README.md 4.85 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
Another example of valid template:

```php
return [
73 74 75 76
    'name' => 'firstName',
    'phone' => 'phoneNumber',
    'city' => 'city',
    'password' => function ($fixture, $faker, $index) {
77
        $fixture['password'] = Yii::$app->getSecurity()->generatePasswordHash('password_' . $index);
78 79 80
        return $fixture;
    },
    'auth_key' => function ($fixture, $faker, $index) {
81
        $fixture['auth_key'] = Yii::$app->getSecurity()->generateRandomString();
82 83
        return $fixture;
    },
Mark committed
84 85 86
];
```

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

Mark committed
96 97
//to generate several fixtures data files, use "," as a separator, for example:
php yii fixture users,profile,some_other_name
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.
Mark committed
102 103
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
104 105

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

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

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

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

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

130
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
131 132 133 134 135
After you created custom provider, for example:

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

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

 }
```

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

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