Download the PHP package nadar/quill-delta-parser without Composer

Quill Delta to HTML Parser

A PHP library to parse Quill WYSIWYG editor deltas into HTML - flexible and extendable for custom elements. Every element is parsed by the same mechanism, making it easy to extend and understand. It also sanitizes the output value, making it more secure, especially when using user-generated text.

What is Quill? Quill is a free, open source WYSIWYG editor built for the modern web. With its modular architecture and expressive API, it is completely customizable to fit any need.

Installation

The package is available only through Composer:

Usage

Where $json is the ops JSON array from Quill, for example:

This would render the following HTML:

Extend the Parser

To extend the Parser by adding your own listeners (this can be the case if you are using Quill plugins which generate custom delta code), you have to decide whether it's an:

• Inline element: Replaces content with new parsed content, mostly the case when working with Quill extensions.
• Block element: Encloses the whole input with a tag, for example, a heading.

An example for a mention plugin that generates the following delta {"insert":{"mention":{"id":"1","value":"Basil","denotationChar":"@"}}}; an inline plugin could look like this:

Now register the listener:

Override Built-in Listeners

Certain listeners (image, video, color) produce an HTML output which may not suit your use case, so you have the option to override the properties of those plugins and re-register the Listener. Here's an example with the image tag:

If you want to replace a class with your own image class, use overwriteListener to achieve the same result, but with your totally custom class. The reason is that listeners are registered by their class names.

Or, of course, when you have a separate file for your class:

Security: URI Scheme Validation

Delta attributes like link, image and video are usually attacker controlled (user generated content) and end up in rendered href or src HTML attributes. Since version 3.7.1 the built-in listeners validate those values against a scheme allowlist, so payloads like javascript:alert(1) can no longer be injected into the markup:

• Link: only http, https, mailto and tel schemes are rendered, everything else is neutralized to href="#". Configure via Link::$safeSchemes.
• Image: only http and https as well as data: URIs with an image/* media type (e.g. pasted base64 images) are rendered, unsafe values are not rendered at all. Configure via Image::$safeSchemes and Image::$dataMediaTypes.
• Video: only http and https schemes are rendered, unsafe values are not rendered at all. Configure via Video::$safeSchemes.

URIs without any scheme (relative paths, anchors like #section, protocol-relative URLs like //example.com) are always considered safe. The validation is case insensitive and normalizes control characters prior to detection, so bypass attempts like JaVaScRiPt: or jav\tascript: are detected as well.

Debugging

Sometimes, understanding how delta is handled and parsed can be challenging to debug. Therefore, you can use the debugger class, which will print a table with information about how the data is parsed.

There is also a built-in Docker Compose file which provides access to the output.php file. The output.php helps to directly write content with the Quill editor while displaying what is rendered, including all debug information. To run this Docker webserver, execute the following command in the root directory of your Git repository clone:

and visit http://localhost:5555/ in your browser.

Credits

• Lode Claassen
• Dean Blackborough