Merge pull request #63 from deanblackborough/v.3.10.0

V.3.10.0

CHANGELOG.md

@@ -3,6 +3,14 @@
 
 Full changelog for PHP Quill Renderer
 
+## v3.10.0 - 2018-05-16
+
+* Added support for passing multiple deltas into the API/parser, limited to multiple of the same type.
+* Added support for reusing the renderer, added `load()` method to enable this.
+* README updated to show new usage.
+* Minor comment and variable corrections.
+* Added tests to cover new feature.
+
 ## v3.02.0 - 2018-05-13
 
 * Add initial support for loading multiple deltas, very basic and not yet supported through the API, next version.

README.md

@@ -29,27 +29,57 @@ 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 via API
+## Usage via API, single $quill_json
 ```
 try {
     $quill = new \DBlackborough\Quill\Render($quill_json, 'HTML');
-    echo $quill->render();
+    $result = $quill->render();
 } catch (\Exception $e) {
     echo $e->getMessage();
 }
+
+echo $result;
 ```
 
-## Usage, direct, parse and then render
+## Usage via API, multiple $quill_json, passed in via array
+
+```
+try {
+    $quill = new RenderMultiple($quill_json, 'HTML');
+    
+    $result_one = $quill->render('one');
+    $result_two = $quill->render('two');
+} catch (\Exception $e) {
+    echo $e->getMessage();
+}
+
+echo $result_one;
+echo $result_two;
+```
 
-### 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.
+## Usage, direct, parse and then render, single $quill_json - updated in v3.10.0
 
 ```
 $parser = new \DBlackborough\Quill\Parser\Html();
+$renderer = new \DBlackborough\Quill\Renderer\Html();
+
 $parser->load($quill_json);
 $parser->parse();
 
-$renderer = new \DBlackborough\Quill\Renderer\Html($parser->deltas());
-echo $renderer->render();
+echo $renderer->load($parser->deltas())->render();
+```
+
+## Usage, direct, parse and then render, multiple $quill_json - updated in v3.10.0
+
+```
+$parser = new \DBlackborough\Quill\Parser\Html();
+$renderer = new \DBlackborough\Quill\Renderer\Html();
+
+$parser->loadMultiple([ 'one'=> $quill_json_1, 'two' => $quill_json_2);
+$parser->parseMultiple();
+
+echo $renderer->load($parser->deltasByIndex('one'))->render();
+echo $renderer->load($parser->deltasByIndex('two'))->render();
 ```
 
 ## Quill attributes support
@@ -73,6 +103,7 @@ Font | No | No | Planned
 Text align | No | No | Planned
 Block quote | No | No | Planned
 Code block | No | No | Planned
+Custom attributes | No | No | Yes
 
 Attribute | HTML Tag
 --- | --- 

src/Parser/Html.php

@@ -44,7 +44,7 @@ public function __construct()
     }
 
     /**
-     * Loop through the deltas and generate the contents array
+     * Parse the $quill_json and generate an array of Delta objects
      *
      * @return boolean
      */
@@ -186,9 +186,9 @@ public function parse(): bool
     }
 
     /**
-     * Parse multiple deltas
+     * Parse the $quill_json_stack and generate an indexed array of Delta objects
      *
-     * @return boolean Return true if all the deltas could be parsed ready for the renderer
+     * @return boolean
      */
     public function parseMultiple() : bool
     {

src/Parser/Parse.php

@@ -103,12 +103,19 @@ public function loadMultiple(array $quill_json): bool
     }
 
     /**
-     * Loop through the deltas and generate the contents array
+     * Parse the $quill_json and generate an array of Delta objects
      *
      * @return boolean
      */
     abstract public function parse(): bool;
 
+    /**
+     * Parse the $quill_json_stack and generate an indexed array of Delta objects
+     *
+     * @return boolean
+     */
+    abstract public function parseMultiple() : bool;
+
     /**
      * Return the array of delta objects
      *

src/Render.php

@@ -28,14 +28,14 @@ class Render
     private $format;
 
     /**
-     * Renderer constructor, sets the deltas and output format
+     * Renderer constructor, pass in the $quill_json string and set the requested output format
      *
-     * @param string $deltas Deltas json string
+     * @param string $quill_json
      * @param string $format Requested output format
      *
      * @throws \Exception
      */
