123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147
  1. Faker Extension for Yii 2
  2. =========================
  3. This extension provides a [`Faker`](https://github.com/fzaninotto/Faker) fixture command for Yii 2.
  4. This repository is a git submodule of <https://github.com/yiisoft/yii2>.
  5. Please submit issue reports and pull requests to the main repository.
  6. For license information check the [LICENSE](LICENSE.md)-file.
  7. Installation
  8. ------------
  9. The preferred way to install this extension is through [composer](http://getcomposer.org/download/).
  10. Either run
  11. ```
  12. php composer.phar require --prefer-dist yiisoft/yii2-faker
  13. ```
  14. or add
  15. ```json
  16. "yiisoft/yii2-faker": "~2.0.0"
  17. ```
  18. to the require section of your composer.json.
  19. Usage
  20. -----
  21. To use this extension, simply add the following code in your application configuration (console.php):
  22. ```php
  23. 'controllerMap' => [
  24. 'fixture' => [
  25. 'class' => 'yii\faker\FixtureController',
  26. ],
  27. ],
  28. ```
  29. Define a `tests` alias in your console config. For example, for the `basic` application template, this should be added
  30. to the `console.php` configuration: `Yii::setAlias('tests', __DIR__ . '/../tests');`
  31. To start using this command you need to be familiar (read guide) with the [Faker](https://github.com/fzaninotto/Faker) library and
  32. generate fixture template files, according to the given format:
  33. ```php
  34. // users.php file under template path (by default @tests/unit/templates/fixtures)
  35. /**
  36. * @var $faker \Faker\Generator
  37. * @var $index integer
  38. */
  39. return [
  40. 'name' => $faker->firstName,
  41. 'phone' => $faker->phoneNumber,
  42. 'city' => $faker->city,
  43. 'password' => Yii::$app->getSecurity()->generatePasswordHash('password_' . $index),
  44. 'auth_key' => Yii::$app->getSecurity()->generateRandomString(),
  45. 'intro' => $faker->sentence(7, true), // generate a sentence with 7 words
  46. ];
  47. ```
  48. As you can see, the template file is just a regular PHP script. The script should return an array of key-value
  49. pairs, where the keys represent the table column names and the values the corresponding value. When you run
  50. the `fixture/generate` command, the script will be executed once for every data row being generated.
  51. In this script, you can use the following two predefined variables:
  52. * `$faker`: the Faker generator instance
  53. * `$index`: the current fixture index. For example if user need to generate 3 fixtures for user table, it will be 0..2.
  54. With such a template file, you can generate your fixtures using the commands like the following:
  55. ```
  56. # generate fixtures from user fixture template
  57. php yii fixture/generate user
  58. # to generate several fixture data files
  59. php yii fixture/generate user profile team
  60. ```
  61. In the code above `users` is template name. After running this command, a new file with the same template name
  62. will be created under the fixture path in the `@tests/unit/fixtures`) folder.
  63. ```
  64. php yii fixture/generate-all
  65. ```
  66. This command will generate fixtures for all template files that are stored under template path and
  67. store fixtures under fixtures path with file names same as templates names.
  68. You can specify how many fixtures per file you need by the `--count` option. In the code below we generate
  69. all fixtures and in each file there will be 3 rows (fixtures).
  70. ```
  71. php yii fixture/generate-all --count=3
  72. ```
  73. You can specify different options of this command:
  74. ```
  75. # generate fixtures in russian language
  76. php yii fixture/generate User --count=5 --language='ru_RU'
  77. # read templates from the other path
  78. php yii fixture/generate-all --templatePath='@app/path/to/my/custom/templates'
  79. # generate fixtures into other directory.
  80. php yii fixture/generate-all --fixtureDataPath='@tests/acceptance/fixtures/data'
  81. ```
  82. You can see all available templates by running command:
  83. ```
  84. # list all templates under default template path (i.e. '@tests/unit/templates/fixtures')
  85. php yii fixture/templates
  86. # list all templates under specified template path
  87. php yii fixture/templates --templatePath='@app/path/to/my/custom/templates'
  88. ```
  89. You also can create your own data providers for custom tables fields, see [Faker](https://github.com/fzaninotto/Faker) library guide for more info;
  90. After you created custom provider, for example:
  91. ```php
  92. class Book extends \Faker\Provider\Base
  93. {
  94. public function title($nbWords = 5)
  95. {
  96. $sentence = $this->generator->sentence($nbWords);
  97. return mb_substr($sentence, 0, mb_strlen($sentence) - 1);
  98. }
  99. }
  100. ```
  101. You can use it by adding it to the `$providers` property of the current command. In your console.php config:
  102. ```php
  103. 'controllerMap' => [
  104. 'fixture' => [
  105. 'class' => 'yii\faker\FixtureController',
  106. 'providers' => [
  107. 'app\tests\unit\faker\providers\Book',
  108. ],
  109. ],
  110. ]
  111. ```