README.md 4.5 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
```
72
# generate fixtures for the users table based on users fixture template
73
php yii fixture/generate users
Mark committed
74

75
# also a short version of this command ("generate" action is default)
76
php yii fixture users
Mark committed
77

78
# to generate several fixtures data files, use "," as a separator, for example:
Mark committed
79
php yii fixture users,profile,some_other_name
Mark committed
80 81 82 83
```

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
84 85
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
86

87
```
Mark committed
88
php yii fixture/generate all
Mark committed
89 90 91 92 93 94 95
```

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).

96
```
97
php yii fixture/generate all 3
Mark committed
98 99 100
```
You can specify different options of this command:

101 102
```
# generate fixtures in russian language
103
php yii fixture/generate users 5 --language='ru_RU'
Mark committed
104

105
# read templates from the other path
106
php yii fixture/generate all --templatePath='@app/path/to/my/custom/templates'
Mark committed
107

108
# generate fixtures into other directory.
Mark committed
109
php yii fixture/generate all --fixtureDataPath='@tests/acceptance/fixtures/data'
Mark committed
110 111
```

112
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
113 114 115 116 117
After you created custom provider, for example:

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

124 125 126 127
    public function ISBN()
    {
        return $this->generator->randomNumber(13);
    }
Mark committed
128 129 130 131

 }
```

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

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