Merge pull request #61 from deanblackborough/v3.02.0

V3.02.0

CHANGELOG.md

@@ -3,6 +3,14 @@
 
 Full changelog for PHP Quill Renderer
 
+## v3.02.0 - 2018-05-13
+
+* Add initial support for loading multiple deltas, very basic and not yet supported through the API, next version.
+* Custom attributes can be added to base insert and compound delta. The base insert adds a span around the insert 
+text; the compound delta adds the attributes to the outer HTML tag.
+* Added code coverage reporting via coveralls.io.
+* Increased test coverage, test for thrown exceptions and removed redundant method in Delta class.
+
 ## v3.01.0 - 2018-05-10
 
 * `Parser::load()` wasn't resetting the deltas array, thanks [tominventisbe](https://github.com/tominventisbe).

README.md

@@ -29,7 +29,7 @@ with version 3 and are unlikely to ever be updated, the v3 is so much more flexi
 The easiest way to use the renderer is via composer. ```composer require deanblackborough/php-quill-renderer```, 
 alternatively you can include the classes in my src/ directory in your library or app.
 
-## Usage
+## Usage via API
 ```
 try {
     $quill = new \DBlackborough\Quill\Render($quill_json, 'HTML');
@@ -40,6 +40,9 @@ try {
 ```
 
 ## Usage, direct, parse and then render
