Download the PHP package bumpcore/editor.php without Composer

Editor.php

Editor.php is a package designed to assist in parsing and manipulating the output of Editor.js with ease. It can be used with either vanilla PHP or with Larave. Laravel offers few additional features.

Table Of Contents

• Version Table
• Quick Start
• EditorPhp
  • Creating Instance
  • Accessing Blocks
  • Rendering HTML
  • Faking
  • Additional
  • Converting to an array
  • Converting to JSON
  • Time & Version
  • Macros
• Blocks
  • Registering Blocks
  • Extending Blocks
  • Creating Custom Blocks
  • Accessing Block's Data
  • Validating Block Data
  • Sanitizing Block Data
  • Fake Data Generation
• Laravel Only Features
  • Cast
  • Response
  • Views
  • Publishing Views and Configuration
  • Commands
• Contribution

Version Table

Quick Start

Install package by:

Editor.php is really simple to get started;

Editor.php supports following blocks;

• Attaches
• Checklist
• Code
• Delimiter
• Embed
• Header
• Image
• Link Tool
• List
• Paragraph
• Personality
• Quote
• Table
• Warning

All of them have default validation rules and views to render. However, customizing validation and views is highly recommended.

EditorPhp

The EditorPhp class is the main class for managing blocks. You can access, render, convert to an array, and convert to JSON through this class.

Creating Instance

There are two ways to create a new instance of EditorPhp:

Both syntaxes are equal, and there's almost no difference between them.

Accessing Blocks

You can access blocks through the blocks property.

Blocks are stored as Illuminate\Support\Collection . By using collection methods, you can manipulate blocks as you wish. You can learn about collections in Laravel's documentation.

Rendering HTML

Rendering HTML is very straightforward. There are multiple ways to render your instance:

Again, all three cases are the same, with no one above another. You can use whichever one you like the most.

By the default, you have two options for the default block's templates; tailwindcss and Bootstrap 5 . Default used template is tailwindcss You may switch templates by:

You can learn more about rendering in creating custom blocks section.

Faking

You can generate fake data with EditorPhp .

You can learn more about generating fake data for the blocks in fake data generation.

Additional

Converting to an array

You can convert your instance to an array using the toArray() method.

Converting to JSON

You can convert your instance to JSON using the toJson(/** options */) method. This method is useful when you manipulate your instance.

Time & Version

You can access time and version:

The time property is a Carbon instance. You can learn more about it in Carbon's documentation.

Macros

You can register macros and use them later. Macros are based on Laravel.

Blocks

Blocks are the main building parts of the EditorPhp editor. You can manipulate them as you wish, and the best part is that you can use them to store your block's logic. For example, the image block requires an uploader to work. You can implement the corresponding functionality in the BumpCore\EditorPhp\Blocks\Image class.

Registering Blocks

Before we jump into learning how to customize blocks, here's how you can register your blocks:

When registering blocks, it's important to use the correct key. The key must be the same as the Editor.js 's type key. To clarify:

In this output, our type key is paragraph , so we should register it as 'paragraph' => Paragraph::class . This might vary depending on how you register your blocks in Editor.js . Default blocks in EditorPhp are registered using camelCase .

Extending Blocks

As mentioned previously, almost all blocks are supported in EditorPhp . However, they mostly handle the validation of block data and rendering. For the Image block to work properly, it requires an upload. We can implement this upload logic in the Image class:

As you can see, we have extended the Image block and added two functions to handle our uploads.

The uploadTemp function performs a temporary file upload. This method is static and can be used anywhere using Image::uploadTemp() . It returns the data required by the image tool.

The upload function serves a different purpose. It represents the final upload for the block but is not static. This method assumes that the image has already been uploaded temporarily and the $json has been loaded and parsed. Therefore, we can use this function as follows:

Now the block performs the final upload and is saved as JSON.

Creating Custom Blocks

It is impossible to support all blocks out there, so we can implement our own blocks in an easy way. A standard block looks like the following:

As you can see, by default, we just need to implement the rendering logic. However, there's more than just rendering.

Accessing Block's Data

There are multiple ways to access a block's data. In the example below, you can see different methods for accessing block data:

You can choose any of the above methods to access and manipulate the block's data. Additionally, you can also check whether the data exists or not using the following methods:

Validating Block Data

Validating data is not required, but it can make your data safer. Validating block data is quite easy. We just have to add a rules method to our block:

When validating the block's data fails, the data will be empty. Data validation is performed using Laravel's validation library. You can learn more about it in Laravel's documentation.

Sanitizing Block Data

You can purify the HTML of your data if you wish. It's important to prevent injections. Purifying data looks much like validation:

Unlike validation, purifying will only strip unwanted tags and attributes.

Fake Data Generation

As we mentioned earlier, we can generate fake data with EditorPhp . But it requires to generate each block's own fake data. To generate fake data we should add static method to our block:

By adding fake method to our block, now EditorPhp will also include MyCustomBlock when generating fake data. You can learn more about at FakerPHP's documentation.

Laravel Only Features

There's few Laravel features that will make your life little bit easier.

Cast

You can use EditorPhpCast to cast your model's attribute to EditorPhp instance.

Also if you are using cast, you may access your model within block instances:

You can also alter the model from the block.

Response

EditorPhp instance can be returned as response. If request expects JSON it will encode it self to JSON. Otherwise it will be rendered into html.

Views

You may also use EditorPhp instance to render inside view directly:

Publishing Views and Configuration

Got to check this before documenting it.

Commands

You can create brand new block with block:make <name> command:

New block will be placed under app/Blocks directory.

Contribution

Contributions are welcome! If you find a bug or have a suggestion for improvement, please open an issue or create a pull request. Below are some guidelines to follow:

• Fork the repository and clone it to your local machine.
• Create a new branch for your contribution.
• Make your changes and test them thoroughly.
• Ensure that your code adheres to the existing coding style and conventions.
• Commit your changes and push them to your forked repository.
• Submit a pull request to the main repository.

Please provide a detailed description of your changes and the problem they solve. Your contribution will be reviewed, and feedback may be provided. Thank you for your help in making this project better!