-    public function __construct(string $deltas, string $format = 'HTML')
+    public function __construct(string $quill_json, string $format = 'HTML')
     {
         switch ($format) {
             case 'HTML':
@@ -48,22 +48,8 @@ public function __construct(string $deltas, string $format = 'HTML')
 
         $this->format = $format;
 
-        if ($this->parser->load($deltas) === false) {
-            throw new \RuntimeException('Failed to load/parse deltas json');
-        }
-    }
-
-    /**
-     * Check to see if a parser has been instantiated
-     *
-     * @return boolean
-     */
-    public function parserLoaded(): bool
-    {
-        if ($this->parser !== null) {
-            return true;
-        } else {
-            return false;
+        if ($this->parser->load($quill_json) === false) {
+            throw new \RuntimeException('Failed to load/json_decode the $quill_json string');
         }
     }
 
@@ -80,18 +66,18 @@ public function render(): string
         }
 
         if ($this->parser->parse() !== true) {
-            throw new \Exception('Failed to parse the supplied deltas object');
+            throw new \Exception('Failed to parse the supplied $quill_json array');
         }
 
         switch ($this->format) {
             case 'HTML':
-                $this->renderer = new Renderer\Html($this->parser->deltas());
+                $this->renderer = new Renderer\Html();
                 break;
             default:
                 // Never should be reached
                 break;
         }
 
-        return $this->renderer->render();
+        return $this->renderer->load($this->parser->deltas())->render();
     }
 }

src/RenderMultiple.php

@@ -0,0 +1,84 @@
+<?php
+declare(strict_types=1);
+
+namespace DBlackborough\Quill;
+
+/**
+ * Parse multiple Quill generated deltas strings into the requested format, you can return
+ * then rendered strings in whatever order you want, just provide the relevant index
+ *
+ * @author Dean Blackborough <[email protected]>
+ * @copyright Dean Blackborough
+ * @license https://github.com/deanblackborough/php-quill-renderer/blob/master/LICENSE
+ */
+class RenderMultiple
+{
+    /**
+     * @var \DBlackborough\Quill\Parser\Parse
+     */
+    private $parser;
+
+    /**
+     * @var string
+     */
+    private $format;
+
+    /**
+     * Renderer constructor, pass in the $quill_json string and set the requested output format
+     *
+     * @param array $quill_json An indexed array of $quill_json string
+     * @param string $format Requested output format
+     *
+     * @throws \Exception
+     */
+    public function __construct(array $quill_json, string $format = 'HTML')
+    {
+        switch ($format) {
+            case 'HTML':
+                $this->parser = new Parser\Html();
+                break;
+            default:
+                throw new \InvalidArgumentException('Requested $format not supported, formats supported, [HTML]');
+                break;
+        }
+
+        $this->format = $format;
+
+        if ($this->parser->loadMultiple($quill_json) === false) {
+            throw new \RuntimeException('Failed to load/json_decode the $quill_json strings');
+        }
+    }
+
+    /**
+     * Pass the content array to the renderer and return the generated output
+     *
+     * @param string $index Index to return
+     *
+     * @return string
+     * @throws \Exception
+     * @throws \BadMethodCallException
+     * @throws \OutOfRangeException
+     */
+    public function render(string $index): string
+    {
+        if ($this->parser === null) {
+            throw new \BadMethodCallException('No parser loaded');
+        }
+
+        if ($this->parser->parseMultiple() !== true) {
+            throw new \Exception('Failed to parse the supplied $quill_json arrays');
+        }
+
+        switch ($this->format) {
+            case 'HTML':
+                $deltas = $this->parser->deltasByIndex($index);
+                break;
+            default:
+                $deltas = [];
+                break;
+        }
+
+        $renderer = new Renderer\Html();
+        return $renderer->load($deltas)->render();
+    }
+}

src/Renderer/Html.php

@@ -24,14 +24,11 @@ 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
+     * @return void
      */
-    public function __construct(array $deltas)
+    public function __construct()
     {
-        $this->html = null;
-
-        parent::__construct($deltas);
+        parent::__construct();
     }
 
     /**
@@ -41,6 +38,8 @@ public function __construct(array $deltas)
      */
     public function render(): string
     {
+        $this->html = '';
+
         $block_open = false;
 
         foreach ($this->deltas as $i => $delta) {

src/Renderer/Render.php

@@ -22,11 +22,25 @@ abstract class Render
     /**
      * Renderer constructor.
      *
-     * @param array $deltas Content data array for renderer
+     * @return void
      */
-    public function __construct(array $deltas)
+    public function __construct()
+    {
+        $this->deltas = [];
+    }
+
+    /**
+     * Load the deltas array
+     *
+     * @param array $deltas Deltas array from the parser
+     *
+     * @return Render
+     */
+    public function load(array $deltas) : Render
     {
         $this->deltas = $deltas;
+
+        return $this;
     }
 
     /**