start-gii.md 5.61 KB
Newer Older
1 2 3
Generating Code with Gii
========================

Larry Ullman committed
4 5
This section will describe how to use [Gii](tool-gii.md) to automatically generate  code
that implements some common Web site features. Using Gii to auto-generate code is simply a matter of entering the right information per to the instructions shown on the Gii Web pages.
Qiang Xue committed
6

Larry Ullman committed
7
Through this tutorial, you will learn how to:
Qiang Xue committed
8

Larry Ullman committed
9 10 11 12
* Enable Gii in your application
* Use Gii to generate an Active Record class
* Use Gii to generate the code implementing the CRUD operations for a DB table
* Customize the code generated by Gii
Qiang Xue committed
13 14


Qiang Xue committed
15
Starting Gii <a name="starting-gii"></a>
Qiang Xue committed
16 17
------------

Larry Ullman committed
18 19
[Gii](tool-gii.md) is provided in Yii as a [module](structure-modules.md). You can enable Gii
by configuring it in the [[yii\base\Application::modules|modules]] property of the application. Depending upon how you created your application, you may find the following code is already provided in the `config/web.php` configuration file:
Qiang Xue committed
20 21 22 23 24 25 26 27 28 29 30

```php
$config = [ ... ];

if (YII_ENV_DEV) {
    $config['bootstrap'][] = 'gii';
    $config['modules']['gii'] = 'yii\gii\Module';
}
```

The above configuration states that when in [development environment](concept-configurations.md#environment-constants),
Larry Ullman committed
31
the application should include a module named `gii`, which is of class [[yii\gii\Module]].
Qiang Xue committed
32 33

If you check the [entry script](structure-entry-scripts.md) `web/index.php` of your application, you will
Larry Ullman committed
34
find the following line, which essentially makes `YII_ENV_DEV` to be true.
Qiang Xue committed
35 36 37 38 39

```php
defined('YII_ENV') or define('YII_ENV', 'dev');
```

Larry Ullman committed
40
Thanks to that line, your application is in development mode, and will have already enabled Gii, per the above configuration. You can now access Gii via the following URL:
Qiang Xue committed
41 42 43 44 45

```
http://hostname/index.php?r=gii
```

46 47
> Note: If you are accessing Gii from a machine other than localhost, the access will be denied by default
> for security purpose. You can configure Gii to add the allowed IP addresses as follows,
48 49 50 51 52 53 54 55
>
```php
'gii' => [
    'class' => 'yii\gii\Module',
    'allowedIPs' => ['127.0.0.1', '::1', '192.168.0.*', '192.168.178.20'] // adjust this to your needs
],
```

56 57
![Gii](images/start-gii.png)

Qiang Xue committed
58

Qiang Xue committed
59
Generating an Active Record Class <a name="generating-ar"></a>
Qiang Xue committed
60 61
---------------------------------

Larry Ullman committed
62
To use Gii to generate an Active Record class, select the "Model Generator" (by clicking the link on the Gii index page). Then fill out the form as follows:
Qiang Xue committed
63 64 65 66

* Table Name: `country`
* Model Class: `Country`

67 68
![Model Generator](images/start-gii-model.png)

Larry Ullman committed
69
Next, click on the "Preview" button. You will see `models/Country.php` is listed in the resulting class file to be created. You may click on the name of the class file to preview its content.
Qiang Xue committed
70

Larry Ullman committed
71 72 73
When using Gii, if you have already created the same file and would be overwriting it, click
the `diff` button next to the file name to see the differences between the code to be generated
and the existing version.
Qiang Xue committed
74

75 76
![Model Generator Preview](images/start-gii-model-preview.png)

Larry Ullman committed
77 78 79 80
When overwriting an existing file, check the box next to "overwrite" and then click  the "Generate" button. If creating a new file, you can just click "Generate". 

Next, you will see
a confirmation page indicating the code has been successfully generated. If you had an existing file, you'll also see a message indicating that it was overwritten with the newly generated code.
Qiang Xue committed
81 82


Qiang Xue committed
83
Generating CRUD Code <a name="generating-crud"></a>
Qiang Xue committed
84 85
--------------------

Larry Ullman committed
86
CRUD stands for Create, Read, Update, and Delete, representing the four common tasks taken with data on most Web sites. To create CRUD functionality using Gii, select the "CRUD Generator" (by clicking the link on the Gii index page). For the "country" example, fill out the resulting form as follows:
Qiang Xue committed
87 88 89 90 91

* Model Class: `app\models\Country`
* Search Model Class: `app\models\CountrySearch`
* Controller Class: `app\controllers\CountryController`

92
![CRUD Generator](images/start-gii-crud.png)
Qiang Xue committed
93

Larry Ullman committed
94 95
Next, click on the "Preview" button. You will see a list of files to be generated, as shown below.

96
![CRUD Generator Preview](images/start-gii-crud-preview.png)
Qiang Xue committed
97

Larry Ullman committed
98 99
If you previously created the `controllers/CountryController.php` and
`views/country/index.php` files (in the databases section of the guide), check the "overwrite" box to replace them. (The previous versions did not have full CRUD support.)
Qiang Xue committed
100 101


Qiang Xue committed
102 103
Trying it Out <a name="trying-it-out"></a>
-------------
Qiang Xue committed
104 105 106 107 108 109 110

To see how it works, use your browser to access the following URL:

```
http://hostname/index.php?r=country/index
```

Larry Ullman committed
111
You will see a data grid showing the countries from the database table. You may sort the grid,
Qiang Xue committed
112 113
or filter it by entering filter conditions in the column headers.

Larry Ullman committed
114 115
For each country displayed in the grid, you may choose to view its details, update it, or delete it.
You may also click on the "Create Country" button on top of the grid to be provided with a form for creating a new country.
Qiang Xue committed
116

117 118 119 120
![Data Grid of Countries](images/start-gii-country-grid.png)

![Updating a Country](images/start-gii-country-update.png)

Larry Ullman committed
121 122
The following is the list of the files generated by Gii, in case you want to investigate how these features are implemented,
or to customize them:
Qiang Xue committed
123 124 125 126 127 128 129 130 131 132

* Controller: `controllers/CountryController.php`
* Models: `models/Country.php` and `models/CountrySearch.php`
* Views: `views/country/*.php`

> Info: Gii is designed to be a highly customizable and extensible code generation tool. Using it wisely
  can greatly accelerate your application development speed. For more details, please refer to
  the [Gii](tool-gii.md) section.


Qiang Xue committed
133
Summary <a name="summary"></a>
Qiang Xue committed
134 135
-------

Larry Ullman committed
136 137
In this section, you have learned how to use Gii to generate the code that implements complete
CRUD functionality for content stored in a database table.