Refreshed docs & readme

Sylius · Feb 26, 2019 · ebcdaa7 · ebcdaa7
1 parent 0d28cce
commit ebcdaa7
Show file tree

Hide file tree

Showing 8 changed files with 506 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -1,47 +1,26 @@
-SyliusFixturesBundle [![Build status...](https://secure.travis-ci.org/Sylius/SyliusFixturesBundle.png?branch=master)](http://travis-ci.org/Sylius/SyliusFixturesBundle)
-====================
+<p align="center">
+    <a href="https://sylius.com" target="_blank">
+        <img src="https://demo.sylius.com/assets/shop/img/logo.png" />
+    </a>
+</p>
 
-Configurable fixtures for Symfony2 applications.
+<h1 align="center">Fixtures Bundle</h1>
 
-Sylius
-------
+<p align="center">Configurable fixtures for Symfony applications.</p>
 
-![Sylius](https://demo.sylius.com/assets/shop/img/logo.png)
+## Documentation
 
-Sylius is an Open Source eCommerce solution built from decoupled components with powerful API and the highest quality code. [Read more on sylius.com](http://sylius.com).
+[Documentation is available in the *docs* folder.](docs/index.md)
 
-Documentation
--------------
+## Security issues
 
-Documentation is available on [**docs.sylius.com**](http://docs.sylius.com/en/latest/components_and_bundles/bundles/SyliusFixturesBundle/index.html).
+Please use `security@sylius.com` email to report security issues.
 
-Contributing
-------------
+## License
 
-[This page](http://docs.sylius.com/en/latest/contributing/index.html) contains all the information about contributing to Sylius.
+[This bundle uses MIT License.](LICENSE)
 
-Follow Sylius' Development
---------------------------
+## Authors
 
-If you want to keep up with the updates and latest features, follow us on the following channels:
-
-* [Official Blog](https://sylius.com/blog)
-* [Sylius on Twitter](https://twitter.com/Sylius)
-* [Sylius on Facebook](https://facebook.com/SyliusEcommerce)
-
-Bug tracking
-------------
-
-Sylius uses [GitHub issues](https://github.com/Sylius/Sylius/issues).
-If you have found bug, please create an issue.
-
-MIT License
------------
-
-License can be found [here](https://github.com/Sylius/Sylius/blob/master/LICENSE).
-
-Authors
--------
-
-The bundle was originally created by [Kamil Kokot](http://kamil.kokot.me).
-See the list of [contributors](https://github.com/Sylius/Sylius/contributors).
+The bundle was originally created by [Kamil Kokot](https://kamil.kokot.me).
+See the list of [contributors](https://github.com/Sylius/SyliusThemeBundle/contributors).
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -0,0 +1,122 @@
+## Architecture
+
+Flexibility is one of the key concepts of **SyliusFixturesBundle**. This article aims to explain what design decisions
+were made in order to achieve it.
+
+### Suites
+
+Suites are collections of configured fixtures. They allow you to define different sets (for example - `staging`,
+`development` or `big_shop`) that can be loaded independently. They are defined through YAML configuration:
+
+```yaml
+sylius_fixtures:
+    suites:
+        my_suite_name: # Suite name as a key
+            listeners: ~
+            fixtures: ~
+```
+
+### Fixtures
+
+Fixtures are just plain old PHP objects, that change system state during their execution - they can either
+persist some entities in the database, upload some files, dispatch some events or do anything you think is needed.
+
+```yaml
+sylius_fixtures:
+    suites:
+        my_suite_name:
+            fixtures:
+                my_fixture: # Fixture name as a key
+                    priority: 0 # The higher priority is, the sooner the fixture will be executed
+                    options: ~ # Fixture options
+```
+
+They implement the `Sylius\Bundle\FixturesBundle\Fixture\FixtureInterface` and need to be registered under
+the `sylius_fixtures.fixture` tag in order to be used in suite configuration.
+
+#### Using a fixture multiple times in a single suite
+
+In order to use the same fixture multiple times in a single suite, it is needed to alias them:
+
+```yaml
+sylius_fixtures:
+    suites:
+        my_suite_name:
+            regular_user: # Fixture alias as a key
+                name: user # Fixture name
+                options:
+                    admin: false
+                    amount: 10
+
+            admin_user: # Fixture alias as a key
+                name: user # Fixture name
+                options:
+                    admin: true
+                    amount: 2
+```
+
+Both `regular_user` and `admin_user` are the aliases for `user` fixture. They will run the same fixture, but with
+different options being submitted.
+
+### Listeners
+
+Listeners allow you to execute code at some point of fixtures loading.
+
+```yaml
+sylius_fixtures:
+    suites:
+        my_suite_name:
+            listeners:
+                my_listener: # Listener name as a key
+                    priority: 0 # The higher priority is, the sooner the fixture will be executed
+                    options: ~ # Listener options
+```
+
+They implement at least one of four interfaces:
+
+ * `Sylius\Bundle\FixturesBundle\Listener\BeforeSuiteListenerInterface` - receives `Sylius\Bundle\FixturesBundle\Listener\SuiteEvent` as an argument
+ * `Sylius\Bundle\FixturesBundle\Listener\BeforeFixtureListenerInterface`  - receives `Sylius\Bundle\FixturesBundle\Listener\FixtureEvent` as an argument
+ * `Sylius\Bundle\FixturesBundle\Listener\AfterFixtureListenerInterface` - receives `Sylius\Bundle\FixturesBundle\Listener\FixtureEvent` as an argument
+ * `Sylius\Bundle\FixturesBundle\Listener\AfterSuiteListenerInterface`  - receives `Sylius\Bundle\FixturesBundle\Listener\SuiteEvent` as an argument
+
+In order to be used in suite configuration, they need to be registered under the `sylius_fixtures.listener`.
+
+### Disabling listeners / fixtures in consecutive configurations
+
+Given the following configuration coming from a third party (like Sylius if you're developing an application based on it):
+
+```yaml
+sylius_fixtures:
+    suites:
+        my_suite_name:
+            listeners:
+                first_listener: ~
+                second_listener: ~
+            fixtures:
+                first_fixture: ~
+                second_fixture: ~
+```
+
+It is possible to disable a listener or a fixture in a consecutive configuration by providing `false` as its value:
+
+```yaml
+sylius_fixtures:
+    suites:
+        my_suite_name:
+            listeners:
+                second_listener: false
+            fixtures:
+                second_fixture: false
+```
+
+These two configurations combined will be treated as a single configuration like:
+
+```yaml
+sylius_fixtures:
+    suites:
+        my_suite_name:
+            listeners:
+                first_listener: ~
+            fixtures:
+                first_fixture: ~
+```
diff --git a/docs/builtin_listeners.md b/docs/builtin_listeners.md
@@ -0,0 +1,81 @@
+## Built-in listeners
+
+**SyliusFixturesBundle** comes with a few useful listeners.
+
+### Logger (`logger`)
+
+Provides output while running `sylius:fixtures:load` command.
+
+```
+# Without logger
+
+$ bin/console sylius:fixtures:load my_suite
+$ _
+
+# With logger
+
+$ bin/console sylius:fixtures:load my_suite
+Running suite "my_suite"...
+Running fixture "country"...
+Running fixture "locale"...
+Running fixture "currency"...
+$ _
+```
+
+The logger does not have any configuration options. It can be enabled in such a way:
+
+```yaml
+sylius_fixtures:
+    suites:
+        my_suite:
+            listeners:
+                logger: ~
+```
+
+### ORM Purger (`orm_purger`)
+
+Purges the relational database. Uses `delete` purge mode and the default entity manager if not configured otherwise.
+
+Configuration options:
+
+ * `mode` - sets how database is purged, available values: `delete` (default), `truncate`
+ * `managers` - an array of entity managers' names used to purge the database, `[null]` by default
+ * `exclude` - an array of table/view names to be excluded from purge, `[]` by default
+
+Example configuration:
+
+```yaml
+sylius_fixtures:
+    suites:
+        my_suite:
+            listeners:
+                orm_purger:
+                    options:
+                        mode: truncate
+                        managers:
+                            - custom_manager
+                        exclude:
+                            - custom_entity_table_name
+```
+
+### PHPCR / MongoDB Purger (`phpcr_purger` / `mongodb_purger`)
+
+Purges the document database. Uses the default document manager if not configured otherwise.
+
+Configuration options:
+
+ * `managers` - an array of document managers' names used to purge the database, `[null]` by default
+
+Example configuration:
+
+```yaml
+sylius_fixtures:
+    suites:
+        my_suite:
+            listeners:
+                phpcr_purger:
+                    options:
+                        managers:
+                            - custom_manager # Uses custom document manager
+                mongodb_purger: ~ # Uses default document manager
+```
diff --git a/docs/commands.md b/docs/commands.md
@@ -0,0 +1,31 @@
+## Commands
+
+### Listing fixtures
+
+To list all available suites and fixtures, use the `sylius:fixtures:list` command.
+
+```
+$ bin/console sylius:fixtures:list
+
+Available suites:
+ - default
+ - dev
+ - test
+Available fixtures:
+ - country
+ - locale
+ - currency
+```
+
+### Loading fixtures
+
+To load a suite, use the `sylius:fixtures:load [suite]` command.
+
+```
+$ bin/console sylius:fixtures:load default
+
+Running suite "default"...
+Running fixture "country"...
+Running fixture "locale"...
+Running fixture "currency"...
+```