editor.php
v1.1.0
editor.php es un paquete diseñado para ayudar a analizar y manipular la salida de Editor.js con facilidad. Se puede utilizar con PHP básico o con Larave. Laravel ofrece algunas características adicionales.
| editor.php | Laravel | PHP |
|---|---|---|
| 1.x | 10.x ~ 11.x | 8,1 ~ 8,3 |
Instalar el paquete por:
composer require bumpcore/ editor.phpeditor.php es realmente sencillo para comenzar;
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 admite los siguientes bloques;
Todos ellos tienen reglas de validación y vistas predeterminadas para renderizar. Sin embargo, se recomienda encarecidamente personalizar la validación y las vistas.
La clase EditorPhp es la clase principal para gestionar bloques. Puede acceder, renderizar, convertir a una matriz y convertir a JSON a través de esta clase.
Hay dos formas de crear una nueva instancia de EditorPhp:
use BumpCore EditorPhp EditorPhp ;
// Using the `new` syntax.
$ editor = new EditorPhp ( $ json );
// Using the `make` syntax.
$ editor = EditorPhp:: make ( $ json );Ambas sintaxis son iguales y casi no hay diferencia entre ellas.
Puede acceder a los bloques a través de la propiedad de bloques.
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 ;
}); Los bloques se almacenan como IlluminateSupportCollection . Al utilizar métodos de recopilación, puede manipular bloques como desee. Puede obtener información sobre las colecciones en la documentación de Laravel.
Renderizar HTML es muy sencillo. Hay varias formas de renderizar su instancia:
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 ;De nuevo, los tres casos son iguales, sin ninguno por encima de otro. Puedes usar el que más te guste.
De forma predeterminada, tiene dos opciones para las plantillas del bloque predeterminado; tailwindcss y Bootstrap 5 . La plantilla utilizada por defecto es tailwindcss Puede cambiar de plantilla de la siguiente manera:
use BumpCore EditorPhp EditorPhp ;
// Using tailwind.
EditorPhp:: useTailwind ();
// Using Bootstrap.
EditorPhp:: useBootstrapFive ();Puede obtener más información sobre el renderizado en la sección de creación de bloques personalizados.
Puedes generar datos falsos con 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 ();Puede obtener más información sobre cómo generar datos falsos para los bloques en Generación de datos falsos.
Puede convertir su instancia en una matriz usando el método toArray() .
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// This will return ['time' => ..., 'blocks' => [...], 'version' => '...']
$ array = $ editor -> toArray (); Puede convertir su instancia a JSON usando el método toJson(/** options */) . Este método es útil cuando manipulas tu instancia.
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// This will return encoded JSON.
$ json = $ editor -> toJson ( JSON_PRETTY_PRINT );Puedes acceder a hora y versión:
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
$ editor -> time ;
$ editor -> version ; La propiedad time es una instancia Carbon . Puede obtener más información al respecto en la documentación de Carbon.
Puede registrar macros y utilizarlas más tarde. Las macros están basadas en 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 (); Los bloques son las principales partes de construcción del editor EditorPhp . Puedes manipularlos como desees y la mejor parte es que puedes usarlos para almacenar la lógica de tu bloque. Por ejemplo, el bloque de imágenes requiere un cargador para funcionar. Puede implementar la funcionalidad correspondiente en la clase BumpCoreEditorPhpBlocksImage .
Antes de comenzar a aprender cómo personalizar bloques, aquí le mostramos cómo puede registrar sus bloques:
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 ); Al registrar bloques, es importante utilizar la clave correcta. La clave debe ser la misma que la clave type de Editor.js . Para aclarar:
{
"time" : 1672852569662 ,
"blocks" : [
{
"type" : " paragraph " ,
"data" : {
"text" : " ... "
}
}
],
"version" : " 2.26.4 "
} En este resultado, nuestra clave de tipo es paragraph , por lo que debemos registrarla como 'paragraph' => Paragraph::class . Esto puede variar según cómo registre sus bloques en Editor.js . Los bloques predeterminados en EditorPhp se registran mediante camelCase .
Como se mencionó anteriormente, casi todos los bloques son compatibles con EditorPhp . Sin embargo, se encargan principalmente de la validación de datos de bloques y la representación. Para que el bloque Image funcione correctamente, es necesario cargarlo. Podemos implementar esta lógica de carga en la clase 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
]); Como puede ver, hemos ampliado el bloque Image y agregado dos funciones para manejar nuestras cargas.
La función uploadTemp realiza una carga de archivo temporal. Este método es estático y se puede utilizar en cualquier lugar usando Image::uploadTemp() . Devuelve los datos requeridos por la herramienta de imagen.
La función upload tiene un propósito diferente. Representa la carga final del bloque pero no es estática. Este método supone que la imagen ya se cargó temporalmente y el $json se cargó y analizó. Por lo tanto, podemos utilizar esta función de la siguiente manera:
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 ();Ahora el bloque realiza la carga final y se guarda como JSON.
Es imposible admitir todos los bloques que existen, por lo que podemos implementar nuestros propios bloques de una manera sencilla. Un bloque estándar se parece a lo siguiente:
use BumpCore EditorPhp Block Block ;
class MyCustomBlock extends Block
{
public function render (): string
{
return view ( ' blocks.my-custom-block ' , [ ' data ' => $ this -> data ]);
}
}Como puede ver, de forma predeterminada, solo necesitamos implementar la lógica de renderizado. Sin embargo, hay más que simplemente renderizar.
Hay varias formas de acceder a los datos de un bloque. En el siguiente ejemplo, puede ver diferentes métodos para acceder a los datos del bloque:
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! ' );
// ...
}Puede elegir cualquiera de los métodos anteriores para acceder y manipular los datos del bloque. Además, también puede comprobar si los datos existen o no utilizando los siguientes métodos:
$ data -> has ( ' custom.data ' );
// or
$ this -> has ( ' custom.data ' ); No es necesario validar los datos, pero puede hacer que sus datos estén más seguros. Validar los datos del bloque es bastante fácil. Sólo tenemos que agregar un método rules a nuestro bloque:
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 ' ,
];
}
// ...
}Cuando falla la validación de los datos del bloque, los datos estarán vacíos. La validación de datos se realiza utilizando la biblioteca de validación de Laravel. Puede obtener más información al respecto en la documentación de Laravel.
Puedes purificar el HTML de tus datos si lo deseas. Es importante prevenir las inyecciones. La purificación de datos se parece mucho a la validación:
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 ' * ' ;
}
// ...
}A diferencia de la validación, la purificación sólo eliminará las etiquetas y atributos no deseados.
Como mencionamos anteriormente, podemos generar datos falsos con EditorPhp . Pero requiere generar los propios datos falsos de cada bloque. Para generar datos falsos debemos agregar un método estático a nuestro bloque:
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 ,
];
}
// ...
} Al agregar un método fake a nuestro bloque, ahora EditorPhp también incluirá MyCustomBlock al generar datos falsos. Puede obtener más información al respecto en la documentación de FakerPHP.
Hay algunas características de Laravel que te harán la vida un poco más fácil.
Puede utilizar EditorPhpCast para transmitir el atributo de su modelo a la instancia 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 ();Además, si estás utilizando Cast, puedes acceder a tu modelo dentro de instancias de bloque:
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.
}
}
// ...
}También puedes modificar el modelo desde el bloque.
La instancia EditorPhp se puede devolver como respuesta. Si la solicitud espera JSON, se codificará en JSON. De lo contrario, se representará en 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 ;
}
} También puedes usar la instancia EditorPhp para renderizar la vista interna directamente:
{{-- blog.show.blade.php --}}
< article >
< h1 > {{ $post -> title } } </ h1 >
< div > {{ $post -> content } } </ div >
</ article >Tengo que comprobar esto antes de documentarlo.
Puede crear un bloque nuevo con el comando block:make <name> :
php artisan make:block CustomImageBlock El nuevo bloque se colocará en el directorio app/Blocks .
¡Las contribuciones son bienvenidas! Si encuentra un error o tiene una sugerencia de mejora, abra un problema o cree una solicitud de extracción. A continuación se presentan algunas pautas a seguir:
Proporcione una descripción detallada de sus cambios y el problema que resuelven. Su contribución será revisada y es posible que se proporcionen comentarios. ¡Gracias por su ayuda para mejorar este proyecto!
