editor.php
v1.1.0
editor.php adalah paket yang dirancang untuk membantu mengurai dan memanipulasi keluaran Editor.js dengan mudah. Ini dapat digunakan dengan vanilla PHP atau dengan Larave. Laravel menawarkan beberapa fitur tambahan.
| editor.php | Laravel | PHP |
|---|---|---|
| 1.x | 10.x ~ 11.x | 8.1 ~ 8.3 |
Instal paket dengan:
composer require bumpcore/ editor.phpeditor.php sangat mudah untuk memulai;
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 mendukung blok berikut;
Semuanya memiliki aturan validasi default dan tampilan untuk dirender. Namun, menyesuaikan validasi dan tampilan sangat disarankan.
Kelas EditorPhp adalah kelas utama untuk mengelola blok. Anda dapat mengakses, merender, mengonversi ke array, dan mengonversi ke JSON melalui kelas ini.
Ada dua cara untuk membuat instance baru EditorPhp:
use BumpCore EditorPhp EditorPhp ;
// Using the `new` syntax.
$ editor = new EditorPhp ( $ json );
// Using the `make` syntax.
$ editor = EditorPhp:: make ( $ json );Kedua sintaksisnya sama, dan hampir tidak ada perbedaan di antara keduanya.
Anda dapat mengakses blok melalui properti blok.
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 ;
}); Blok disimpan sebagai IlluminateSupportCollection . Dengan menggunakan metode pengumpulan, Anda dapat memanipulasi blok sesuai keinginan. Anda dapat mempelajari tentang koleksi di dokumentasi Laravel.
Merender HTML sangat mudah. Ada beberapa cara untuk merender instance Anda:
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 ;Sekali lagi, ketiga kasus tersebut sama, tidak ada kasus yang lebih tinggi dari kasus lainnya. Anda dapat menggunakan mana saja yang paling Anda sukai.
Secara default, Anda memiliki dua opsi untuk templat blok default; tailwindcss dan Bootstrap 5 . Template default yang digunakan adalah tailwindcss Anda dapat mengganti template dengan:
use BumpCore EditorPhp EditorPhp ;
// Using tailwind.
EditorPhp:: useTailwind ();
// Using Bootstrap.
EditorPhp:: useBootstrapFive ();Anda dapat mempelajari lebih lanjut tentang rendering di bagian membuat blok khusus.
Anda dapat menghasilkan data palsu dengan 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 ();Anda dapat mempelajari lebih lanjut tentang menghasilkan data palsu untuk blok dalam pembuatan data palsu.
Anda dapat mengonversi instance Anda menjadi array menggunakan metode toArray() .
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// This will return ['time' => ..., 'blocks' => [...], 'version' => '...']
$ array = $ editor -> toArray (); Anda dapat mengonversi instance Anda ke JSON menggunakan metode toJson(/** options */) . Metode ini berguna ketika Anda memanipulasi instance Anda.
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// This will return encoded JSON.
$ json = $ editor -> toJson ( JSON_PRETTY_PRINT );Anda dapat mengakses waktu dan versi:
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
$ editor -> time ;
$ editor -> version ; Properti time adalah contoh Carbon . Anda dapat mempelajarinya lebih lanjut di dokumentasi Carbon.
Anda dapat mendaftarkan makro dan menggunakannya nanti. Makro didasarkan pada 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 (); Blok adalah bagian bangunan utama dari editor EditorPhp . Anda dapat memanipulasinya sesuai keinginan, dan bagian terbaiknya adalah Anda dapat menggunakannya untuk menyimpan logika blok Anda. Misalnya, blok gambar memerlukan pengunggah agar dapat berfungsi. Anda dapat mengimplementasikan fungsionalitas yang sesuai di kelas BumpCoreEditorPhpBlocksImage .
Sebelum kita mulai mempelajari cara menyesuaikan blok, berikut cara mendaftarkan blok Anda:
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 ); Saat mendaftarkan blok, penting untuk menggunakan kunci yang benar. Kuncinya harus sama dengan kunci type Editor.js . Untuk memperjelas:
{
"time" : 1672852569662 ,
"blocks" : [
{
"type" : " paragraph " ,
"data" : {
"text" : " ... "
}
}
],
"version" : " 2.26.4 "
} Dalam keluaran ini, kunci tipe kita adalah paragraph , jadi kita harus mendaftarkannya sebagai 'paragraph' => Paragraph::class . Ini mungkin berbeda-beda tergantung cara Anda mendaftarkan blok Anda di Editor.js . Blok default di EditorPhp didaftarkan menggunakan camelCase .
Seperti disebutkan sebelumnya, hampir semua blok didukung di EditorPhp . Namun, mereka kebanyakan menangani validasi data blok dan rendering. Agar blok Image berfungsi dengan baik, diperlukan pengunggahan. Kita dapat mengimplementasikan logika unggahan ini di kelas 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
]); Seperti yang Anda lihat, kami telah memperluas blok Image dan menambahkan dua fungsi untuk menangani unggahan kami.
Fungsi uploadTemp melakukan pengunggahan file sementara. Metode ini bersifat statis dan dapat digunakan di mana saja menggunakan Image::uploadTemp() . Ini mengembalikan data yang dibutuhkan oleh alat gambar.
Fungsi upload memiliki tujuan berbeda. Ini mewakili unggahan terakhir untuk blok tersebut tetapi tidak statis. Metode ini mengasumsikan bahwa gambar telah diunggah sementara dan $json telah dimuat dan diurai. Oleh karena itu, kita dapat menggunakan fungsi ini sebagai berikut:
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 ();Sekarang blok tersebut melakukan pengunggahan terakhir dan disimpan sebagai JSON.
Tidak mungkin untuk mendukung semua blok di luar sana, sehingga kita dapat mengimplementasikan blok kita sendiri dengan cara yang mudah. Blok standar terlihat seperti berikut:
use BumpCore EditorPhp Block Block ;
class MyCustomBlock extends Block
{
public function render (): string
{
return view ( ' blocks.my-custom-block ' , [ ' data ' => $ this -> data ]);
}
}Seperti yang Anda lihat, secara default, kita hanya perlu mengimplementasikan logika rendering. Namun, ada lebih dari sekedar rendering.
Ada beberapa cara untuk mengakses data blok. Pada contoh di bawah, Anda dapat melihat berbagai metode untuk mengakses data blok:
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! ' );
// ...
}Anda dapat memilih salah satu metode di atas untuk mengakses dan memanipulasi data blok. Selain itu, Anda juga dapat memeriksa apakah data tersebut ada atau tidak menggunakan cara berikut:
$ data -> has ( ' custom.data ' );
// or
$ this -> has ( ' custom.data ' ); Memvalidasi data tidak diperlukan, namun dapat membuat data Anda lebih aman. Memvalidasi data blok cukup mudah. Kita hanya perlu menambahkan metode rules ke blok kita:
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 ' ,
];
}
// ...
}Jika validasi data blok gagal, data akan kosong. Validasi data dilakukan menggunakan perpustakaan validasi Laravel. Anda dapat mempelajarinya lebih lanjut di dokumentasi Laravel.
Anda dapat memurnikan HTML data Anda jika diinginkan. Penting untuk mencegah suntikan. Memurnikan data mirip dengan validasi:
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 ' * ' ;
}
// ...
}Berbeda dengan validasi, pemurnian hanya akan menghapus tag dan atribut yang tidak diinginkan.
Seperti yang kami sebutkan sebelumnya, kami dapat menghasilkan data palsu dengan EditorPhp . Namun hal ini memerlukan pembuatan data palsu masing-masing blok. Untuk menghasilkan data palsu kita harus menambahkan metode statis ke blok kita:
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 ,
];
}
// ...
} Dengan menambahkan metode fake ke blok kami, sekarang EditorPhp juga akan menyertakan MyCustomBlock saat membuat data palsu. Anda dapat mempelajari lebih lanjut di dokumentasi FakerPHP.
Ada beberapa fitur Laravel yang akan membuat hidup Anda sedikit lebih mudah.
Anda dapat menggunakan EditorPhpCast untuk mentransmisikan atribut model Anda ke instance 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 ();Juga jika Anda menggunakan cast, Anda dapat mengakses model Anda dalam instance blok:
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.
}
}
// ...
}Anda juga dapat mengubah model dari blok.
Contoh EditorPhp dapat dikembalikan sebagai respons. Jika permintaan mengharapkan JSON, ia akan menyandikannya sendiri ke JSON. Kalau tidak, itu akan dirender ke dalam 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 ;
}
} Anda juga dapat menggunakan instance EditorPhp untuk merender tampilan dalam secara langsung:
{{-- blog.show.blade.php --}}
< article >
< h1 > {{ $post -> title } } </ h1 >
< div > {{ $post -> content } } </ div >
</ article >Harus memeriksa ini sebelum mendokumentasikannya.
Anda dapat membuat blok baru dengan perintah block:make <name> :
php artisan make:block CustomImageBlock Blok baru akan ditempatkan di bawah direktori app/Blocks .
Kontribusi dipersilahkan! Jika Anda menemukan bug atau memiliki saran perbaikan, silakan buka masalah atau buat permintaan tarik. Berikut adalah beberapa pedoman yang harus diikuti:
Harap berikan penjelasan rinci tentang perubahan Anda dan masalah yang dipecahkannya. Kontribusi Anda akan ditinjau, dan umpan balik mungkin diberikan. Terima kasih atas bantuan Anda dalam menjadikan proyek ini lebih baik!
