Update readme to describe configurable generators and new secure string generator

Author: Robin Cawser

README.md

@@ -31,17 +31,35 @@ vivait_string_generator:
   generators:
     string: vivait_generator.generator.string
     secure_bytes: vivait_generator.generator.secure_bytes
+    secure_string: vivait_generator.generator.secure_bytes
+```
+
+## Bundled generators
+
+### `StringGenerator`
+Generates a random string based on a pool or characters. Defaults:
+
+```php
+@Generate(generator="string", options={"length"=8, "chars"="abcdefjhijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ12345567890", "prefix"=""})
 ```
-### Bundled generators
-* `StringGenerator` generates a random string based on a pool or characters
-* `SecureBytesGenerator` generates a secure random string using the `Symfony\Component\Security\Core\Util\SecureRandom` class
 
-### Custom generators
-You can use your own generators by implementing `GeneratorInterface` and defining the generator in the configuration,
-using either its service or classname.
 
-## Basic usage
+### `SecureBytesGenerator`
+Generates a secure random byte string using the `Symfony\Component\Security\Core\Util\SecureRandom` class. Defaults:
+
+```php
+@Generate(generator="secure_bytes", options={"length"=8})
+```
+
+### `SecureStringGenerator`
+Generates a secure random string using [ircmaxell's RandomLib](https://github.com/ircmaxell/RandomLib). The library provides three different strengths of
+strings(currently `high` is unavailable), `low` and `medium`. Defaults:
+
+```php
+@Generate(generator="secure_string", options={"length"=32, "chars"="", "strength"="medium"})
+```
 
+## Usage
 Add the `@Generate(generator="generator_name")` annotation to an entity property
 (where `generator_name` is the name of a generator defined in the configuration).
 
@@ -75,24 +93,26 @@ class Api
      */
     private $api_key;
 ```
-## Options
 
-### Length
+### Options
+
+Generators that implement `ConfigurableGeneratorInterface`, such as the bundled generators have options which can be configured.
+
+To do this, set the options parameter on the annotation:
 
-To change the length of the generated string, add `length` to the annotation.
 ```php
-@Generate(length=4)
-```  
+@Generate(generator="string", options={"length"=32, "chars"="ABCDEFG"})
+```
 
 ### Callbacks
 
 It's possible to define callbacks on the `Generator` class that you are using.
-For example, with the bundled StringGenerator, you may wish to set the character pool.
+For example, with the bundled StringGenerator, you may wish to set the a prefix on the generated string
 
 This can be achieved by setting the `callbacks` option. For example:
 
 ```php
-@Generate(generator="string", callbacks={"setChars"="ABCDEFG"})
+@Generate(generator="my_generator", callbacks={"setPrefix"="VIVA_"})
 ```
 
 Here, `setChars()` is called in the `StringGenerator` class, passing `ABCDEFG` as a parameter.
@@ -104,7 +124,7 @@ It's even possible to set a callback value dynamically:
  * @var string
  *
  * @ORM\Column(name="short_id", type="string", length=255, nullable=false)
- * @Generate(generator="string", length=5, callbacks={"setPrefix"="getPrefix"})
+ * @Generate(generator="string", options={"length"=32}, callbacks={"setPrefix"="getPrefix"})
  */
 private $short_id;
 
@@ -133,3 +153,43 @@ However, by setting `override` to false, only null properties will have a string
 ```php
 @Generate(generator="string", override=false)
 ```
+
+
+## Custom generators
+You can use your own generators by implementing `GeneratorInterface` and defining the generator in the configuration,
+using either its service or classname.
+
+To create configurable generators, implement `ConfigurableGeneratorInterface`. This interface uses
+[`Symfony\Component\OptionsResolver\OptionsResolver`](http://symfony.com/doc/current/components/options_resolver.html) to set the generator configuration.
+
+Set default options:
+
+```php
+/**
+* @param OptionsResolver $resolver
+* @return mixed
+*/
+public function getDefaultOptions(OptionsResolver $resolver)
+{
+  $resolver->setDefaults([
+    'chars' => $this->chars,
+    'length' => $this->length,
+    'prefix' => $this->prefix,
+    ]);
+  }
+  ```
+
+Do something with options:
+
+  ```php
+  /**
+  * @param array $options
+  * @return mixed|void
+  */
+  public function setOptions(array $options)
+  {
+    $this->chars = $options['chars'];
+    $this->length = $options['length'];
+    $this->prefix = $options['prefix'];
+  }
+  ```