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 の新しいインスタンスを作成するには 2 つの方法があります。
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 ;繰り返しますが、3 つのケースはすべて同じであり、他に優劣はありません。最も好きなものを使用できます。
デフォルトでは、デフォルト ブロックのテンプレートには 2 つのオプションがあります。 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ブロックを拡張し、アップロードを処理する 2 つの関数を追加しました。
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ディレクトリの下に配置されます。
貢献は大歓迎です!バグを見つけた場合、または改善のための提案がある場合は、問題を開くか、プル リクエストを作成してください。以下に従うべきガイドラインをいくつか示します。
変更内容とそれによって解決される問題について詳しく説明してください。あなたの貢献が検討され、フィードバックが提供される場合があります。このプロジェクトをより良いものにするためにご協力いただきありがとうございます。
