README.md 4.38 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 35 36
    'fixture' => [
        'class' => 'yii\faker\FixtureController',
    ],
Mark committed
37 38
],
```
39 40 41 42 43

Define a `tests` alias in your console config. For example, for the `basic` application template, this should be added
to the `console.php` configuration: `Yii::setAlias('tests', __DIR__ . '/../tests');`
To start using this command you need to be familiar (read guide) with the [Faker](https://github.com/fzaninotto/Faker) library and
generate fixture template files, according to the given format:
Mark committed
44 45

```php
46 47 48 49 50
// users.php file under template path (by default @tests/unit/templates/fixtures)
/**
 * @var $faker \Faker\Generator
 * @var $index integer
 */
Mark committed
51
return [
52 53 54 55 56 57
    'name' => $faker->firstName,
    'phone' => $faker->phoneNumber,
    'city' => $faker->city,
    'password' => Yii::$app->getSecurity()->generatePasswordHash('password_' . $index),
    'auth_key' => Yii::$app->getSecurity()->generateRandomString(),
    'intro' => $faker->sentence(7, true),  // generate a sentence with 7 words
Mark committed
58 59 60
];
```

61 62 63 64
As you can see, the template file is just a regular PHP script. The script should return an array of key-value
pairs, where the keys represent the table column names and the values the corresponding value. When you run
the `fixture/generate` command, the script will be executed once for every data row being generated.
In this script, you can use the following two predefined variables:
Mark committed
65

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

69
With such a template file, you can generate your fixtures using the commands like the following:
Mark committed
70

Mark committed
71
```
Mark committed
72 73
# generate fixtures from user fixture template
php yii fixture/generate user
Mark committed
74

Qiang Xue committed
75
# to generate several fixture data files
Mark committed
76
php yii fixture/generate user profile team
Mark committed
77 78
```

Qiang Xue committed
79 80
In the code above `users` is template name. After running this command, a new file with the same template name
will be created under the fixture path in the `@tests/unit/fixtures`) folder.
Mark committed
81

82
```
Qiang Xue committed
83
php yii fixture/generate-all
Mark committed
84 85 86 87
```

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.
Qiang Xue committed
88
You can specify how many fixtures per file you need by the `--count` option. In the code below we generate
Mark committed
89 90
all fixtures and in each file there will be 3 rows (fixtures).

91
```
Qiang Xue committed
92
php yii fixture/generate-all --count=3
Mark committed
93 94 95
```
You can specify different options of this command:

96 97
```
# generate fixtures in russian language
Qiang Xue committed
98
php yii fixture/generate User --count=5 --language='ru_RU'
Mark committed
99

100
# read templates from the other path
Qiang Xue committed
101
php yii fixture/generate-all --templatePath='@app/path/to/my/custom/templates'
Mark committed
102

103
# generate fixtures into other directory.
Qiang Xue committed
104
php yii fixture/generate-all --fixtureDataPath='@tests/acceptance/fixtures/data'
Mark committed
105 106
```

Mark committed
107 108 109 110 111 112 113 114 115 116
You can see all available templates by running command:

```
# list all templates under default template path (i.e. '@tests/unit/templates/fixtures')
php yii fixture/templates

# list all templates under specified template path
php yii fixture/templates --templatePath='@app/path/to/my/custom/templates'
```

117
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
118 119 120 121 122
After you created custom provider, for example:

```php
class Book extends \Faker\Provider\Base
{
Mark committed
123

124 125 126 127 128
    public function title($nbWords = 5)
    {
        $sentence = $this->generator->sentence($nbWords);
        return mb_substr($sentence, 0, mb_strlen($sentence) - 1);
    }
Mark committed
129 130 131 132

 }
```

133
You can use it by adding it to the `$providers` property of the current command. In your console.php config:
Mark committed
134 135 136

```php
'controllerMap' => [
137 138 139 140 141 142
    'fixture' => [
        'class' => 'yii\faker\FixtureController',
        'providers' => [
            'app\tests\unit\faker\providers\Book',
        ],
    ],
Mark committed
143
]
Qiang Xue committed
144
```