editor.php
v1.1.0
editor.php — это пакет, предназначенный для облегчения анализа и управления выводом Editor.js. Его можно использовать как с ванильным PHP, так и с Larave. Laravel предлагает несколько дополнительных функций.
| editor.php | Ларавел | PHP |
|---|---|---|
| 1.х | 10.х ~ 11.х | 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 ();Также, если вы используете приведение, вы можете получить доступ к своей модели внутри экземпляров блока:
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 .
Вклады приветствуются! Если вы обнаружили ошибку или у вас есть предложения по улучшению, откройте проблему или создайте запрос на включение. Ниже приведены некоторые рекомендации, которым следует следовать:
Пожалуйста, предоставьте подробное описание ваших изменений и проблемы, которую они решают. Ваш вклад будет рассмотрен, и может быть предоставлена обратная связь. Спасибо за помощь в улучшении проекта!
