improve docs and exception messages

Author: juliangut

README.md

@@ -30,7 +30,7 @@ Require composer autoload file
 require './vendor/autoload.php';
 ```
 
-By extending `Gears\Identity\AbstractIdentity` you can easily have an Identity classes
+By extending `Gears\Identity\AbstractIdentity` you can easily have an Identity class
 
 ```php
 use Gears\Identity\AbstractIdentity;
@@ -46,16 +46,54 @@ class CustomIdentity extends AbstractIdentity
 }
 ```
 
-### UUID implementations
+### Available implementations
 
 Due to its popularity UUID based identity implementations are provided
 
-Main direct UUID value implementation is available in class `Gears\Identity\UuidIdentity`
+##### UuidIdentity
 
-If you want a more concise UUID based identities you can use any of the following
+```php
+use Gears\Identity\UuidIdentity;
+use Ramsey\Uuid\Uuid;
+
+$uuid = Uuid::uuid4()->toString();
+$identity = UuidIdentity::fromString($uuid);
+```
+
+If you want a more concise UUID based identities you can use any of the following:
+
+##### ShortUuidIdentity
+
+You need to require [pascaldevink/shortuuid](https://github.com/pascaldevink/shortuuid)
+
+```php
+use Gears\Identity\ShortUuidIdentity;
+use PascalDeVink\ShortUuid\ShortUuid;
+
+$shortUuid = new ShortUuid();
+$identity = ShortUuidIdentity::fromString($shortUuid->uuid4());
 