+
+### If you use this method, it will change in the next release, I need to add a load() method to the Renderer class, the API will not change.
+
 ```
 $parser = new \DBlackborough\Quill\Parser\Html();
 $parser->load($quill_json);

src/Delta/Html/Compound.php

@@ -13,8 +13,19 @@
  */
 class Compound extends Delta
 {
+    /**
+     * @var array Array of HTML tags
+     */
     private $tags;
 
+    /**
+     * @var array An array of element attributes
+     */
+    private $element_attributes;
+
+    /**
+     * @var string The generated HTML fragment
+     */
     private $html;
 
     /**
@@ -27,6 +38,7 @@ public function __construct(string $insert)
         $this->insert = $insert;
 
         $this->tags = [];
+        $this->element_attributes = [];
         $this->html = '';
     }
 
@@ -58,7 +70,7 @@ private function tags(): void
                     break;
 
                 default:
-                    // Ignore tags not found
+                    $this->element_attributes[$attribute] = $value;
                     break;
             }
         }
@@ -88,8 +100,17 @@ public function render(): string
     {
         $this->tags();
 
-        foreach ($this->tags as $tag) {
-            $this->html .= "<{$tag}>";
+        $element_attributes = '';
+        foreach ($this->element_attributes as $attribute => $value) {
+            $element_attributes .= "{$attribute}=\"{$value}\" ";
+        }
+
+        foreach ($this->tags as $i => $tag) {
+            if ($i === 0 && strlen($element_attributes) > 0) {
+                $this->html .= "<{$tag} " . rtrim($element_attributes) . '>';
+            } else {
+                $this->html .= "<{$tag}>";
+            }
         }
 
         $this->html .= $this->insert;

src/Delta/Html/Delta.php

@@ -107,20 +107,6 @@ public function getInsert(): string
         return $this->insert;
     }
 
-    /**
-     * If the delta is a child, is it the only child
-     *
-     * @return boolean
-     */
-    public function isOnlyChild(): bool
-    {
-        if ($this->isFirstChild() === true && $this->isLastChild() === true) {
-            return true;
-        } else {
-            return false;
-        }
-    }
-
     /**
      * If the delta is a child, what type of tag is the parent
      *

src/Delta/Html/Insert.php

@@ -34,6 +34,21 @@ public function __construct(string $insert, array $attributes = [])
      */
     public function render(): string
     {
-        return $this->insert;
+        $add_span = false;
+        if (count($this->attributes) > 0) {
+            $add_span = true;
+        }
+
+        if ($add_span === false) {
+            return $this->insert;
+        } else {
+            $html = '<span';
+            foreach($this->attributes as $attribute => $value) {
+                $html .= " {$attribute}=\"{$value}\"";
+            }
+            $html .= ">{$this->insert}</span>";
+
+            return $html;
+        }
     }
 }

src/Parser/Html.php

@@ -130,7 +130,7 @@ public function parse(): bool
                                         break;
 
                                     default:
-                                        // Write to errors array? Throw exception?
+                                        $this->deltas[] = new Insert($quill['insert'], $quill['attributes']);
                                         break;
                                 }
                             }
@@ -185,6 +185,30 @@ public function parse(): bool
         }
     }
 
+    /**
+     * Parse multiple deltas
+     *
+     * @return boolean Return true if all the deltas could be parsed ready for the renderer
+     */
+    public function parseMultiple() : bool
+    {
+        $results = [];
+        foreach ($this->quill_json_stack as $index => $quill_json) {
+            $this->quill_json = $quill_json;
+            $this->deltas = [];
+            $results[$index] = $this->parse();
+            if ($results[$index] === true) {
+                $this->deltas_stack[$index] = $this->deltas();
+            }
+        }
+
+        if (in_array(false, $results) === false) {
+            return true;
+        } else {
+            return false;
+        }
+    }
+
     /**
      * Return the array of delta objects
      *
@@ -194,4 +218,21 @@ public function deltas(): array
     {
         return $this->deltas;
     }
+
+    /**
+     * Return a specific delta array of delta objects
+     *
+     * @param string $index Index of the deltas array you want
+     *
+     * @return array
+     * @throwns \OutOfRangeException
+     */
+    public function deltasByIndex(string $index): array
+    {
+        if (array_key_exists($index, $this->deltas_stack) === true) {
+            return $this->deltas_stack[$index];
+        } else {
+            throw new \OutOfRangeException('Deltas array does not exist for the given index: ' . $index);
+        }
+    }
 }

src/Parser/Parse.php

@@ -13,19 +13,33 @@
 abstract class Parse
 {
     /**
-     * The initial quill json array after it has been decoded
+     * The initial quill json string after it has been json decoded
      *
      * @var array
      */
     protected $quill_json;
 
+    /**
+     * An array of json decoded quill strings
+     *
+     * @var array
+     */
+    protected $quill_json_stack;
+
     /**
      * Deltas array after parsing, array of Delta objects
      *
      * @var array
      */
     protected $deltas;
 
+    /**
+     * Deltas stack array after parsing, array of Delta objects index by user defined index
+     *
+     * @var array
+     */
+    protected $deltas_stack;
+
     /**
      * Is the json array a valid json array?
      *
@@ -38,11 +52,11 @@ abstract class Parse
      */
     public function __construct()
     {
-        $this->deltas = [];
+        $this->quill_json = null;
     }
 
     /**
-     * Load the deltas, check the json is valid and then save to the $quill_json property
+     * Load the deltas, checks the json is valid and then save to the $quill_json property
      *
      * @param string $quill_json Quill json string
      *
@@ -61,6 +75,33 @@ public function load(string $quill_json): bool
         }
     }
 
+    /**
+     * Load multiple deltas
+     *
+     * @param array An array of $quill json, returnable via array index
+     *
+     * @return boolean
+     */
+    public function loadMultiple(array $quill_json): bool
+    {
+        $this->deltas_stack = [];
+
+        foreach ($quill_json as $index => $json) {
+            $json_stack_value = json_decode($json, true);
+
+            if (is_array($json_stack_value) === true && count($json_stack_value) > 0) {
+                $this->quill_json_stack[$index] = $json_stack_value;
+            }
+        }
+
+        if (count($quill_json) === count($this->quill_json_stack)) {
+            $this->valid = true;
+            return true;
+        } else {
+            return false;
+        }
+    }
+
     /**
      * Loop through the deltas and generate the contents array
      *
@@ -74,4 +115,14 @@ abstract public function parse(): bool;
      * @return array
      */
     abstract public function deltas(): array;
+
+    /**
+     * Return a specific delta array of delta objects
+     *
+     * @param string $index Index of the deltas array you want
+     *
+     * @return array
+     * @throwns \OutOfRangeException
+     */
+    abstract public function deltasByIndex(string $index): array;
 }

src/Render.php

@@ -42,14 +42,14 @@ public function __construct(string $deltas, string $format = 'HTML')
                 $this->parser = new Parser\Html();
                 break;
             default:
-                throw new \Exception('No renderer found for requested format: "' . $format . '"');
+                throw new \InvalidArgumentException('Requested $format not supported, formats supported, [HTML]');
                 break;
         }
 
         $this->format = $format;
 
         if ($this->parser->load($deltas) === false) {
-            throw new \Exception('Failed to load deltas json');
+            throw new \RuntimeException('Failed to load/parse deltas json');
         }
     }
 
@@ -75,6 +75,10 @@ public function parserLoaded(): bool
      */
     public function render(): string
     {
+        if ($this->parser === null) {
+            throw new \BadMethodCallException('No parser loaded');
+        }
+
         if ($this->parser->parse() !== true) {
             throw new \Exception('Failed to parse the supplied deltas object');
         }
@@ -84,7 +88,7 @@ public function render(): string
                 $this->renderer = new Renderer\Html($this->parser->deltas());
                 break;
             default:
-                throw new \Exception('No renderer found for requested format: "' . $this->format . '"');
+                // Never should be reached
                 break;
         }
 

src/Renderer/Html.php

@@ -25,6 +25,7 @@ class Html extends Render
      * Renderer constructor.
      *
      * @param array $deltas Delta objects array
+     * @deprecated Loading the delta in the constructor is going to be removed in the next version, to support multiple deltas I am going to add a load method
      */
     public function __construct(array $deltas)
     {