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 );두 구문은 동일하며 둘 사이에는 거의 차이가 없습니다.
블록 속성을 통해 블록에 접근할 수 있습니다.
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 디렉터리에 배치됩니다.
기여를 환영합니다! 버그를 발견했거나 개선을 위한 제안이 있는 경우 이슈를 공개하거나 풀 리퀘스트를 작성해 주세요. 다음은 따라야 할 몇 가지 지침입니다.
변경사항과 이로 인해 해결되는 문제에 대한 자세한 설명을 제공해 주세요. 귀하의 기여가 검토되고 피드백이 제공될 수 있습니다. 이 프로젝트를 더 좋게 만드는 데 도움을 주셔서 감사합니다!
