Tiptap Php Laravel Package

Getting Started

Start by installing the package via Composer:

composer require ueberdosis/tiptap-php

The core entry point is Tiptap\Tiptap, which parses Tiptap JSON (ProseMirror document format). The simplest use case is rendering editor content to HTML on the server:

use Tiptap\Tiptap;

$tiptap = new Tiptap();
$html = $tiptap->render([
    'type' => 'doc',
    'content' => [
        ['type' => 'paragraph', 'content' => [['type' => 'text', 'text' => 'Hello world!']]]
    ]
]);
// Outputs: '<p>Hello world!</p>'

Check the src/ folder in the repo for the source code structure—src/Node/, src/Mark/, and src/Renderer/ are especially useful.

Implementation Patterns

• Content Sanitization: Before storing editor output in the DB, validate it using Tiptap::validate() to catch malformed documents:

  $isValid = $tiptap->validate($jsonDocument);
  if (!$isValid) { /* log/report invalid structure */ }
  

• Custom Rendering: Override default renderers (e.g., to add CSS classes or adapt output) by extending Tiptap\Renderer\Html and registering custom node/mark handlers.
• Extension Integration: For advanced use (e.g., custom blocks or marks), define an extension class extending Tiptap\Extension and configure it via Tiptap::configure([...]). This ensures the server-side renderer matches the client-side editor behavior.
• Content Transformation: Use the Transform API to apply structured edits (e.g., auto-convert headings to title case, strip empty paragraphs) using Tiptap\Transformer\ChainTransformer.
• Laravel Tip: In Laravel, bind Tiptap as a singleton in a service provider and inject it into controllers/services handling rich-text content.

Gotchas and Tips

• Version Mismatch: Ensure your Tiptap JSON version (from the editor) matches what the PHP library expects. Newer Tiptap versions introduce schema changes; verify the schemaVersion in your editor’s output.
• Security: Never trust raw JSON input. Always validate before rendering or storing—even if render() internally sanitizes, validate() should run first for predictable behavior.
• Missing Nodes/Marks: If the editor uses extensions not bundled by default (e.g., BubbleMenu), you must register the corresponding PHP extension (or stub it with Tiptap\Node\Dummy) or rendering will fail.
• Debugging: Use Tiptap::debug($json) to print a tree representation of the document—helpful when troubleshooting why content renders incorrectly.
• Performance: Rendering is fast, but avoid recreating the Tiptap instance per request. Reuse it (e.g., as a shared service) since initialization involves extension loading and schema setup.
• Testing: Mock Tiptap in unit tests using predefined Tiptap JSON fixtures. A good practice is to store sample valid.json and invalid.json files under tests/fixtures/.