ref: improve block definitions

Author: bernard-ng

README.md

@@ -1,48 +1,54 @@
-# EditorJS PHP
+# EditorJS Backend
 
 [![PHP Version Require](http://poser.pugx.org/devscast/editorjs/require/php)](https://packagist.org/packages/devscast/editorjs)
 [![Latest Stable Version](https://poser.pugx.org/devscast/editorjs/v/stable)](https://packagist.org/packages/devscast/editorjs)
 [![Total Downloads](https://poser.pugx.org/devscast/editorjs/downloads)](https://packagist.org/packages/devscast/editorjs)
 [![License](https://poser.pugx.org/devscast/editorjs/license)](https://packagist.org/packages/devscast/editorjs)
 
-Server-side implementation for the Editor.js. 
-It contains data validation, HTML sanitization and converts output from Editor.js to the Block objects.
+EditorJS Backend is a library for parsing, validating, and sanitizing JSON data generated by the Editor.js rich text editor. 
+It provides a robust and extensible way to handle Editor.js blocks in PHP applications.
 
 ## Installation
-To install lib use composer:
+
 ```bash
 composer require devscast/editorjs
 ```
 
-## Configuration file
-You can manually configure validation rules for different types of Editor.js tools (header, paragraph, list, quote and other). You can also extend configuration with new tools.
-
-```yaml
-tools:
-    header:
-        text:
-            type: string
-            required: true
-            allowedTags:
-                - {tag: "b", attributes: []}
-                - {tag: "i", attributes: []}
-                - {tag: "a", attributes: ["href"]}
-        level:
-            type: int
-            canBeOnly: [2, 3, 4, 5, 6]
+## Basic Usage
+Parsing and Sanitizing Editor.js Data
+The Editor class is the main entry point for processing Editor.js JSON data. It parses the JSON into blocks, validates the structure, and sanitizes the resulting HTML output.
+
+```php
+<?php
+
+use Devscast\EditorJs\Editor;
+
+$data = <<<JSON
+{
+    "time": 1635603431943,
+    "blocks": [
+        {
+            "id": "1",
+            "type": "header",
+            "data": {
+                "text": "Hello, Editor.js!",
+                "level": 2
+            }
+        },
+        {
+            "id": "2",
+            "type": "paragraph",
+            "data": {
+                "text": "This is a paragraph block."
+            }
+        }
+    ],
+    "version": "2.31.0"
+}
+JSON;
+
+$editor = new Editor($data);
+
+// Get sanitized HTML output
+echo $editor->getHtml();
 ```
-
-Where:
-
-- **tools** — array of supported Editor.js tools.
-- **header** — defines header tool settings.
-- **text and level** — parameters in header tool structure.
-  - **text** is a required string, which will be sanitized except b, i and a[href] tags.
-  - **level** is an optional integer that can be only 0, 1 or 2.
-- **allowedTags** — list of allowed tags with attributes.
-
-## Acknowledgements
-This library is based on the following projects:
-
-- [Editor.js](https://editorjs.io/)
-- [Editor.js PHP](https://github.com/editor-js/editorjs-php)

phpstan.neon

@@ -5,5 +5,6 @@ parameters:
         - tests
 
     ignoreErrors:
-        #- identifier: missingType.generics
-        - identifier: missingType.iterableValue
+        - identifier: missingType.iterableValue
+        - identifier: property.defaultValue # BlockFactory L36
+        - identifier: assign.propertyType # BlockFactory L73

src/AbstractBlock.php

@@ -13,8 +13,8 @@
 
 namespace Devscast\EditorJs\Blocks;
 
-use Devscast\EditorJs\AbstractBlock;
 use Devscast\EditorJs\Assert;
+use Devscast\EditorJs\Definition\AbstractBlock;
 
 /**
  * Class Attaches.
@@ -30,6 +30,8 @@
 {
     public const string NAME = 'attaches';
 
+    public const array ALLOWED_TAGS = [];
+
     protected function __construct(string $id, string $type, array $data, ?array $tunes = [], ?array $allowedTags = null)
     {
         Assert::eq($type, self::NAME);

src/BlockFactory.php

@@ -13,8 +13,8 @@
 
 namespace Devscast\EditorJs\Blocks;
 
-use Devscast\EditorJs\AbstractBlock;
 use Devscast\EditorJs\Assert;
+use Devscast\EditorJs\Definition\AbstractBlock;
 
 /**
  * Class Code.
@@ -30,6 +30,8 @@
 {
     public const string NAME = 'code';
 
+    public const array ALLOWED_TAGS = [];
+
     protected function __construct(string $id, string $type, array $data, ?array $tunes = [], ?array $allowedTags = null)
     {
         Assert::eq($type, self::NAME);

src/BlockInterface.php

@@ -13,8 +13,8 @@
 
 namespace Devscast\EditorJs\Blocks;
 
-use Devscast\EditorJs\AbstractBlock;
 use Devscast\EditorJs\Assert;
+use Devscast\EditorJs\Definition\AbstractBlock;
 
 /**
  * Class Delimiter.
@@ -30,6 +30,8 @@
 {
     public const string NAME = 'delimiter';
 
+    public const array ALLOWED_TAGS = [];
+
     protected function __construct(string $id, string $type, array $data, ?array $tunes = [], ?array $allowedTags = null)
     {
         Assert::eq($type, self::NAME);

src/Blocks/Attaches.php

@@ -13,8 +13,8 @@
 
 namespace Devscast\EditorJs\Blocks;
 
-use Devscast\EditorJs\AbstractBlock;
 use Devscast\EditorJs\Assert;
+use Devscast\EditorJs\Definition\AbstractBlock;
 
 /**
  * Class Embed.
@@ -30,6 +30,8 @@
 {
     public const string NAME = 'embed';
 
+    public const array ALLOWED_TAGS = [];
+
     protected function __construct(string $id, string $type, array $data, ?array $tunes = [], ?array $allowedTags = null)
     {
         Assert::eq($type, self::NAME);