README.md 4.66 KB
Newer Older
Mark committed
1
Faker Extension for Yii 2
2
=========================
Mark committed
3 4 5

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

6

Mark committed
7 8 9 10 11 12 13 14
Installation
------------

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

Either run

```
15
php composer.phar require --prefer-dist yiisoft/yii2-faker "*"
Mark committed
16 17 18 19 20 21 22 23 24 25
```

or add

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

to the require section of your composer.json.

26

Mark committed
27 28 29 30 31 32 33
Usage
-----

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

```php
'controllerMap' => [
34
	'fixture' => [
Mark committed
35 36 37 38
		'class' => 'yii\faker\FixtureController',
	],
],
```
Mark committed
39 40
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
41
To start using this command you need to be familiar (read guide) for the [Faker](https://github.com/fzaninotto/Faker) library and
Mark committed
42 43 44
generate fixtures template files, according to the given format:

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

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

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

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

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

Mark committed
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
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
89 90 91
After you prepared needed templates for tables you can simply generate your fixtures via command

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

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

Mark committed
98 99
//to generate several fixtures data files, use "," as a separator, for example:
php yii fixture users,profile,some_other_name
Mark committed
100 101 102 103
```

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.
Mark committed
104 105
You can generate fixtures for all templates by specifying keyword ```all```. You dont need to worry about if data file
directory already created or not, if not - it will be created by these command.
Mark committed
106 107

```php
Mark committed
108
php yii fixture/generate all
Mark committed
109 110 111 112 113 114 115 116
```

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
117
php yii fixture/generate all 3
Mark committed
118 119 120 121
```
You can specify different options of this command:

```php
122
//generate fixtures in russian language
123
php yii fixture/generate users 5 --language='ru_RU'
Mark committed
124

125
//read templates from the other path
126
php yii fixture/generate all --templatePath='@app/path/to/my/custom/templates'
Mark committed
127

Mark committed
128 129
//generate fixtures into other directory.
php yii fixture/generate all --fixtureDataPath='@tests/acceptance/fixtures/data'
Mark committed
130 131
```

132
You also can create your own data providers for custom tables fields, see [Faker](https://github.com/fzaninotto/Faker) library guide for more info;
Mark committed
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
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
152
You can use it by adding it to the ```$providers``` property of the current command. In your console.php config:
Mark committed
153 154 155

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