-* `Gears\Identity\ShortUuidIdentity`. You need to composer require [pascaldevink/shortuuid](https://github.com/pascaldevink/shortuuid)
-* `Gears\Identity\HashUuidIdentity`. You need to composer require [hashids/hashids](https://github.com/ivanakimov/hashids.php). Be aware that original UUID should be hashed as hexadecimal strings, so no dashes, review Hashids documentation
+// Should you need to get original UUID
+$originalUuid = $shortUuid->decode($identity->getValue())->toString();
+```
+
+##### HashUuidIdentity
+
+You need to require [hashids/hashids](https://github.com/ivanakimov/hashids.php)
+
+```php
+use Gears\Identity\HashUuidIdentity;
+use Hashids\Hashids;
+use Ramsey\Uuid\Uuid;
+
+$hashIds = new Hashids();
+$uuid = Uuid::uuid4()->toString();
+$hashedUuid = $hashIds->encodeHex(\str_replace('-', '', $uuid));
+$identity = HashUuidIdentity::fromString($hashedUuid);
+
+// Should you need to get original UUID, mind that UUID has no dash separators
+$originalUuid = $hashIds->decodeHex($identity->getValue());
+```
 
 ## Contributing
 

src/AbstractIdentity.php

@@ -70,7 +70,7 @@ final public function __toString(): string
     /**
      * {@inheritdoc}
      */
-    public function serialize(): string
+    final public function serialize(): string
     {
         return \serialize($this->value);
     }
@@ -80,7 +80,7 @@ public function serialize(): string
      *
      * @param mixed $serialized
      */
-    public function unserialize($serialized): void
+    final public function unserialize($serialized): void
     {
         $this->value = \unserialize($serialized, [static::class]);
     }

src/HashUuidIdentity.php

@@ -34,15 +34,15 @@ public static function fromString(string $value)
             $uuid = Uuid::fromString((new Hashids())->decodeHex($value));
         } catch (InvalidUuidStringException $exception) {
             throw new InvalidIdentityException(
-                \sprintf('Provided identifier "%s" is not a valid hashed UUID', $value),
+                \sprintf('Provided identity value "%s" is not a valid hashed UUID', $value),
                 0,
                 $exception
             );
         }
 
         if ($uuid->getVariant() !== Uuid::RFC_4122 || !\in_array($uuid->getVersion(), \range(1, 5), true)) {
             throw new InvalidIdentityException(
-                \sprintf('Provided identifier "%s" is not a valid hashed UUID', $value)
+                \sprintf('Provided identity value "%s" is not a valid hashed UUID', $value)
             );
         }
 

src/ShortUuidIdentity.php

@@ -32,7 +32,7 @@ public static function fromString(string $value)
         $uuid = (new ShortUuid())->decode($value);
         if ($uuid->getVariant() !== Uuid::RFC_4122 || !\in_array($uuid->getVersion(), \range(1, 5), true)) {
             throw new InvalidIdentityException(
-                \sprintf('Provided identifier "%s" is not a valid short UUID', $value)
+                \sprintf('Provided identity value "%s" is not a valid short UUID', $value)
             );
         }
 

src/UuidIdentity.php

@@ -33,15 +33,15 @@ public static function fromString(string $value)
             $uuid = Uuid::fromString($value);
         } catch (InvalidUuidStringException $exception) {
             throw new InvalidIdentityException(
-                \sprintf('Provided identifier "%s" is not a valid UUID', $value),
+                \sprintf('Provided identity value "%s" is not a valid UUID', $value),
                 0,
                 $exception
             );
         }
 
         if ($uuid->getVariant() !== Uuid::RFC_4122 || !\in_array($uuid->getVersion(), \range(1, 5), true)) {
             throw new InvalidIdentityException(
-                \sprintf('Provided identifier "%s" is not a valid UUID', $value)
+                \sprintf('Provided identity value "%s" is not a valid UUID', $value)
             );
         }
 

tests/Identity/HashUuidIdentityTest.php

@@ -32,7 +32,7 @@ public function testCreation(): void
 
     /**
      * @expectedException \Gears\Identity\Exception\InvalidIdentityException
-     * @expectedExceptionMessage Provided identifier "invalidHashedUUID" is not a valid hashed UUID
+     * @expectedExceptionMessage Provided identity value "invalidHashedUUID" is not a valid hashed UUID
      */
     public function testInvalidShortUuid(): void
     {
@@ -41,7 +41,7 @@ public function testInvalidShortUuid(): void
 
     /**
      * @expectedException \Gears\Identity\Exception\InvalidIdentityException
-     * @expectedExceptionMessage Provided identifier "gGJqXEqR7AFZjBkzP9MLtWYP9AA" is not a valid hashed UUID
+     * @expectedExceptionMessage Provided identity value "gGJqXEqR7AFZjBkzP9MLtWYP9AA" is not a valid hashed UUID
      */
     public function testNonRFC4122Uuid(): void
     {

tests/Identity/ShortUuidIdentityTest.php

@@ -32,7 +32,7 @@ public function testCreation(): void
 
     /**
      * @expectedException \Gears\Identity\Exception\InvalidIdentityException
-     * @expectedExceptionMessage Provided identifier "invalidShortUUID" is not a valid short UUID
+     * @expectedExceptionMessage Provided identity value "invalidShortUUID" is not a valid short UUID
      */
     public function testInvalidShortUuid(): void
     {
@@ -41,7 +41,7 @@ public function testInvalidShortUuid(): void
 
     /**
      * @expectedException \Gears\Identity\Exception\InvalidIdentityException
-     * @expectedExceptionMessage Provided identifier "zaDP55gm3yL9cV2D" is not a valid short UUID
+     * @expectedExceptionMessage Provided identity value "zaDP55gm3yL9cV2D" is not a valid short UUID
      */
     public function testNonRFC4122Uuid(): void
     {

tests/Identity/UuidIdentityTest.php

@@ -32,7 +32,7 @@ public function testCreation(): void
 
     /**
      * @expectedException \Gears\Identity\Exception\InvalidIdentityException
-     * @expectedExceptionMessage Provided identifier "invalidUUID" is not a valid UUID
+     * @expectedExceptionMessage Provided identity value "invalidUUID" is not a valid UUID
      */
     public function testInvalidUuid(): void
     {
@@ -41,7 +41,7 @@ public function testInvalidUuid(): void
 
     /**
      * @expectedException \Gears\Identity\Exception\InvalidIdentityException
-     * @expectedExceptionMessage Provided identifier "00000000-07bf-961b-abd8-c4716f92fcc0" is not a valid UUID
+     * @expectedExceptionMessage Provided identity value "00000000-07bf-961b-abd8-c4716f92fcc0" is not a valid UUID
      */
     public function testNonRFC4122Uuid(): void
     {