doc: add details for checking user password strength (#143)

Co-authored-by: Vincent <[email protected]>

README.md

@@ -1,6 +1,6 @@
 # CoopTilleulsForgotPasswordBundle
 
-This Symfony bundle provides an _forgot password_ feature for a REST API.
+This Symfony bundle provides a _forgot password_ feature for a REST API.
 It is bridged for [API Platform](https://api-platform.com/).
 
 [![Actions Status](https://github.com/coopTilleuls/CoopTilleulsForgotPasswordBundle/workflows/CI/badge.svg)](https://github.com/coopTilleuls/CoopTilleulsForgotPasswordBundle/actions)

docs/usage.md

@@ -109,6 +109,54 @@ Your app is ready to receive a request like:
 }
 ```
 
+### Validate the user password
+
+Chances are that you want to ensure the new password is strong enough.
+
+```php
+// src/Entity/User.php
+namespace App\Entity;
+
+use Symfony\Component\Validator\Constraints as Assert;
+
+class User
+{
+    #[Assert\PasswordStrength]
+    protected $rawPassword;
+}
+```
+
+Now, you can use the very same event to validate the User.
+
+```php
+// src/EventSubscriber/ForgotPasswordEventSubscriber.php
+
+public function onUpdatePassword(UpdatePasswordEvent $event): void
+{
+    $passwordToken = $event->getPasswordToken();
+    $user = $passwordToken->getUser();
+    $user->setPlainPassword($event->getPassword());
+
+    // ApiPlatform\Validator\ValidatorInterface
+    $this->validator->validate($user); // throws an Exception if invalid
+
+    /*
+     * // Symfony\Component\Validator\Validator\ValidatorInterface
+     * $constraintViolationList = $this->validator->validate($user); // returns a ConstraintViolationListInterface which is a \Traversable, \Countable and \ArrayAccess
+     * 
+     * // TODO: handle when the list is not empty
+     */
+
+    $this->userManager->updateUser($user);
+}
+```
+
+Please note that when using API Platform validator, there is a slight difference between version 3.3 and 3.4+.  
+
+**In version 3.3 and lower**, the validation system overwrite Symfony's. In case of a constraint violation Exception thrown, it will always respond in JSON with Hydra / JSON-LD / JSON Problem, according to your configuration. This, even if the Request has been sent through a classic form. _You might want to prefer one or the other accordingly to your use-case._  
+
+**In version 3.4 and above**, this unwanted behaviour has been fixed and API Platform validation system will check if the object (here: the user) is an API Platform resource. If not, It will fallback to Symfony's error system, as it should. _Using API Platform validator is then completely fine._
+
 ## Use your own business rules when the user is not found
 
 On the third user story, user was not found, you can listen to this event and use your own rules.