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目录下。
欢迎贡献！如果您发现错误或有改进建议，请提出问题或创建拉取请求。以下是一些需要遵循的准则：
请详细描述您的更改及其解决的问题。我们将审查您的贡献，并可能提供反馈。感谢您的帮助，让这个项目变得更好！
