editor.php
v1.1.0
editor.php是一個設計用來幫助輕鬆解析和操作 Editor.js 輸出的套件。它可以與普通 PHP 或 Larave 一起使用。 Laravel 提供了一些附加功能。
| editor.php | 拉維爾 | PHP |
|---|---|---|
| 1.x | 10.x ~ 11.x | 8.1~8.3 |
安裝包通過：
composer require bumpcore/ editor.phpeditor.php上手非常簡單；
use BumpCore EditorPhp EditorPhp ;
// Passing Editor.js's output directly to the `make`.
// This will render blocks into html.
echo EditorPhp:: make ( $ json )-> render ();editor.php支援以下區塊；
它們都有預設的驗證規則和要呈現的視圖。但是，強烈建議自訂驗證和視圖。
EditorPhp類別是管理區塊的主類別。您可以透過此類存取、渲染、轉換為陣列以及轉換為 JSON。
有兩種方法可以建立 EditorPhp 的新實例：
use BumpCore EditorPhp EditorPhp ;
// Using the `new` syntax.
$ editor = new EditorPhp ( $ json );
// Using the `make` syntax.
$ editor = EditorPhp:: make ( $ json );兩種語法是相同的，它們之間幾乎沒有區別。
您可以透過blocks屬性存取區塊。
use BumpCore EditorPhp EditorPhp ;
use BumpCore EditorPhp Block Block ;
use BumpCore EditorPhp Blocks Paragraph ;
$ editor = EditorPhp:: make ( $ json );
// Stripping all tags from paragraph block's text.
$ editor -> blocks -> transform ( function ( Block $ block )
{
if ( $ block instanceof Paragraph)
{
$ block -> set ( ' text ' , strip_tags ( $ block -> get ( ' text ' )));
}
return $ block ;
});區塊儲存為IlluminateSupportCollection 。透過使用集合方法，您可以隨心所欲地操作區塊。您可以在 Laravel 文件中了解集合。
渲染 HTML 非常簡單。有多種方法可以渲染實例：
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// Using the `render` function.
echo $ editor -> render ();
// Using the `toHtml` function.
echo $ editor -> toHtml ();
// Or by casting to a string.
echo $ editor ;同樣，這三種情況都是相同的，沒有一個比另一個更好。您可以使用您最喜歡的任何一個。
預設情況下，預設區塊的範本有兩個選項： tailwindcss和Bootstrap 5 。預設使用的模板是tailwindcss您可以透過以下方式切換模板：
use BumpCore EditorPhp EditorPhp ;
// Using tailwind.
EditorPhp:: useTailwind ();
// Using Bootstrap.
EditorPhp:: useBootstrapFive ();您可以在建立自訂區塊部分了解有關渲染的更多資訊。
您可以使用EditorPhp產生假數據。
use BumpCore EditorPhp EditorPhp ;
// This will return a generated fake JSON.
$ fake = EditorPhp:: fake ();
// If we pass first argument true, it will return new `EditorPhp` instance with fake data.
$ fakeEditor = EditorPhp:: fake ( true );
// You can also pass min lenght and max lenght of blocks.
// Below code will generate blocks between 1 and 3.
$ fakeEditor = EditorPhp:: fake ( true , 1 , 3 );
echo $ fakeEditor -> render ();您可以在假數據生成中了解有關為區塊生成假數據的更多資訊。
您可以使用toArray()方法將實例轉換為陣列。
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// This will return ['time' => ..., 'blocks' => [...], 'version' => '...']
$ array = $ editor -> toArray ();您可以使用toJson(/** options */)方法將實例轉換為 JSON。當您操作實例時，此方法非常有用。
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// This will return encoded JSON.
$ json = $ editor -> toJson ( JSON_PRETTY_PRINT );您可以存取時間和版本：
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
$ editor -> time ;
$ editor -> version ; time屬性是一個Carbon實例。您可以在 Carbon 的文檔中了解更多資訊。
您可以註冊巨集並在以後使用它們。宏基於 Laravel。
use BumpCore EditorPhp EditorPhp ;
// Registering new macro.
EditorPhp:: macro (
' getParagraphs ' ,
fn () => $ this -> blocks -> filter ( fn ( Block $ block ) => $ block instanceof Paragraph)
);
$ editor = EditorPhp:: make ( $ json );
// This will return a collection that only contains paragraphs.
$ paragraphs = $ editor -> getParagraphs ();區塊是EditorPhp編輯器的主要建置部分。您可以根據需要操縱它們，最好的部分是您可以使用它們來儲存區塊的邏輯。例如，圖像塊需要上傳器才能運作。您可以在BumpCoreEditorPhpBlocksImage類別中實現對應的功能。
在我們開始學習如何自訂區塊之前，先介紹如何註冊區塊：
use BumpCore EditorPhp EditorPhp ;
// This will merge without erasing already registered blocks. Other blocks will still remain with the recently registered `image` and `paragraph` blocks.
EditorPhp:: register ([
' image ' => Blocks MyCustomImageBlock::class,
' paragraph ' => Blocks MyCustomParagraphBlock::class,
]);
// This will override already registered blocks. We now only have `image` and `paragraph` blocks.
EditorPhp:: register ([
' image ' => Blocks MyCustomImageBlock::class,
' paragraph ' => Blocks MyCustomParagraphBlock::class,
], true );註冊區塊時，使用正確的密鑰很重要。鍵必須與Editor.js的type鍵相同。澄清一下：
{
"time" : 1672852569662 ,
"blocks" : [
{
"type" : " paragraph " ,
"data" : {
"text" : " ... "
}
}
],
"version" : " 2.26.4 "
}在此輸出中，我們的類型鍵是paragraph ，因此我們應該將其註冊為'paragraph' => Paragraph::class 。這可能會有所不同，具體取決於您在Editor.js中註冊區塊的方式。 EditorPhp中的預設區塊是使用camelCase法註冊的。
如前所述， EditorPhp中支援幾乎所有區塊。然而，它們主要處理區塊資料的驗證和渲染。為了使Image塊正常工作，需要上傳。我們可以在Image類別中實作這個上傳邏輯：
use BumpCore EditorPhp Blocks Image ;
class MyImageBlock extends Image
{
public static function uploadTemp ( string $ fileName = ' image ' ): array
{
// ...
// Temporary upload logic.
return [
' success ' => . . . ,
' file ' => [
' url ' => . . . ,
],
];
}
public function upload (): void
{
$ file = $ this -> get ( ' file.url ' );
// Your logic.
// ...
// Altering the current block's data.
$ this -> set ( ' file.url ' , ...);
}
}
// ...
// Registering customized block.
EditorPhp:: register ([
' image ' => MyImageBlock::class
]);正如您所看到的，我們擴展了Image塊並添加了兩個函數來處理我們的上傳。
uploadTemp函數執行臨時檔案上傳。此方法是靜態的，可以在任何使用Image::uploadTemp()的地方使用。它會傳回圖像工具所需的資料。
upload功能有不同的用途。它代表區塊的最終上傳，但不是靜態的。該方法假設圖片已經臨時上傳並且$json已經加載並解析。因此，我們可以如下使用該函數：
use BumpCore EditorPhp EditorPhp ;
use Blocks MyImageBlock ;
$ editor = EditorPhp:: make ( $ json );
$ editor -> blocks -> each ( function ( Block $ block )
{
if ( $ block instanceof MyImageBlock)
{
$ block -> upload ();
}
});
return $ editor -> toJson ();現在該區塊執行最終上傳並儲存為 JSON。
不可能支援所有的區塊，因此我們可以以簡單的方式實現我們自己的區塊。標準塊如下所示：
use BumpCore EditorPhp Block Block ;
class MyCustomBlock extends Block
{
public function render (): string
{
return view ( ' blocks.my-custom-block ' , [ ' data ' => $ this -> data ]);
}
}正如你所看到的，預設情況下，我們只需要實作渲染邏輯。然而，不僅僅是渲染。
有多種方法可以存取區塊的資料。在下面的範例中，您可以看到存取區塊資料的不同方法：
public function render (): string
{
// ...
// Method 1: Accessing through the data object.
$ data = $ this -> data ;
$ data -> get ( ' custom.data ' );
$ data -> set ( ' custom.data ' , ' Hello World! ' );
// Method 2: Accessing by invoking the data object.
$ data ( ' custom.data ' ); // Hello World!
// Method 3: Using shortcuts.
$ this -> get ( ' custom.data ' );
$ this -> set ( ' custom.data ' , ' Nice! ' );
// ...
}您可以選擇上述任何方法來存取和操作區塊的資料。另外，您也可以透過以下方法檢查資料是否存在：
$ data -> has ( ' custom.data ' );
// or
$ this -> has ( ' custom.data ' );驗證資料不是必需的，但它可以使您的資料更安全。驗證區塊資料非常容易。我們只需在我們的區塊中新增一個rules方法：
use BumpCore EditorPhp Block Block ;
class MyCustomBlock extends Block
{
// ...
public function rules (): array
{
return [
' text ' => ' required|string|max:255 ' ,
' items ' => ' sometimes|array ' ,
' items.*.name ' => ' required|string|max:255 ' ,
' items.*.html ' => ' required|string|min:255 ' ,
];
}
// ...
}當驗證區塊的資料失敗時，資料將為空。資料驗證是使用 Laravel 的驗證庫執行的。您可以在 Laravel 文件中了解更多。
如果您願意，您可以淨化資料的 HTML。預防注射很重要。淨化數據看起來很像驗證：
use BumpCore EditorPhp Block Block ;
class MyCustomBlock extends Block
{
// ...
public function allow (): array | string
{
// Specifying one by one.
return [
' text ' => [
' a:href,target,title ' , // Will allow `a` tag and href, target, and title attributes.
' b ' , // Will only allow `b` tag with no attributes.
],
' items.*.name ' => ' b:* ' , // Will allow `b` tag with all attributes.
' items.*.html ' => ' * ' , // Will allow every tag and every attribute.
];
// Or just allowing all attributes and tags for all data.
return ' * ' ;
}
// ...
}與驗證不同，淨化只會去除不需要的標籤和屬性。
正如我們之前提到的，我們可以使用EditorPhp來產生假數據。但它需要產生每個區塊自己的假資料。要產生假數據，我們應該將靜態方法添加到我們的區塊中：
use BumpCore EditorPhp Block Block ;
class MyCustomBlock extends Block
{
// ...
public static function fake ( Faker Generator $ faker ): array
{
$ items = [];
foreach ( range ( 0 , $ faker -> numberBetween ( 0 , 10 )) as $ index )
{
$ items [] = [
' name ' => fake ()-> name (),
' html ' => $ faker -> randomHtml (),
];
}
return [
' text ' => fake ()-> text ( 255 ),
' items ' => $ items ,
];
}
// ...
}透過為我們的區塊添加fake方法，現在EditorPhp在產生假資料時也將包含MyCustomBlock 。您可以在 FakerPHP 的文檔中了解更多資訊。
Laravel 的一些功能可以讓你的生活變得更輕鬆。
您可以使用EditorPhpCast將模型的屬性轉換為EditorPhp實例。
use BumpCore EditorPhp Casts EditorPhpCast ;
use Illuminate Database Eloquent Model ;
class Post extends Model
{
protected $ casts = [
' content ' => EditorPhpCast::class,
];
}
// ...
$ post = Post:: find ( 1 );
// Content is `EditorPhp` instance in here.
echo $ post -> content -> render ();此外，如果您使用強制轉換，您可以在區塊實例中存取您的模型：
use BumpCore EditorPhp Block Block ;
use App Models Post ;
class MyBlock extends Block
{
// ...
public static function render (): string
{
if ( $ this -> root -> model instanceof Post)
{
// Do the other thing.
}
}
// ...
}您也可以從區塊中更改模型。
EditorPhp實例可以作為回應傳回。如果請求需要 JSON，它會將其編碼為 JSON。否則會被渲染成html。
namespace App Http Controllers ;
use App Http Controllers Controller ;
use App Models Post ;
class ShowPostController extends Controller
{
public function __invoke ( Post $ post )
{
// Depending on the request it will return json or rendered html.
return $ post -> content ;
}
}您也可以使用EditorPhp實例直接渲染內部視圖：
{{-- blog.show.blade.php --}}
< article >
< h1 > {{ $post -> title } } </ h1 >
< div > {{ $post -> content } } </ div >
</ article >在記錄之前必須檢查一下。
您可以使用block:make <name>指令建立全新的區塊：
php artisan make:block CustomImageBlock新區塊將放置在app/Blocks目錄下。
歡迎貢獻！如果您發現錯誤或有改進建議，請提出問題或建立拉取請求。以下是一些需要遵循的準則：
請詳細描述您的變更及其解決的問題。我們將審查您的貢獻，並可能提供回饋。感謝您的幫助，讓這個專案變得更好！
