editor.php
v1.1.0
editor.php عبارة عن حزمة مصممة للمساعدة في تحليل مخرجات Editor.js ومعالجتها بسهولة. يمكن استخدامه مع Vanilla PHP أو Larave. يقدم Laravel بعض الميزات الإضافية.
| editor.php | لارافيل | PHP |
|---|---|---|
| 1.x | 10.x ~ 11.x | 8.1 ~ 8.3 |
تثبيت الحزمة عن طريق:
composer require bumpcore/ editor.phpإن editor.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 );كلا النحوين متساويان، ولا يوجد فرق بينهما تقريبًا.
يمكنك الوصول إلى الكتل من خلال خاصية الكتل.
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 (); يمكنك تحويل المثيل الخاص بك إلى JSON باستخدام طريقة toJson(/** options */) . هذه الطريقة مفيدة عند التعامل مع المثيل الخاص بك.
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 ); عند تسجيل الكتل، من المهم استخدام المفتاح الصحيح. يجب أن يكون المفتاح هو نفس مفتاح type Editor.js . للتوضيح:
{
"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 ();وأيضًا إذا كنت تستخدم cast، فيمكنك الوصول إلى النموذج الخاص بك ضمن مثيلات الحظر:
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 .
المساهمات هي موضع ترحيب! إذا وجدت خطأً أو كان لديك اقتراح للتحسين، فيرجى فتح مشكلة أو إنشاء طلب سحب. فيما يلي بعض الإرشادات التي يجب اتباعها:
يرجى تقديم وصف تفصيلي لتغييراتك والمشكلة التي تحلها. ستتم مراجعة مساهمتك، وقد يتم تقديم تعليقاتك. شكرا لمساعدتكم في جعل هذا المشروع أفضل!
