pref: add BlockGenerator to lazyload parsing

bernard-ng · bernard-ng · commit d9a4ba966f32 · 2025-04-17T12:53:47.000+02:00
diff --git a/src/Definition/AbstractBlock.php b/src/Definition/AbstractBlock.php
@@ -69,6 +69,11 @@ protected function __construct(
     #[\Override]
     public static function create(array $data, array $allowedTags = []): static
     {
+        Assert::notEmpty($data['id']);
+        Assert::notEmpty($data['type']);
+        Assert::isArray($data['data']);
+        Assert::notEmpty($data['data']);
+
         return new static(
             id: $data['id'],
             type: $data['type'],
diff --git a/src/Definition/BlockGenerator.php b/src/Definition/BlockGenerator.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Devscast\EditorJs\Definition;
+
+/**
+ * Class BlockGenerator.
+ *
+ * The `BlockGenerator` class is responsible for generating blocks from the provided data
+ * using a `BlockRegistry`. It implements an iterator to yield block instances parsed
+ * from the data.
+ *
+ * @author bernard-ng <bernard@devscast.tech>
+ */
+final readonly class BlockGenerator
+{
+    /**
+     * Constructor for the `BlockGenerator` class.
+     *
+     * @param string $data The raw data to be parsed into blocks.
+     * @param BlockRegistry $registry The registry containing block definitions.
+     */
+    public function __construct(
+        private string $data,
+        private BlockRegistry $registry
+    ) {
+    }
+
+    /**
+     * Get an iterator for the blocks.
+     *
+     * This method parses the provided data using the `BlockFactory` and yields
+     * instances of `BlockInterface`.
+     *
+     * @return iterable<BlockInterface> An iterable collection of block instances.
+     */
+    public function getIterator(): iterable
+    {
+        yield from BlockFactory::parse($this->data, $this->registry);
+    }
+}
diff --git a/src/Editor.php b/src/Editor.php
@@ -13,8 +13,7 @@
 
 namespace Devscast\EditorJs;
 
-use Devscast\EditorJs\Definition\BlockFactory;
-use Devscast\EditorJs\Definition\BlockInterface;
+use Devscast\EditorJs\Definition\BlockGenerator;
 use Devscast\EditorJs\Definition\BlockRegistry;
 use Devscast\EditorJs\Exception\EditorException;
 use Devscast\EditorJs\Sanitizer\Sanitizer;
@@ -35,10 +34,9 @@
 final readonly class Editor
 {
     /**
-     * @var iterable<BlockInterface>
      * The collection of parsed blocks from the provided JSON data.
      */
-    public iterable $blocks;
+    public BlockGenerator $blocks;
 
     /**
      * Initializes the `Editor` instance by parsing the provided JSON data into blocks
@@ -59,15 +57,15 @@ public function __construct(
             throw new EditorException('Invalid JSON data provided');
         }
 
-        $this->blocks = BlockFactory::parse($data, $registry);
+        $this->blocks = new BlockGenerator($this->data, $this->registry);
     }
 
     /**
      * Get the parsed blocks.
      *
-     * @return iterable<BlockInterface> The collection of parsed blocks.
+     * @return BlockGenerator The collection of parsed blocks.
      */
-    public function getBlocks(): iterable
+    public function getBlocks(): BlockGenerator
     {
         return $this->blocks;
     }
diff --git a/src/Sanitizer/Sanitizer.php b/src/Sanitizer/Sanitizer.php
@@ -13,6 +13,7 @@
 
 namespace Devscast\EditorJs\Sanitizer;
 
+use Devscast\EditorJs\Definition\BlockGenerator;
 use Devscast\EditorJs\Definition\BlockInterface;
 use Symfony\Component\HtmlSanitizer\HtmlSanitizer;
 use Symfony\Component\HtmlSanitizer\HtmlSanitizerConfig;
@@ -39,30 +40,31 @@ final class Sanitizer implements SanitizerInterface
      * This method iterates over the given blocks, converts each block to its HTML
      * representation, and sanitizes the resulting HTML using the configured sanitizer.
      *
-     * @param iterable<BlockInterface> $blocks The collection of blocks to sanitize.
+     * @param BlockGenerator $blocks The collection of blocks to sanitize.
      * @return string The sanitized HTML content.
      */
     #[\Override]
-    public function sanitize(iterable $blocks): string
+    public function sanitize(BlockGenerator $blocks): string
     {
-        $blocks = \iterator_to_array($blocks);
-        $sanitizer = new HtmlSanitizer($this->getConfig($blocks));
+        $config = $this->getConfig($blocks->getIterator());
+        $sanitizer = new HtmlSanitizer($config);
 
-        return array_reduce(
-            $blocks,
-            fn (string $html, BlockInterface $block) => $html . $sanitizer->sanitize($block->toHtml()),
-            initial: ''
-        );
+        $html = '';
+        foreach ($blocks->getIterator() as $block) {
+            $html .= $sanitizer->sanitize($block->toHtml());
+        }
+
+        return $html;
     }
 
     /**
      * Generate the HTML sanitizer configuration based on the allowed tags and attributes
      * of the provided blocks.
      *
-     * @param array<BlockInterface> $blocks The array of blocks to configure the sanitizer for.
+     * @param iterable<BlockInterface> $blocks The collection of blocks to configure the sanitizer for.
      * @return HtmlSanitizerConfig The configured HTML sanitizer.
      */
-    private function getConfig(array $blocks): HtmlSanitizerConfig
+    private function getConfig(iterable $blocks): HtmlSanitizerConfig
     {
         $config = (new HtmlSanitizerConfig())
             ->allowRelativeLinks()
diff --git a/src/Sanitizer/SanitizerInterface.php b/src/Sanitizer/SanitizerInterface.php
@@ -13,7 +13,7 @@
 
 namespace Devscast\EditorJs\Sanitizer;
 
-use Devscast\EditorJs\Definition\BlockInterface;
+use Devscast\EditorJs\Definition\BlockGenerator;
 
 /**
  * Interface SanitizerInterface.
@@ -34,8 +34,8 @@ interface SanitizerInterface
      * This method processes the given blocks, converts them to their HTML representation,
      * and ensures the resulting HTML is safe and adheres to the allowed tags and attributes.
      *
-     * @param iterable<BlockInterface> $blocks The collection of blocks to sanitize.
+     * @param BlockGenerator $blocks The collection of blocks to sanitize.
      * @return string The sanitized HTML content.
      */
-    public function sanitize(iterable $blocks): string;
+    public function sanitize(BlockGenerator $blocks): string;
 }
diff --git a/tests/Blocks/AbstractBlockTest.php b/tests/Blocks/AbstractBlockTest.php
@@ -4,7 +4,6 @@
 
 namespace Devscast\EditorJs\Tests\Blocks;
 
-use Devscast\EditorJs\Definition\AbstractBlock;
 use Devscast\EditorJs\Editor;
 use Devscast\EditorJs\Exception\EditorException;
 use Generator;
@@ -27,6 +26,7 @@ public function testBlockParsingWithInvalidSchema(string $data, string $message)
     {
         $this->expectException(EditorException::class);
         $editor = new Editor($data);
+        $editor->getHtml();
     }
 
     #[DataProvider('getValidSchemasProvider')]
@@ -35,8 +35,6 @@ public function testBlockParsingWithValidSchema(string $data, string $expected,
         $this->assertNotEmpty($data);
 
         $editor = new Editor($data);
-        $this->assertNotEmpty($editor->getBlocks());
-        $this->assertContainsOnlyInstancesOf(AbstractBlock::class, $editor->getBlocks());
         $this->assertSame($expected, $editor->getHtml(), $message);
     }
 }
diff --git a/tests/Blocks/ParagraphTest.php b/tests/Blocks/ParagraphTest.php
@@ -15,10 +15,22 @@ class ParagraphTest extends AbstractBlockTest
     #[\Override]
     public static function getValidSchemasProvider(): \Generator
     {
+        yield [
+            <<< JSON
+                {
+                   "time": 1739980616433,
+                   "version": "2",
+                   "blocks": [{"id": "mhTl6ghSkV", "type": "invalid-paragraph","data": {"text": "This is a test paragraph"}}]
+                }
+                JSON,
+            '',
+            'invalid block is filtered out',
+        ];
         yield [
             <<< JSON
               {
                 "time": 1739980616433,
+                "version": "2",
                 "blocks": [
                   {
                     "id": "mhTl6ghSkV",
@@ -37,6 +49,7 @@ public static function getValidSchemasProvider(): \Generator
             <<< JSON
               {
                 "time": 1739980616433,
+                "version": "2",
                 "blocks": [
                   {
                     "id": "mhTl6ghSkV",
@@ -62,6 +75,7 @@ public static function getValidSchemasProvider(): \Generator
             <<< JSON
               {
                 "time": 1739980616433,
+                "version": "2",
                 "blocks": [
                   { 
                     "id": "mhTl6ghSkV", 
@@ -80,6 +94,7 @@ public static function getValidSchemasProvider(): \Generator
             <<< JSON
               {
                 "time": 1739980616433,
+                "version": "2",
                 "blocks": [
                   { 
                     "id": "mhTl6ghSkV", 
@@ -98,6 +113,7 @@ public static function getValidSchemasProvider(): \Generator
             <<< JSON
             {
               "time": 1739980616433,
+              "version": "2",
               "blocks": [
                 {
                   "id": "mhTl6ghSkV",
@@ -127,16 +143,8 @@ public static function getInvalidSchemasProvider(): \Generator
             <<< JSON
             {
                "time": 1739980616433,
-               "blocks": [{"id": "mhTl6ghSkV", "type": "invalid-type","data": {"text": "This is a test paragraph"}}]
-            }
-            JSON,
-            'invalid block type',
-        ];
-        yield [
-            <<< JSON
-            {
-               "time": 1739980616433,
-               "blocks": [{"id": "", "type": "invalid-type","data": {"text": "This is a test paragraph"}}]
+               "version": "2",
+               "blocks": [{"id": "", "type": "paragraph","data": {"text": "This is a test paragraph"}}]
             }
             JSON,
             'invalid block id',
@@ -145,6 +153,7 @@ public static function getInvalidSchemasProvider(): \Generator
             <<< JSON
             {
                "time": 1739980616433,
+               "version": "2",
                "blocks": [{"id": "mhTl6ghSkV", "type": "paragraph","data": ""}]
             }
             JSON,
@@ -154,6 +163,7 @@ public static function getInvalidSchemasProvider(): \Generator
             <<< JSON
             {
                "time": 1739980616433,
+               "version": "2",
                "blocks": [{"id": "mhTl6ghSkV", "type": "paragraph","data": {}}]
             }
             JSON,

Original file line number	Diff line number	Diff line change
`@@ -13,8 +13,7 @@`
`13`	`13`
`14`	`14`	`namespace Devscast\EditorJs;`
`15`	`15`
`16`		`-use Devscast\EditorJs\Definition\BlockFactory;`
`17`		`-use Devscast\EditorJs\Definition\BlockInterface;`
	`16`	`+use Devscast\EditorJs\Definition\BlockGenerator;`
`18`	`17`	`use Devscast\EditorJs\Definition\BlockRegistry;`
`19`	`18`	`use Devscast\EditorJs\Exception\EditorException;`
`20`	`19`	`use Devscast\EditorJs\Sanitizer\Sanitizer;`
`@@ -35,10 +34,9 @@`
`35`	`34`	`final readonly class Editor`
`36`	`35`	`{`
`37`	`36`	`/**`
`38`		`- * @var iterable<BlockInterface>`
`39`	`37`	`* The collection of parsed blocks from the provided JSON data.`
`40`	`38`	`*/`
`41`		`- public iterable $blocks;`
	`39`	`+ public BlockGenerator $blocks;`
`42`	`40`
`43`	`41`	`/**`
`44`	`42`	* Initializes the `Editor` instance by parsing the provided JSON data into blocks
`@@ -59,15 +57,15 @@ public function __construct(`
`59`	`57`	`throw new EditorException('Invalid JSON data provided');`
`60`	`58`	`}`
`61`	`59`
`62`		`- $this->blocks = BlockFactory::parse($data, $registry);`
	`60`	`+ $this->blocks = new BlockGenerator($this->data, $this->registry);`
`63`	`61`	`}`
`64`	`62`
`65`	`63`	`/**`
`66`	`64`	`* Get the parsed blocks.`
`67`	`65`	`*`
`68`		`- * @return iterable<BlockInterface> The collection of parsed blocks.`
	`66`	`+ * @return BlockGenerator The collection of parsed blocks.`
`69`	`67`	`*/`
`70`		`- public function getBlocks(): iterable`
	`68`	`+ public function getBlocks(): BlockGenerator`
`71`	`69`	`{`
`72`	`70`	`return $this->blocks;`
`73`	`71`	`}`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,6 @@`
`4`	`4`
`5`	`5`	`namespace Devscast\EditorJs\Tests\Blocks;`
`6`	`6`
`7`		`-use Devscast\EditorJs\Definition\AbstractBlock;`
`8`	`7`	`use Devscast\EditorJs\Editor;`
`9`	`8`	`use Devscast\EditorJs\Exception\EditorException;`
`10`	`9`	`use Generator;`
`@@ -27,6 +26,7 @@ public function testBlockParsingWithInvalidSchema(string $data, string $message)`
`27`	`26`	`{`
`28`	`27`	`$this->expectException(EditorException::class);`
`29`	`28`	`$editor = new Editor($data);`
	`29`	`+ $editor->getHtml();`
`30`	`30`	`}`
`31`	`31`
`32`	`32`	`#[DataProvider('getValidSchemasProvider')]`
`@@ -35,8 +35,6 @@ public function testBlockParsingWithValidSchema(string $data, string $expected,`
`35`	`35`	`$this->assertNotEmpty($data);`
`36`	`36`
`37`	`37`	`$editor = new Editor($data);`
`38`		`- $this->assertNotEmpty($editor->getBlocks());`
`39`		`- $this->assertContainsOnlyInstancesOf(AbstractBlock::class, $editor->getBlocks());`
`40`	`38`	`$this->assertSame($expected, $editor->getHtml(), $message);`
`41`	`39`	`}`
`42`	`40`	`}`
Original file line number	Diff line number	Diff line change
`@@ -15,10 +15,22 @@ class ParagraphTest extends AbstractBlockTest`
`15`	`15`	`#[\Override]`
`16`	`16`	`public static function getValidSchemasProvider(): \Generator`
`17`	`17`	`{`
	`18`	`+ yield [`
	`19`	`+ <<< JSON`
	`20`	`+ {`
	`21`	`+ "time": 1739980616433,`
	`22`	`+ "version": "2",`
	`23`	`+ "blocks": [{"id": "mhTl6ghSkV", "type": "invalid-paragraph","data": {"text": "This is a test paragraph"}}]`
	`24`	`+ }`
	`25`	`+ JSON,`
	`26`	`+ '',`
	`27`	`+ 'invalid block is filtered out',`
	`28`	`+ ];`
`18`	`29`	`yield [`
`19`	`30`	`<<< JSON`
`20`	`31`	`{`
`21`	`32`	`"time": 1739980616433,`
	`33`	`+ "version": "2",`
`22`	`34`	`"blocks": [`
`23`	`35`	`{`
`24`	`36`	`"id": "mhTl6ghSkV",`
`@@ -37,6 +49,7 @@ public static function getValidSchemasProvider(): \Generator`
`37`	`49`	`<<< JSON`
`38`	`50`	`{`
`39`	`51`	`"time": 1739980616433,`
	`52`	`+ "version": "2",`
`40`	`53`	`"blocks": [`
`41`	`54`	`{`
`42`	`55`	`"id": "mhTl6ghSkV",`
`@@ -62,6 +75,7 @@ public static function getValidSchemasProvider(): \Generator`
`62`	`75`	`<<< JSON`
`63`	`76`	`{`
`64`	`77`	`"time": 1739980616433,`
	`78`	`+ "version": "2",`
`65`	`79`	`"blocks": [`
`66`	`80`	`{`
`67`	`81`	`"id": "mhTl6ghSkV",`
`@@ -80,6 +94,7 @@ public static function getValidSchemasProvider(): \Generator`
`80`	`94`	`<<< JSON`
`81`	`95`	`{`
`82`	`96`	`"time": 1739980616433,`
	`97`	`+ "version": "2",`
`83`	`98`	`"blocks": [`
`84`	`99`	`{`
`85`	`100`	`"id": "mhTl6ghSkV",`
`@@ -98,6 +113,7 @@ public static function getValidSchemasProvider(): \Generator`
`98`	`113`	`<<< JSON`
`99`	`114`	`{`
`100`	`115`	`"time": 1739980616433,`
	`116`	`+ "version": "2",`
`101`	`117`	`"blocks": [`
`102`	`118`	`{`
`103`	`119`	`"id": "mhTl6ghSkV",`
`@@ -127,16 +143,8 @@ public static function getInvalidSchemasProvider(): \Generator`
`127`	`143`	`<<< JSON`
`128`	`144`	`{`
`129`	`145`	`"time": 1739980616433,`
`130`		`- "blocks": [{"id": "mhTl6ghSkV", "type": "invalid-type","data": {"text": "This is a test paragraph"}}]`
`131`		`- }`
`132`		`- JSON,`
`133`		`- 'invalid block type',`
`134`		`- ];`
`135`		`- yield [`
`136`		`- <<< JSON`
`137`		`- {`
`138`		`- "time": 1739980616433,`
`139`		`- "blocks": [{"id": "", "type": "invalid-type","data": {"text": "This is a test paragraph"}}]`
	`146`	`+ "version": "2",`
	`147`	`+ "blocks": [{"id": "", "type": "paragraph","data": {"text": "This is a test paragraph"}}]`
`140`	`148`	`}`
`141`	`149`	`JSON,`
`142`	`150`	`'invalid block id',`
`@@ -145,6 +153,7 @@ public static function getInvalidSchemasProvider(): \Generator`
`145`	`153`	`<<< JSON`
`146`	`154`	`{`
`147`	`155`	`"time": 1739980616433,`
	`156`	`+ "version": "2",`
`148`	`157`	`"blocks": [{"id": "mhTl6ghSkV", "type": "paragraph","data": ""}]`
`149`	`158`	`}`
`150`	`159`	`JSON,`
`@@ -154,6 +163,7 @@ public static function getInvalidSchemasProvider(): \Generator`
`154`	`163`	`<<< JSON`
`155`	`164`	`{`
`156`	`165`	`"time": 1739980616433,`
	`166`	`+ "version": "2",`
`157`	`167`	`"blocks": [{"id": "mhTl6ghSkV", "type": "paragraph","data": {}}]`
`158`	`168`	`}`
`159`	`169`	`JSON,`