gii.md 5.16 KB
Newer Older
1 2 3
The Gii code generation tool
============================

4
Yii includes a handy tool, named Gii, that provides rapid prototyping by generating commonly used code snippets
5 6
as well as complete CRUD controllers.

Carsten Brandt committed
7

8 9 10
Installing and configuring
--------------------------

11
Gii is an offical Yii extension. The preferred way to install this extension is through
12
[composer](http://getcomposer.org/download/).
Carsten Brandt committed
13

14
You can either run this command:
Carsten Brandt committed
15 16

```
17
php composer.phar require --prefer-dist yiisoft/yii2-gii "*"
Carsten Brandt committed
18 19
```

20
Or you can add this code to the require section of your `composer.json` file:
Carsten Brandt committed
21 22 23 24 25

```
"yiisoft/yii2-gii": "*"
```

26
Once the Gii extension has been installed, you enable it by adding these lines to your application configuration file:
27 28

```php
29
'modules' => [
Carsten Brandt committed
30 31 32
	'gii' => [
		'class' => 'yii\gii\Module',
	],
33
]
34 35
```

Carsten Brandt committed
36 37 38 39 40 41
You can then access Gii through the following URL:

```
http://localhost/path/to/index.php?r=gii
```

42
> Note: if you are accessing gii from an IP address other than localhost, access will be denied by default. To circumvent that default, add the allowed IP addressess to the configuration:
Alexander Makarov committed
43
>
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
```php
'gii' => [
	'class' => 'yii\gii\Module',
	'allowedIPs' => ['127.0.0.1', '::1', '192.168.0.*', '192.168.178.20'] // adjust this to your needs
],
```

### Basic application

In basic application template configuration structure is a bit different so Gii should be configured in
`config/web.php`:

```php
// ...
if (YII_ENV_DEV)
{
	// configuration adjustments for 'dev' environment
	$config['preload'][] = 'debug';
	$config['modules']['debug'] = 'yii\debug\Module';
	$config['modules']['gii'] = 'yii\gii\Module'; // <--- here
}
```

So in order to adjust IP address you need to do it like the following:

```php
if (YII_ENV_DEV)
{
	// configuration adjustments for 'dev' environment
	$config['preload'][] = 'debug';
	$config['modules']['debug'] = 'yii\debug\Module';
	$config['modules']['gii'] = [
		'class' => 'yii\gii\Module',
		'allowedIPs' => ['127.0.0.1', '::1', '192.168.0.*', '192.168.178.20'],
	];
}
```
Carsten Brandt committed
81

82 83 84
How to use it
-------------

Carsten Brandt committed
85 86 87 88 89 90
When you open Gii you first see the entry page that lets you choose a generator.

![Gii entry page](images/gii-entry.png)

By default there are the following generators available:

Carsten Brandt committed
91 92
- **Model Generator** - This generator generates an ActiveRecord class for the specified database table.
- **CRUD Generator** - This generator generates a controller and views that implement CRUD (Create, Read, Update, Delete)
Carsten Brandt committed
93
  operations for the specified data model.
Carsten Brandt committed
94
- **Controller Generator** - This generator helps you to quickly generate a new controller class, one or several
Carsten Brandt committed
95
  controller actions and their corresponding views.
Carsten Brandt committed
96
- **Form Generator** - This generator generates a view script file that displays a form to collect input for the
Carsten Brandt committed
97
  specified model class.
Carsten Brandt committed
98
- **Module Generator** - This generator helps you to generate the skeleton code needed by a Yii module.
Carsten Brandt committed
99 100 101 102 103 104 105 106 107 108 109 110

After choosing a generator by clicking on the "Start" button you will see a form that allows you to configure the
parameters of the generator. Fill out the form according to your needs and press the "Preview" button to get a
preview of the code that gii is about to generated. Dependend on the generator you chose and whether the files
already existed or not you will get an ouput similar to what you see in the following picuture:

![Gii preview](images/gii-preview.png)

Clicking on the file name you can view a preview of the code that will be generated for that file.
When the file already exists, gii also provides a diff view that shows what is different between the code that exists
and the one that will be generated. In this case you can also choose which files should be overridden and which not.

Carsten Brandt committed
111 112 113 114 115
> Tip: When using the Model Generator to update models after database change, you can copy the code from gii preview
  and merge the changes with your own code. You can use IDE features like PHPStorms
  [compare with clipboard](http://www.jetbrains.com/phpstorm/webhelp/comparing-files.html) for this,
  which allows you to merge in relevant changes and leave out others that may revert your own code.

Carsten Brandt committed
116 117 118
After you have reviewed the code and selected the files to be generated you can click the "Generate" button to create
the files. If all went fine you are done. When you see errors that gii is not able to generate the files you have to
adjust directory permissions so that your webserver is able to write to the directories and create the files.
119 120 121 122

> Note: The code generated by gii is only a template that has to be adjusted to your needs. It is there
  to help you create new things quickly but it is not something that creates ready to use code.
  We often see people using the models generated by gii without change and just extend them to adjust
123
  some parts of it. This is not how it is meant to be used. Code generated by gii may be incomplete or incorrect
124 125
  and has to be changed to fit your needs before you can use it.

Carsten Brandt committed
126

127 128 129
Creating your own templates
---------------------------

Carsten Brandt committed
130 131 132 133 134
Every generator has a form field that lets you choose a template to use for code generation.
By default gii only provides one template but you can create your own templates that are adjusted to your needs.

TBD

Carsten Brandt committed
135

Carsten Brandt committed
136 137 138
Creating your own generators
----------------------------

139
TBD
140