README.md 4.84 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
],
```
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
return [
47 48 49 50 51 52 53 54 55 56 57
    [
        'table_column0' => 'faker_formatter',
        ...
        'table_columnN' => 'other_faker_formatter'
        'body' => function ($fixture, $faker, $index) {
            //set needed fixture fields based on different conditions

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

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
Another example of valid template:

```php
use yii\helpers\Security;

return [
75 76 77 78 79 80 81 82 83 84 85
    '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
86 87 88
];
```

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
After you created custom provider, for example:

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

144 145 146 147
    public function ISBN()
    {
        return $this->generator->randomNumber(13);
    }
Mark committed
148 149 150 151

 }
```

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 157 158 159 160 161
    'fixture' => [
        'class' => 'yii\faker\FixtureController',
        'providers' => [
            'app\tests\unit\faker\providers\Book',
        ],
    ],
Mark committed
162
]
Qiang Xue committed
163
```