Update documentation

rollerworks · Aug 26, 2017 · ebdcd33 · ebdcd33
1 parent 77b0ff6
commit ebdcd33
Showing 1 changed file with 71 additions and 30 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,43 +1,76 @@
-Password blacklisting
-=====================
+Bundle configuration reference
+==============================
 
-The `\Rollerworks\Component\PasswordStrength\Validator\Constraints\Blacklist` constraint requires
+## Blacklist
+
+The `Rollerworks\Component\PasswordStrength\Validator\Constraints\Blacklist` constraint requires
 you configure a blacklist provider. Otherwise any password will be considered valid.
 
-## Configuration
+See also https://github.com/rollerworks/PasswordStrengthValidator/blob/master/docs/blacklist.md
+for a complete manual on using this constraint.
 
-First you need to configure a blacklist provider.
+**New since 2.0:**
 
-**Tip.** You can use the ChainProvider to yse multiple providers at once.
+> Since 2.0 the `Blacklist` constraint allows to use a different provider then the default.
+> Use the `provider` option of the constraint to search in a different provider.
+>
+> `new Blacklist(['provider' => 'my_customer_provider.name' ])`
+>
+> Note that only providers registered in the `blacklist.providers` configuration
+> can be used.
 
-The `default_provider` option contains the service-name of the blacklist provider.
+First you need to set a default provider.
 
-This bundle provides an integration for all the pre-bundled provider of the component.
-You can choose from:
+**Note:** Some providers require additional configuring, like database credentials.
 
-* rollerworks_password_strength.blacklist.provider.noop: Default implementation, always returns "not blacklisted".
-* [rollerworks_password_strength.blacklist.provider.array](#array): In-memory-array blacklist, not recommended for big lists.
-* [rollerworks_password_strength.blacklist.provider.sqlite](#sqlite): SQLite3 database file, updatable using the rollerworks-password:blacklist:update console command.
-* [rollerworks_password_strength.blacklist.provider.chain](#chain): Allows using multiple blacklist providers.
+> The configuration file is usually located at `app/config/config.yml`
+>
+> When using Symfony Flex the configuration file may be located elsewhere,
+> and could be generated for you (eg. `config/packages/rollerworks_password.yml`).
 
+First you need to configure a default blacklist provider. 
 Add the following to your config file:
 
 ```yaml
-# app/config/config.yml
-
 rollerworks_password_strength:
     blacklist:
-        # Replace rollerworks_password_strength.blacklist.provider.noop with the service you want to use
+        # Replace rollerworks_password_strength.blacklist.provider.noop with the service-id of the provider you want to use
         default_provider: rollerworks_password_strength.blacklist.provider.noop
 ```
 
+The `rollerworks_password_strength.blacklist.provider.noop` is a no-op provider. 
+It's main purpose is to ensures the application doesn't break, but you can also use
+this to disable password blacklist listing without having to update your code.
+
+### Configuring providers
+
+The PasswordStrength component comes already pre-bundled with support for, in-memory, 
+SQLite3, PDO, and a ChainProvider to search in multiple providers.
+
+**Caution:** 
+
+* The `blacklist.default_provider` option accepts any service-id.
+* The `blacklist.providers` option is a fixed config-structure of providers.
+
+The `blacklist.providers` option is used to compose a list of loadable provider
+services, only configured providers in the list can be used by the `Blacklist` constraint,
+and for maintenance commands. _It's not possible to add custom providers (yet)._
+
+<!-- Support for custom providers is planned. -->
+
+This bundle provides an integration for all the pre-bundled provider of the component.
+You can choose from:
+
+* rollerworks_password_strength.blacklist.provider.noop: Default implementation, always returns "not blacklisted".
+* [rollerworks_password_strength.blacklist.provider.array](#array): In-memory-array blacklist, not recommended for big lists.
+* [rollerworks_password_strength.blacklist.provider.sqlite](#sqlite): SQLite3 database file.
+* [rollerworks_password_strength.blacklist.provider.chain](#chain): Allows using multiple blacklist providers.
+
 ### Array
 
-Add the following to your config file:
+Update your configuration as follow:
 
 ```yaml
-# app/config/config.yml
-
 rollerworks_password_strength:
     blacklist:
         default_provider: rollerworks_password_strength.blacklist.provider.array
@@ -48,11 +81,9 @@ rollerworks_password_strength:
 
 ### Sqlite
 
-Add the following to your config file:
+Update your configuration as follow:
 
 ```yaml
-# app/config/config.yml
-
 rollerworks_password_strength:
     blacklist:
         default_provider: rollerworks_password_strength.blacklist.provider.sqlite
@@ -64,30 +95,34 @@ rollerworks_password_strength:
 
 ### Chain
 
-The chain provider works by searching in the registered providers.
+The chain provider works by searching in the registered providers,
+you can also add service-id of your custom providers.
 
-Add the following to your config file:
+Update your configuration as follow:
 
 ```yaml
-# app/config/config.yml
-
 rollerworks_password_strength:
     blacklist:
         default_provider: rollerworks_password_strength.blacklist.provider.sqlite
         providers:
             chain:
                 lazy: true # Use the LazyChainLoader for better performance (doesn't allow updating at runtime)
                 providers:
-                    # Add a list of services to search in
+                    # Add a list of provider service-ids to search in
                     - rollerworks_password_strength.blacklist.provider.array
                     - rollerworks_password_strength.blacklist.provider.sqlite
 ```
 
+**Note:** The `lazy` option uses `LazyChainLoader` for better performance,
+but unlike the "old" `ChainLoader` the loader doesn't allow adding extra providers
+at runtime, all providers you want to use _must_ be in the list.
+
 ### Custom blacklist provider
 
-To use a custom blacklist provider first register it in the service container,
-add it to the `providers` list and set the `default_provider` to the service id,
-or add it to the `providers.chain.providers` list.
+To use a custom blacklist provider, first register it in the service container.
+
+Depending your usage, add it to the `providers.chain.providers` list or set the
+`default_provider` to the service id.
 
 **Note:** The blacklist provider must implement the
 `Rollerworks\Component\PasswordStrength\Blacklist\BlacklistProviderInterface`.
@@ -96,3 +131,9 @@ or add it to the `providers.chain.providers` list.
 
 Commands for managing the blacklist are automatically registered
 when the Symfony Console component is installed.
+
+You can use the `--provider` option to specify a loader to manage.
+_This doesn't support custom loaders yet._
+
+See also: https://github.com/rollerworks/PasswordStrengthValidator/blob/master/docs/blacklist.md#commands
+