editor.php
v1.1.0
editor.php ist ein Paket, das das einfache Parsen und Bearbeiten der Ausgabe von Editor.js unterstützen soll. Es kann entweder mit Vanilla PHP oder mit Larave verwendet werden. Laravel bietet einige zusätzliche Funktionen.
| editor.php | Laravel | PHP |
|---|---|---|
| 1.x | 10.x ~ 11.x | 8.1 ~ 8.3 |
Paket installieren durch:
composer require bumpcore/ editor.phpDer Einstieg in editor.php ist wirklich einfach;
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 unterstützt folgende Blöcke;
Alle verfügen über Standardvalidierungsregeln und -ansichten zum Rendern. Es wird jedoch dringend empfohlen, die Validierung und Ansichten anzupassen.
Die EditorPhp -Klasse ist die Hauptklasse zum Verwalten von Blöcken. Über diese Klasse können Sie darauf zugreifen, rendern, in ein Array konvertieren und in JSON konvertieren.
Es gibt zwei Möglichkeiten, eine neue Instanz von EditorPhp zu erstellen:
use BumpCore EditorPhp EditorPhp ;
// Using the `new` syntax.
$ editor = new EditorPhp ( $ json );
// Using the `make` syntax.
$ editor = EditorPhp:: make ( $ json );Beide Syntaxen sind gleich und es gibt fast keinen Unterschied zwischen ihnen.
Sie können über die Blocks-Eigenschaft auf Blöcke zugreifen.
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 ;
}); Blöcke werden als IlluminateSupportCollection gespeichert. Mithilfe von Sammlungsmethoden können Sie Blöcke nach Ihren Wünschen manipulieren. Weitere Informationen zu Sammlungen finden Sie in der Dokumentation von Laravel.
Das Rendern von HTML ist sehr einfach. Es gibt mehrere Möglichkeiten, Ihre Instanz zu rendern:
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 ;Auch hier sind alle drei Fälle gleich, keiner steht über dem anderen. Sie können diejenige verwenden, die Ihnen am besten gefällt.
Standardmäßig haben Sie zwei Optionen für die Vorlagen des Standardblocks; tailwindcss und Bootstrap 5 . Die standardmäßig verwendete Vorlage ist tailwindcss Sie können die Vorlagen wechseln, indem Sie:
use BumpCore EditorPhp EditorPhp ;
// Using tailwind.
EditorPhp:: useTailwind ();
// Using Bootstrap.
EditorPhp:: useBootstrapFive ();Weitere Informationen zum Rendern finden Sie im Abschnitt zum Erstellen benutzerdefinierter Blöcke.
Mit EditorPhp können Sie gefälschte Daten generieren.
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 ();Weitere Informationen zum Generieren gefälschter Daten für die Blöcke finden Sie in der gefälschten Datengenerierung.
Sie können Ihre Instanz mit der Methode toArray() in ein Array konvertieren.
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// This will return ['time' => ..., 'blocks' => [...], 'version' => '...']
$ array = $ editor -> toArray (); Sie können Ihre Instanz mit der Methode toJson(/** options */) in JSON konvertieren. Diese Methode ist nützlich, wenn Sie Ihre Instanz bearbeiten.
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
// This will return encoded JSON.
$ json = $ editor -> toJson ( JSON_PRETTY_PRINT );Sie können auf Uhrzeit und Version zugreifen:
use BumpCore EditorPhp EditorPhp ;
$ editor = EditorPhp:: make ( $ json );
$ editor -> time ;
$ editor -> version ; Die time ist eine Carbon Instanz. Mehr darüber erfahren Sie in der Dokumentation von Carbon.
Sie können Makros registrieren und später verwenden. Makros basieren auf 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 (); Blöcke sind die Hauptbauteile des EditorPhp Editors. Sie können sie nach Belieben manipulieren und das Beste daran ist, dass Sie sie zum Speichern der Logik Ihres Blocks verwenden können. Beispielsweise erfordert der Bildblock einen Uploader, um zu funktionieren. Sie können die entsprechende Funktionalität in der Klasse BumpCoreEditorPhpBlocksImage implementieren.
Bevor wir uns mit dem Anpassen von Blöcken befassen, erfahren Sie hier, wie Sie Ihre Blöcke registrieren können:
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 ); Bei der Registrierung von Blöcken ist es wichtig, den richtigen Schlüssel zu verwenden. Der Schlüssel muss mit dem type von Editor.js identisch sein. Zur Klarstellung:
{
"time" : 1672852569662 ,
"blocks" : [
{
"type" : " paragraph " ,
"data" : {
"text" : " ... "
}
}
],
"version" : " 2.26.4 "
} In dieser Ausgabe lautet unser Typschlüssel paragraph “, daher sollten wir ihn als 'paragraph' => Paragraph::class registrieren. Dies kann je nachdem, wie Sie Ihre Blöcke in Editor.js registrieren, variieren. Standardblöcke in EditorPhp werden mit camelCase registriert.
Wie bereits erwähnt, werden in EditorPhp fast alle Blöcke unterstützt. Sie kümmern sich jedoch hauptsächlich um die Validierung von Blockdaten und das Rendering. Damit der Image ordnungsgemäß funktioniert, ist ein Upload erforderlich. Wir können diese Upload-Logik in der Image -Klasse implementieren:
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
]); Wie Sie sehen, haben wir den Image erweitert und zwei Funktionen hinzugefügt, um unsere Uploads zu verwalten.
Die Funktion uploadTemp führt einen temporären Datei-Upload durch. Diese Methode ist statisch und kann überall mit Image::uploadTemp() verwendet werden. Es gibt die vom Bildtool benötigten Daten zurück.
Die upload Funktion dient einem anderen Zweck. Es stellt den endgültigen Upload für den Block dar, ist jedoch nicht statisch. Bei dieser Methode wird davon ausgegangen, dass das Bild bereits vorübergehend hochgeladen wurde und der $json geladen und analysiert wurde. Daher können wir diese Funktion wie folgt verwenden:
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 ();Nun führt der Block den endgültigen Upload durch und wird als JSON gespeichert.
Es ist unmöglich, alle verfügbaren Blöcke zu unterstützen, sodass wir unsere eigenen Blöcke auf einfache Weise implementieren können. Ein Standardblock sieht wie folgt aus:
use BumpCore EditorPhp Block Block ;
class MyCustomBlock extends Block
{
public function render (): string
{
return view ( ' blocks.my-custom-block ' , [ ' data ' => $ this -> data ]);
}
}Wie Sie sehen, müssen wir standardmäßig nur die Rendering-Logik implementieren. Es geht jedoch um mehr als nur das Rendern.
Es gibt mehrere Möglichkeiten, auf die Daten eines Blocks zuzugreifen. Im folgenden Beispiel sehen Sie verschiedene Methoden für den Zugriff auf Blockdaten:
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! ' );
// ...
}Sie können eine der oben genannten Methoden wählen, um auf die Daten des Blocks zuzugreifen und sie zu bearbeiten. Darüber hinaus können Sie mit den folgenden Methoden überprüfen, ob die Daten vorhanden sind oder nicht:
$ data -> has ( ' custom.data ' );
// or
$ this -> has ( ' custom.data ' ); Eine Validierung der Daten ist nicht erforderlich, kann Ihre Daten jedoch sicherer machen. Die Validierung von Blockdaten ist recht einfach. Wir müssen unserem Block nur eine rules hinzufügen:
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 ' ,
];
}
// ...
}Wenn die Validierung der Blockdaten fehlschlägt, sind die Daten leer. Die Datenvalidierung wird mithilfe der Validierungsbibliothek von Laravel durchgeführt. Mehr darüber erfahren Sie in der Dokumentation von Laravel.
Wenn Sie möchten, können Sie den HTML-Code Ihrer Daten bereinigen. Es ist wichtig, Injektionen zu verhindern. Das Bereinigen von Daten ähnelt einer Validierung:
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 ' * ' ;
}
// ...
}Im Gegensatz zur Validierung werden bei der Bereinigung nur unerwünschte Tags und Attribute entfernt.
Wie bereits erwähnt, können wir mit EditorPhp gefälschte Daten generieren. Es ist jedoch erforderlich, für jeden Block eigene gefälschte Daten zu generieren. Um gefälschte Daten zu generieren, sollten wir unserem Block eine statische Methode hinzufügen:
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 ,
];
}
// ...
} Durch das Hinzufügen fake -Methode zu unserem Block wird EditorPhp nun auch MyCustomBlock bei der Generierung gefälschter Daten einbeziehen. Weitere Informationen finden Sie in der Dokumentation von FakerPHP.
Es gibt einige Laravel-Funktionen, die Ihnen das Leben ein wenig erleichtern werden.
Sie können EditorPhpCast verwenden, um das Attribut Ihres Modells in EditorPhp Instanz umzuwandeln.
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 ();Wenn Sie Cast verwenden, können Sie auch innerhalb von Blockinstanzen auf Ihr Modell zugreifen:
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.
}
}
// ...
}Sie können das Modell auch vom Block aus ändern.
EditorPhp Instanz kann als Antwort zurückgegeben werden. Wenn die Anfrage JSON erwartet, wird sie selbst in JSON codiert. Andernfalls wird es in HTML gerendert.
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 ;
}
} Sie können auch EditorPhp Instanz verwenden, um die Innenansicht direkt zu rendern:
{{-- blog.show.blade.php --}}
< article >
< h1 > {{ $post -> title } } </ h1 >
< div > {{ $post -> content } } </ div >
</ article >Ich muss das überprüfen, bevor ich es dokumentiere.
Sie können mit dem Befehl block:make <name> einen brandneuen Block erstellen:
php artisan make:block CustomImageBlock Der neue Block wird im Verzeichnis app/Blocks abgelegt.
Beiträge sind willkommen! Wenn Sie einen Fehler finden oder einen Verbesserungsvorschlag haben, öffnen Sie bitte ein Problem oder erstellen Sie eine Pull-Anfrage. Nachfolgend finden Sie einige Richtlinien, die Sie befolgen sollten:
Bitte geben Sie eine detaillierte Beschreibung Ihrer Änderungen und des dadurch gelösten Problems an. Ihr Beitrag wird überprüft und es besteht die Möglichkeit, Feedback zu geben. Vielen Dank für Ihre Hilfe, dieses Projekt besser zu machen!
