README.md 4.63 KB
Newer Older
Mark committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
Faker Extension for Yii 2
===============================

This extension provides a [`Faker`](https://github.com/fzaninotto/Faker) fixture command for Yii 2.

Installation
------------

The preferred way to install this extension is through [composer](http://getcomposer.org/download/).

Either run

```
php composer.phar require yiisoft/yii2-faker "*"
```

or add

```json
"yiisoft/yii2-faker": "*"
```

to the require section of your composer.json.

Usage
-----

To use this extension,  simply add the following code in your application configuration (console.php):

```php
'controllerMap' => [
32
	'fixture' => [
Mark committed
33 34 35 36
		'class' => 'yii\faker\FixtureController',
	],
],
```
Mark committed
37 38
Set valid ```test``` alias in your console config, for example for ```basic``` application template, this should be added
to ```console.php``` config: ```Yii::setAlias('tests', __DIR__ . '/../tests');```
Mark committed
39
To start using this command you need to be familiar (read guide) for the [Faker](https://github.com/fzaninotto/Faker) library and
Mark committed
40 41 42
generate fixtures template files, according to the given format:

```php
43
//users.php file under template path (by default @tests/unit/templates/fixtures)
Mark committed
44 45 46 47
return [
	[
		'table_column0' => 'faker_formatter',
		...
Mark committed
48
		'table_columnN' => 'other_faker_formatter'
Mark committed
49
		'body' => function ($fixture, $faker, $index) {
Mark committed
50
			//set needed fixture fields based on different conditions
Mark committed
51

52
			$fixture['body'] = $faker->sentence(7,true); //generate sentence exact with 7 words.
Mark committed
53 54 55 56 57 58 59 60
			return $fixture;
		}
	],
];
```

If you use callback as a attribute value, then it will be called as shown with three parameters:

Mark committed
61 62 63
* ```$fixture``` - current fixture array. 
* ```$faker``` - faker generator instance
* ```$index``` - current fixture index. For example if user need to generate 3 fixtures for tbl_user, it will be 0..2.
Mark committed
64 65 66

After you set all needed fields in callback, you need to return $fixture array back from the callback.

Mark committed
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
Another example of valid template:

```php
use yii\helpers\Security;

return [
	'name' => 'firstName',
	'phone' => 'phoneNumber',
	'city' => 'city',
	'password' => function ($fixture, $faker, $index) {
		$fixture['password'] = Security::generatePasswordHash('password_' . $index);
		return $fixture;
	},
	'auth_key' => function ($fixture, $faker, $index) {
		$fixture['auth_key'] = Security::generateRandomKey();
		return $fixture;
	},
];
```

Mark committed
87 88 89
After you prepared needed templates for tables you can simply generate your fixtures via command

```php
90
//generate fixtures for the users table based on users fixture template
91
php yii fixture/generate users
Mark committed
92

93
//also a short version of this command ("generate" action is default)
94
php yii fixture users
Mark committed
95 96

//to generate fixtures for several tables, use "," as a separator, for example:
97
php yii fixture users,profile,some_other_table
Mark committed
98 99 100 101
```

In the code above "users" is template name, after this command run, new file named same as template
will be created under the fixtures path (by default ```@tests/unit/fixtures```) folder.
102
You can generate fixtures for all templates by specifying keyword ```all```.
Mark committed
103 104

```php
105
php yii fixture/generate all_fixtures
Mark committed
106 107 108 109 110 111 112 113
```

This command will generate fixtures for all template files that are stored under template path and 
store fixtures under fixtures path with file names same as templates names.
You can specify how many fixtures per file you need by the second parameter. In the code below we generate
all fixtures and in each file there will be 3 rows (fixtures).

```php
114
php yii fixture/generate all 3
Mark committed
115 116 117 118
```
You can specify different options of this command:

```php
119
//generate fixtures in russian language
120
php yii fixture/generate users 5 --language='ru_RU'
Mark committed
121

122
//read templates from the other path
123
php yii fixture/generate all --templatePath='@app/path/to/my/custom/templates'
Mark committed
124

125
//generate fixtures into other folders, but be sure that this folders exists or you will get notice about that.
Qiang Xue committed
126
php yii fixture/generate all --fixturePath='@tests/unit/fixtures/subfolder1/subfolder2/subfolder3'
Mark committed
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
```

You also can create your own data providers for custom tables fields, see [Faker]((https://github.com/fzaninotto/Faker)) library guide for more info;
After you created custom provider, for example:

```php
class Book extends \Faker\Provider\Base
{
	public function title($nbWords = 5)
	{
		$sentence = $this->generator->sentence($nbWords);
		return mb_substr($sentence, 0, mb_strlen($sentence) - 1);
	}

	public function ISBN()
	{
		return $this->generator->randomNumber(13);
	}

 }
```

Mark committed
149
You can use it by adding it to the ```$providers``` property of the current command. In your console.php config:
Mark committed
150 151 152

```php
'controllerMap' => [
153
	'fixture' => [
Mark committed
154 155 156 157 158 159
		'class' => 'yii\faker\FixtureController',
		'providers' => [
			'app\tests\unit\faker\providers\Book',
		],
	],
]
Qiang Xue committed
160
```