Tiptap Php Laravel Package

Product Decisions This Supports

Build vs. buy for rich-text rendering. The core decision this package informs is whether to hand-roll a ProseMirror/Tiptap JSON → HTML renderer on the server or adopt a maintained one. Writing a schema-aware serializer (marks, nested nodes, attribute merging, HTML attribute passthrough) is weeks of engineering plus indefinite maintenance; this package collapses that into a Composer dependency. Default recommendation: buy, and reserve the build option for cases where schema conformance is a hard requirement.

Content model standardization (roadmap-level). It enables a single canonical content format — Tiptap JSON — across editor, API, storage, and delivery. That is a platform decision with long tails: it determines how easily you add new block types (details/accordions, tables, images with width/height), how you migrate legacy HTML, and how you export to email, RSS, PDF, or a search index. Choosing "Tiptap JSON as the system of record" is a durable architectural commitment; this package is the PHP-side enabler.

Feature bets it unlocks or de-risks:

• Server-side rendering for SEO and link previews — render stored JSON to HTML at request time or at publish time, without a headless browser or a Node service in the critical path.
• Email and syndication channels — getHTML() for newsletters, digests, RSS, and AMP; getText() with configurable blockSeparator for plain-text variants and search indexing.
• Content ingestion and migration — convert legacy HTML into Tiptap-compatible JSON (getDocument()/getJSON()) as the front door for imports from WordPress, CMS exports, or third-party feeds.
• Trust and safety at write time — sanitize() strips script/unsafe markup on ingestion of user-generated content, normalizing input before persistence rather than cleaning at render.
• Content ops and programmatic edits — descendants() allows bulk transformations (heading level normalization, link rewriting, attribute backfills) as backfill jobs rather than editorial manual work.

Prioritization input. Because the PHP API deliberately mirrors the JS API, front-end engineers' existing Tiptap knowledge transfers to backend work — a real velocity argument when sizing roadmap items like "rich-text comments," "collaborative docs," or "AI-assisted editing" that need server-side content handling.

When to Consider This Package

Strong fit when:

• The stack is PHP/Laravel and the editor is Tiptap/ProseMirror (or you're willing to adopt it).
• You need HTML out of stored JSON server-side — SEO pages, emails, feeds, PDFs, or API responses consumed by non-JS clients.
• You want one content pipeline instead of a Node rendering microservice and a PHP app that disagree about markup.
• You need sanitization or normalization as part of ingestion, not as an afterthought at render.
• You want extension parity with the front end: StarterKit, headings with configurable levels, links, images with dimensions, details, and code blocks with syntax highlighting.

Look elsewhere or scope carefully when:

• Full ProseMirror schema fidelity is required. The README explicitly notes partial schema adherence (e.g., marks disallowed inside CodeBlock). If you validate content against a strict schema or rely on edge-case node relationships, budget for gaps or upstream issues.
• Sanitization is a security boundary for hostile input at scale. Treat sanitize() as content hygiene, not as a replacement for a hardened, independently audited HTML sanitizer. Get a security review before it becomes your only defense for multi-tenant UGC.
• Shiki highlighting is desired but Node.js is unavailable in production. The Shiki path shells out via spatie/shiki-php and requires the npm package; the highlight.php extension is the pure-PHP alternative but needs CSS loaded client-side.
• The editor isn't Tiptap. For Markdown-centric or non-ProseMirror editors, a CommonMark/HTML toolchain is a simpler fit.
• Ecosystem risk tolerance is low. Public dependents are effectively zero, which is a weak signal of third-party production validation. It's a first-party-adjacent package from the Tiptap organization (ueberdosis), MIT-licensed, actively released (2.x line through 2.2.0 with security-hardening work on attribute rendering), but it is not a wide-adoption commodity. Plan for a fallback: the JSON is an open format, so an escape hatch to a JS renderer or a custom serializer remains available.

Decision rule: adopt behind a thin internal abstraction (one service class wrapping Editor) so the package can be swapped without touching feature code, and pin the version.

How to Pitch It (Stakeholders)

To executives (one paragraph): We're standardizing rich-text content on the Tiptap format, which our editor already produces. This package is the server-side counterpart: it turns that stored content into clean HTML for SEO pages, emails, and feeds, converts legacy HTML into the new format, and sanitizes user input on the way in. It's MIT-licensed, maintained by the same organization that builds the editor, and small enough to adopt in days rather than the weeks of custom work an in-house renderer would require. The main caveat is limited third-party adoption, so we'll wrap it in a small internal layer to keep our options open.

To engineering (the ask): Add ueberdosis/tiptap-php and expose it through a single rendering service — renderHtml(), toJson(), toText(), sanitize(). Keep extension configuration in one place so front-end and back-end agree on node/mark support. Pin the minor version, watch the changelog (attribute rendering and link-attribute handling have been tightened recently), and treat sanitize() as defense-in-depth alongside our existing input validation. Do not adopt the Shiki extension unless Node.js is a sanctioned production runtime; default to CodeBlockHighlight if syntax highlighting is in scope.

Success measures for the pilot: time-to-first server-rendered article page, elimination of any Node rendering service from the deploy topology, and zero content-fidelity regressions in an HTML round-trip test corpus drawn from real stored documents.