README

The ProseMirror JSON Parser (prosemirror-json-parser) is a versatile PHP library crafted for effortless conversion of ProseMirror/TipTap JSON Model content into HTML. With dependency-free operation and exceptional parsing speed, this library ensures high-performance HTML generation. Seamlessly integrating with TipTap and ProseMirror, it offers customization through easy addition or modification of nodes. Effortlessly install via Composer, utilize the toHtml function and explore extensive customization options for tailored JSON to HTML conversion.

It functions seamlessly with both TipTap and ProseMirror because TipTap is built upon ProseMirror.

Key Features:

• Dependency-free: No additional libraries required for this parser.
• Exceptional speed: Offers high-performance parsing capabilities.
• Highly extendible: Enables the addition of custom nodes as per your requirements.
• 100% Code Coverage and Testing: Ensures comprehensive test coverage, guaranteeing reliability and stability.
• Robust out-of-the-box HTML generation: Generates high-quality HTML seamlessly without requiring modifications, ensuring ease of use and reliability.

Installation & Usage

To install the library using Composer, execute the following command:

composer require nadar/prosemirror-json-parser

After installing the library, integrate the parser into your project. Utilize the toHtml function to convert your JSON value into renderable HTML code. Note that the toHtml function solely accepts an array. Therefore, if your content is in JSON format, employ json_decode($json, true) to initially convert the JSON string into an array and pass it toHtml(json_decode($json, true)).

$html = (new Nadar\ProseMirror\Parser())
    ->toHtml($json);

Extending & Customizing

Each node corresponds to a callable function within the parser, using the node's name as the key. This setup allows for easy addition or modification of nodes.

For example, to adjust the rendering of the image node, you can include your own function into the parser using the replaceNode() method:

$html = (new \Nadar\ProseMirror\Parser())
    ->replaceNode(\Nadar\ProseMirror\NodeType::image, fn(\Nadar\ProseMirror\Node $node) => '<img src="' . $node->getAttr('src') . '" class="this-is-my-class" />')
    ->toHtml($json);

To see all default nodes declared, refer to the NodeType class.

If you have a custom node with a specific name, you can add it to the parser using the addNode() method:

$html = (new \Nadar\ProseMirror\Parser())
    ->addNode('myCustomNode', fn(\Nadar\ProseMirror\Node $node) => '<div class="my-custom-node">...</div>')
    ->toHtml($json);

The addNode() and replaceNode() methods are almost identical internally, except that replaceNode should only be used when altering the output of default nodes. You can view all by-default declared nodes in the NodeType class.

Customizing Marks

In addition to customizing nodes, you can also customize how marks (like bold, italic, link, etc.) are rendered without replacing the entire text node renderer. This is particularly useful when you want to customize the output of specific marks.

For example, to customize the link mark to add additional attributes:

$html = (new \Nadar\ProseMirror\Parser())
    ->replaceMark('link', fn(\Nadar\ProseMirror\Mark $mark, string $text) => 
        '<a href="' . $mark->getAttr('href') . '" class="custom-link" rel="noopener">' . $text . '</a>'
    )
    ->toHtml($json);

You can also use the MarkType enum for type safety:

$html = (new \Nadar\ProseMirror\Parser())
    ->replaceMark(\Nadar\ProseMirror\MarkType::link, fn(\Nadar\ProseMirror\Mark $mark, string $text) => 
        '<a href="' . $mark->getAttr('href') . '" class="custom-link" rel="noopener">' . $text . '</a>'
    )
    ->toHtml($json);

You can also add custom mark renderers for your own mark types:

$html = (new \Nadar\ProseMirror\Parser())
    ->addMark('highlight', fn(\Nadar\ProseMirror\Mark $mark, string $text) => 
        '<mark class="highlight">' . $text . '</mark>'
    )
    ->toHtml($json);

Default marks that can be customized include: bold, italic, underline, strike, and link.

The addMark() and replaceMark() methods work similarly to their node counterparts - use replaceMark() for customizing default marks and addMark() for adding new custom mark types. Both methods accept either a MarkType enum or a string for the type parameter.

List Item Paragraph Handling

By default, the parser produces clean HTML for list items without wrapping content in paragraph tags: <ul><li>text</li></ul>.

If you need the previous behavior where list items were wrapped in paragraph tags (<ul><li><p>text</p></li></ul>), you can enable it:

$html = (new \Nadar\ProseMirror\Parser())
    ->setWrapParagraphsInListItems(true)
    ->toHtml($json);

Note: Paragraphs outside of list items will always be rendered with <p> tags. This option only affects paragraphs that are direct children of list items.

The text and image were enhanced by an AI, as English is not my first language and I am quite lazy. Even this sentence was generated by AI.