Loosen storage contracts, add hydratable interface, and allow hydration instances (#10)

* Loosen the storage related contracts to allow things, other than strings, to be stored, and retrieved.

* Adding a hydratable interface, and being more specific, at least in the documentation, about what our storage related interfaces support.

* Allowing an instance to be passed during hydration.

Author: fmizzell

src/HydratableInterface.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Contracts;
+
+interface HydratableInterface extends \JsonSerializable
+{
+    public static function hydrate(string $json, $instance = null);
+}

src/Mock/IdGenerator/Sequential.php

@@ -2,7 +2,9 @@
 
 namespace Contracts\Mock\IdGenerator;
 
-class Sequential implements \Contracts\IdGeneratorInterface
+use Contracts\IdGeneratorInterface;
+
+class Sequential implements IdGeneratorInterface
 {
     private $id = 0;
     public function generate()

src/Mock/Storage/JsonObjectMemory.php

@@ -31,7 +31,7 @@ public function retrieveAll(): array
         return  $results;
     }
 
-    public function store(string $data, string $id = null): string
+    public function store($data, string $id = null): string
     {
         $this->validate($data);
         return parent::store($data, $id);

src/Mock/Storage/Memory.php

@@ -2,15 +2,16 @@
 
 namespace Contracts\Mock\Storage;
 
+use Contracts\RetrieverInterface;
 use Contracts\StorerInterface;
 use Contracts\BulkRetrieverInterface;
 
-class Memory implements StorerInterface, BulkRetrieverInterface
+class Memory implements RetrieverInterface, StorerInterface, BulkRetrieverInterface
 {
 
     protected $storage = [];
 
-    public function retrieve(string $id): ?string
+    public function retrieve(string $id)
     {
         if (isset($this->storage[$id])) {
             return $this->storage[$id];
@@ -23,7 +24,7 @@ public function retrieveAll(): array
         return $this->storage;
     }
 
-    public function store(string $data, string $id = null): string
+    public function store($data, string $id = null): string
     {
         if (!isset($id)) {
             throw new \Exception("An id is required to store the data.");

src/RetrieverInterface.php

@@ -10,11 +10,8 @@ interface RetrieverInterface
      * @param string $id
      *   The identifier for the data.
      *
-     * @return string
+     * @return string | HydratableInterface
      *   The data or null if no data could be retrieved.
-     *
-     * @throws \Exception
-     *   No data matched the identifier.
      */
-    public function retrieve(string $id): ?string;
+    public function retrieve(string $id);
 }

src/StorerInterface.php

@@ -7,7 +7,7 @@ interface StorerInterface
   /**
    * Store.
    *
-   * @param string $data
+   * @param string|HydratableInterface $data
    *   The data to be stored.
    * @param string $id
    *   The identifier for the data. If the act of storing generates the
@@ -19,5 +19,5 @@ interface StorerInterface
    * @throws \Exception
    *   Issues storing the data.
    */
-    public function store(string $data, string $id = null): string;
+    public function store($data, string $id = null): string;
 }

test/Mock/IdGenerator/SequentialTest.php

@@ -1,9 +1,7 @@
 <?php
 
-
 namespace ContractsTest\Mock\IdGenerator;
 
-
 use Contracts\Mock\IdGenerator\Sequential;
 use PHPUnit\Framework\TestCase;