editor.php
v1.1.0
editor.php est un package conçu pour aider à analyser et à manipuler facilement la sortie de Editor.js. Il peut être utilisé avec PHP Vanilla ou avec Larave. Laravel offre quelques fonctionnalités supplémentaires.
| editor.php | Laravel | PHP |
|---|---|---|
| 1.x | 10.x ~ 11.x | 8.1 ~ 8.3 |
Installez le package en :
composer require bumpcore/ editor.phpeditor.php est vraiment simple à démarrer ;
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 prend en charge les blocs suivants :
Tous ont des règles de validation par défaut et des vues à restituer. Cependant, la personnalisation de la validation et des vues est fortement recommandée.
La classe EditorPhp est la classe principale de gestion des blocs. Vous pouvez accéder, restituer, convertir en tableau et convertir en JSON via cette classe.
Il existe deux manières de créer une nouvelle instance de EditorPhp :
use BumpCore EditorPhp EditorPhp ;
// Using the `new` syntax.
$ editor = new EditorPhp ( $ json );
// Using the `make` syntax.
$ editor = EditorPhp:: make ( $ json );Les deux syntaxes sont égales et il n’y a presque aucune différence entre elles.
Vous pouvez accéder aux blocs via la propriété Blocks.
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 ;
}); Les blocs sont stockés sous IlluminateSupportCollection . En utilisant des méthodes de collecte, vous pouvez manipuler les blocs à votre guise. Vous pouvez en savoir plus sur les collections dans la documentation de Laravel.
Le rendu HTML est très simple. Il existe plusieurs façons de restituer votre instance :
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 ;Encore une fois, les trois cas sont identiques, aucun n’étant supérieur à l’autre. Vous pouvez utiliser celui que vous préférez.
Par défaut, vous disposez de deux options pour les modèles de bloc par défaut ; tailwindcss et Bootstrap 5 . Le modèle utilisé par défaut est tailwindcss Vous pouvez changer de modèle en :
use BumpCore EditorPhp EditorPhp ;
// Using tailwind.
EditorPhp:: useTailwind ();
// Using Bootstrap.
EditorPhp:: useBootstrapFive ();Vous pouvez en savoir plus sur le rendu dans la section Création de blocs personnalisés.
Vous pouvez générer de fausses données avec 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 ();Vous pouvez en savoir plus sur la génération de fausses données pour les blocs lors de la génération de fausses données.
Vous pouvez convertir votre instance en tableau à l'aide de la méthode toArray() .
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// This will return ['time' => ..., 'blocks' => [...], 'version' => '...']
$ array = $ editor -> toArray (); Vous pouvez convertir votre instance en JSON à l'aide de la méthode toJson(/** options */) . Cette méthode est utile lorsque vous manipulez votre instance.
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// This will return encoded JSON.
$ json = $ editor -> toJson ( JSON_PRETTY_PRINT );Vous pouvez accéder à l'heure et à la version :
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
$ editor -> time ;
$ editor -> version ; La propriété time est une instance Carbon . Vous pouvez en savoir plus à ce sujet dans la documentation de Carbon.
Vous pouvez enregistrer des macros et les utiliser plus tard. Les macros sont basées sur 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 (); Les blocs sont les principaux éléments de construction de l’éditeur EditorPhp . Vous pouvez les manipuler comme vous le souhaitez, et le meilleur, c'est que vous pouvez les utiliser pour stocker la logique de votre bloc. Par exemple, le bloc d'image nécessite un téléchargeur pour fonctionner. Vous pouvez implémenter la fonctionnalité correspondante dans la classe BumpCoreEditorPhpBlocksImage .
Avant de commencer à apprendre à personnaliser les blocs, voici comment vous pouvez enregistrer vos blocs :
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 ); Lors de l'enregistrement des blocs, il est important d'utiliser la bonne clé. La clé doit être la même que la clé type de Editor.js . Pour clarifier :
{
"time" : 1672852569662 ,
"blocks" : [
{
"type" : " paragraph " ,
"data" : {
"text" : " ... "
}
}
],
"version" : " 2.26.4 "
} Dans cette sortie, notre clé de type est paragraph , nous devons donc l'enregistrer comme 'paragraph' => Paragraph::class . Cela peut varier en fonction de la manière dont vous enregistrez vos blocs dans Editor.js . Les blocs par défaut dans EditorPhp sont enregistrés à l'aide de camelCase .
Comme mentionné précédemment, presque tous les blocs sont pris en charge dans EditorPhp . Cependant, ils gèrent principalement la validation des données de bloc et le rendu. Pour que le bloc Image fonctionne correctement, il nécessite un téléchargement. Nous pouvons implémenter cette logique de téléchargement dans la classe 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
]); Comme vous pouvez le constater, nous avons étendu le bloc Image et ajouté deux fonctions pour gérer nos téléchargements.
La fonction uploadTemp effectue un téléchargement de fichier temporaire. Cette méthode est statique et peut être utilisée n'importe où en utilisant Image::uploadTemp() . Il renvoie les données requises par l'outil d'image.
La fonction upload a un objectif différent. Il représente le téléchargement final du bloc mais n'est pas statique. Cette méthode suppose que l'image a déjà été téléchargée temporairement et que le $json a été chargé et analysé. On peut donc utiliser cette fonction comme suit :
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 ();Le bloc effectue désormais le téléchargement final et est enregistré au format JSON.
Il est impossible de prendre en charge tous les blocs, nous pouvons donc implémenter nos propres blocs de manière simple. Un bloc standard ressemble à ceci :
use BumpCore EditorPhp Block Block ;
class MyCustomBlock extends Block
{
public function render (): string
{
return view ( ' blocks.my-custom-block ' , [ ' data ' => $ this -> data ]);
}
}Comme vous pouvez le voir, par défaut, il nous suffit d'implémenter la logique de rendu. Cependant, il y a bien plus que du simple rendu.
Il existe plusieurs façons d'accéder aux données d'un bloc. Dans l'exemple ci-dessous, vous pouvez voir différentes méthodes pour accéder aux données de bloc :
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! ' );
// ...
}Vous pouvez choisir l'une des méthodes ci-dessus pour accéder et manipuler les données du bloc. De plus, vous pouvez également vérifier si les données existent ou non en utilisant les méthodes suivantes :
$ data -> has ( ' custom.data ' );
// or
$ this -> has ( ' custom.data ' ); La validation des données n'est pas obligatoire, mais elle peut rendre vos données plus sûres. La validation des données de bloc est assez simple. Il suffit d'ajouter une méthode rules à notre bloc :
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 ' ,
];
}
// ...
}Lorsque la validation des données du bloc échoue, les données seront vides. La validation des données est effectuée à l'aide de la bibliothèque de validation de Laravel. Vous pouvez en apprendre davantage dans la documentation de Laravel.
Vous pouvez purifier le HTML de vos données si vous le souhaitez. Il est important d'éviter les injections. La purification des données ressemble beaucoup à une validation :
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 ' * ' ;
}
// ...
}Contrairement à la validation, la purification supprimera uniquement les balises et attributs indésirables.
Comme nous l'avons mentionné précédemment, nous pouvons générer de fausses données avec EditorPhp . Mais cela nécessite de générer les fausses données de chaque bloc. Pour générer de fausses données, nous devons ajouter une méthode statique à notre bloc :
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 ,
];
}
// ...
} En ajoutant fake méthode à notre bloc, EditorPhp inclura désormais également MyCustomBlock lors de la génération de fausses données. Vous pouvez en savoir plus sur la documentation de FakerPHP.
Il existe peu de fonctionnalités de Laravel qui vous faciliteront un peu la vie.
Vous pouvez utiliser EditorPhpCast pour convertir l'attribut de votre modèle en 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 ();De plus, si vous utilisez Cast, vous pouvez accéder à votre modèle dans les instances de bloc :
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.
}
}
// ...
}Vous pouvez également modifier le modèle à partir du bloc.
L'instance EditorPhp peut être renvoyée en réponse. Si la demande attend du JSON, elle s'encodera automatiquement en JSON. Sinon, il sera rendu 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 ;
}
} Vous pouvez également utiliser l'instance EditorPhp pour afficher directement la vue intérieure :
{{-- blog.show.blade.php --}}
< article >
< h1 > {{ $post -> title } } </ h1 >
< div > {{ $post -> content } } </ div >
</ article >Je dois vérifier cela avant de le documenter.
Vous pouvez créer un tout nouveau bloc avec block:make <name> :
php artisan make:block CustomImageBlock Le nouveau bloc sera placé dans le répertoire app/Blocks .
Les contributions sont les bienvenues ! Si vous trouvez un bug ou avez une suggestion d'amélioration, veuillez ouvrir un problème ou créer une pull request. Voici quelques directives à suivre :
Veuillez fournir une description détaillée de vos modifications et du problème qu'elles résolvent. Votre contribution sera examinée et des commentaires pourront être fournis. Merci pour votre aide pour améliorer ce projet !
