Merge pull request #139 from cleverage/138

#138 - Document the Symfony Flex recipe

Author: njoubert-cleverage

CHANGELOG.md

@@ -1,6 +1,9 @@
 Latest
 ------
 
+## Changes
+* [#138](https://github.com/cleverage/ui-process-bundle/issues/138) Installation documentation: describe the Symfony Flex recipe, which registers the bundle, imports the bundle controllers routes (`config/routes/clever_age_ui_process.yaml`, the EasyAdmin routes being imported by the EasyAdmin recipe) and creates `config/packages/clever_age_ui_process.yaml`, and the manual setup without Flex.
+
 v3.3
 ------
 

docs/index.md

@@ -50,7 +50,14 @@ Open a command console, enter your project directory and install it using compos
 composer require cleverage/ui-process-bundle
 ```
 
-Remember to add the following line to `config/bundles.php` (not required if Symfony Flex is used)
+With [Symfony Flex](https://symfony.com/doc/current/setup/flex.html), the
+[recipe](https://github.com/symfony/recipes-contrib/tree/main/cleverage/ui-process-bundle) registers the bundle,
+imports its routes (`config/routes/clever_age_ui_process.yaml`) and creates its configuration
+(`config/packages/clever_age_ui_process.yaml`, see [configuration](#configuration)). The recipes of its dependencies
+configure the security password hasher and the Doctrine naming strategy expected below: go straight to the
+[database](#database) step.
+
+Without Flex, add the following line to `config/bundles.php`, then follow the quick setup:
 
 ```php
 CleverAge\UiProcessBundle\CleverAgeUiProcessBundle::class => ['all' => true],
@@ -61,12 +68,24 @@ CleverAge\UiProcessBundle\CleverAgeUiProcessBundle::class => ['all' => true],
 ### Import routes
 
 ```yaml
-# config/routes.yaml
-ui-process-bundle:
+# config/routes/clever_age_ui_process.yaml
+clever_age_ui_process:
     resource: '@CleverAgeUiProcessBundle/config/routes/*.yaml'
 ```
 
-This imports the bundle controllers and the EasyAdmin routes (do not import `easyadmin.routes` a second time).
+This imports the bundle controllers and the EasyAdmin routes (do not import `easyadmin.routes` a second time). If
+EasyAdmin routes are already imported (e.g. `config/routes/easyadmin.yaml`, created by the EasyAdmin recipe), import
+only the controllers, as the recipe does:
+
+```yaml
+# config/routes/clever_age_ui_process.yaml
+clever_age_ui_process:
+    resource: '@CleverAgeUiProcessBundle/config/routes/controllers.yaml'
+```
+
+The former route names, deprecated since 3.3, are then not defined: if your application still uses them, also import
+`@CleverAgeUiProcessBundle/config/routes/deprecated_aliases.yaml`.
+
 See [routes](reference/03-users_and_security.md#routes).
 
 ### Security

docs/reference/03-users_and_security.md

@@ -130,7 +130,9 @@ the previous one. It is used to authenticate on the [HTTP API](06-http_api.md).
 Routes
 ------
 
-Routes are imported with `@CleverAgeUiProcessBundle/config/routes/*.yaml` (see [installation](../index.md#import-routes)).
+Routes are imported with `@CleverAgeUiProcessBundle/config/routes/*.yaml`, or
+`@CleverAgeUiProcessBundle/config/routes/controllers.yaml` when the EasyAdmin routes are already imported, as done by the
+Symfony Flex recipe (see [installation](../index.md#import-routes)).
 
 | Route name                          | Former name (deprecated) | Path                             | Description                                                                                  |
 |-------------------------------------|--------------------------|----------------------------------|----------------------------------------------------------------------------------------------|
@@ -147,7 +149,8 @@ The routes of the CRUD pages are generated by EasyAdmin from the dashboard route
 
 The former route names are deprecated aliases since 3.3 (`config/routes/deprecated_aliases.yaml`), removed in 4.0:
 generating a URL with them, or opening a `?routeName=<former name>` URL of the dashboard, still works and triggers a
-deprecation.
+deprecation. They are not defined when only `controllers.yaml` is imported (Symfony Flex recipe): import
+`deprecated_aliases.yaml` too if your application still uses them.
 
 The EasyAdmin routes (the dashboard and its CRUD pages) are generated by the `easyadmin.routes` loader imported by
 `config/routes/easyadmin.yaml`. This loader generates the routes of **every** dashboard, including the ones of your