From df44626c39608aab22617a28ef9e82637f81c279 Mon Sep 17 00:00:00 2001
From: Mark <mark.github@yandex.ru>
Date: Sun, 5 Jan 2014 06:15:42 +0400
Subject: [PATCH] docs added, guide style added.

---
 docs/guide/README.md                          |   8 ++
 docs/guide/console-fixture.md                 | 105 ++++++++++++++++++
 .../{migration.md => console-migrate.md}      |   0
 docs/guide/{debugger.md => module-debug.md}   |   0
 4 files changed, 113 insertions(+)
 create mode 100644 docs/guide/README.md
 create mode 100644 docs/guide/console-fixture.md
 rename docs/guide/{migration.md => console-migrate.md} (100%)
 rename docs/guide/{debugger.md => module-debug.md} (100%)

diff --git a/docs/guide/README.md b/docs/guide/README.md
new file mode 100644
index 000000000..5717e71bf
--- /dev/null
+++ b/docs/guide/README.md
@@ -0,0 +1,8 @@
+This folder contains official Yii 2 guides documentation.
+
+To add new guide, take the following steps:
+
+1. Create `guide-name` and put there relevant documentation;
+2. If guide has more then one word in name, then it should be with dashes, like: `console-fixture.md`, `module-debug.md`
+3. If your guide is for console commands, than its name should follow convention: `console-{command}.md`
+4. If your guide is for custom modules, than its name should follow convention: `module-{moduleName}.md`
diff --git a/docs/guide/console-fixture.md b/docs/guide/console-fixture.md
new file mode 100644
index 000000000..0ec7401fa
--- /dev/null
+++ b/docs/guide/console-fixture.md
@@ -0,0 +1,105 @@
+Database Fixtures
+=================
+
+Fixtures are important part of testing. Their main purpose is to populate you with data that needed by testing
+different cases. With this data using your tests becoming more efficient and useful.
+
+Yii supports database fixtures via the `yii fixture` command line tool. This tool supports:
+
+* Applying new fixtures to database tables;
+* Clearing, database tables (with sequences);
+* Auto-generating fixtures and populating it with random data.
+
+Fixtures format
+---------------
+
+Fixtures are just plain php files returning array, as follows:
+
+```
+#users.php file under fixtures path
+
+return [
+	[
+		'name' => 'Chase',
+		'login' => 'lmayert',
+		'email' => 'strosin.vernice@jerde.com',
+		'auth_key' => 'K3nF70it7tzNsHddEiq0BZ0i-OU8S3xV',
+		'password' => '$2y$13$WSyE5hHsG1rWN2jV8LRHzubilrCLI5Ev/iK0r3jRuwQEs2ldRu.a2',
+	],
+	[
+		'name' => 'Celestine',
+		'login' => 'napoleon69',
+		'email' => 'aileen.barton@heaneyschumm.com',
+		'auth_key' => 'dZlXsVnIDgIzFgX4EduAqkEPuphhOh9q',
+		'password' => '$2y$13$kkgpvJ8lnjKo8RuoR30ay.RjDf15bMcHIF7Vz1zz/6viYG5xJExU6',
+	],
+];
+```
+
+This data will be loaded to the `users`, but before it will be loaded table `users` will be cleared: all data deleted, sequence reseted.
+Above fixture example was auto-generated by `yii2-faker` extension, read more about it in these [section](#auto-generating-fixtures).
+
+Applying fixtures
+-----------------
+
+To apply fixture to the table, run the following command:
+
+```
+yii fixture/apply <tbl_name>
+```
+
+The required `tbl_name` parameter specifies a database table to which data will be loaded. You can load data to several tables at once.
+Below are correct formats of this command:
+
+```
+// apply fixtures to the "users" table of database
+yii fixture/apply users
+
+// same as above, because default action of "fixture" command is "apply"
+yii fixture users
+
+// apply several fixtures to several tables. Note that there should not be any whitespace between ",", it should be one string.
+yii fixture users,users_profiles
+
+// apply fixtures to the table users, but fixtures will be taken from different path.
+yii fixture users --fixturePath='@app/my/custom/path/to/fixtures'
+
+// apply fixtures to the table users, but for other database connection.
+yii fixtures users --db='customDbConnectionId'
+```
+
+Clearing tables
+---------------
+
+To clear table, run the following command:
+
+```
+// clear given table: delete all data and reset sequence.
+yii fixture/clear users
+
+// clear several tables. Note that there should not be any whitespace between ",", it should be one string.
+yii fixture/clear users,users_profile
+```
+
+Configure Command Globally
+--------------------------
+While command line options allow us to configure the migration command
+on-the-fly, sometimes we may want to configure the command once for all. For example you can configure
+different migration path as follows:
+
+```
+'controllerMap' => [
+    'fixture' => [
+        'class' => 'yii\console\FixtureController',
+        'fixturePath' => '@app/my/custom/path/to/fixtures',
+		'db' => 'customDbConnectionId',
+    ],
+]
+```
+
+Auto-generating fixtures
+------------------------
+
+Yii also can auto-generate fixtures for you based on some template. You can generate your fixtures with different data on different languages and formats.
+These feature is done by [Faker](https://github.com/fzaninotto/Faker) library and `yii2-faker` extension.
+See extension [guide](https://github.com/yiisoft/yii2/tree/master/extensions/yii/faker) for more docs.
diff --git a/docs/guide/migration.md b/docs/guide/console-migrate.md
similarity index 100%
rename from docs/guide/migration.md
rename to docs/guide/console-migrate.md
diff --git a/docs/guide/debugger.md b/docs/guide/module-debug.md
similarity index 100%
rename from docs/guide/debugger.md
rename to docs/guide/module-debug.md