Shiki Php Laravel Package

Product Decisions This Supports

• Build vs. buy for documentation and content surfaces. This package is the "build" option for server-rendered code highlighting — no per-request vendor API, no SaaS contract, no data leaving your infrastructure. The real decision is build vs. outsource to Torchlight (hosted, near-zero setup, recurring cost, code snippets sent to a third party) vs. build with a pure-PHP highlighter (highlight.php, a Pygments port — no Node, but weaker fidelity to modern editor themes).
• Where highlighting lives in the architecture. Shiki uses the same TextMate grammars as VS Code, so output matches what developers see in their editor. That supports a product decision about consistency of experience: docs, blog, changelog, and in-app code samples all look like the IDE. Choose this if "code looks like the editor" is a stated quality bar; skip it if approximate coloring is acceptable and you want zero runtime complexity.
• Roadmap: code-centric features. The line-marking API (highlightLines, addLines, deleteLines, focusLines) directly enables diff walkthroughs, tutorial step-throughs, "what changed in this release" changelogs, and annotated code review views. That's a roadmap unlock, not just a rendering detail — it's the difference between showing code and teaching code.
• Roadmap: theming and dark mode. Dual-theme support (2.2.0+) and custom VS Code theme JSON mean light/dark parity is a configuration concern, not a redesign. If dark mode for docs is on the roadmap, this removes a workstream.
• Laravel-specific prioritization. If the stack is Laravel, the decision collapses to spatie/laravel-markdown (which wraps this) versus a hand-rolled pipeline. That's a strong argument for not building custom Markdown-to-HTML rendering — the Blade grammar ships in the box, which matters for any product that documents Laravel code.
• Use cases that justify it: developer documentation sites, blog/changelog engines, CMS-rendered Markdown, LMS or tutorial platforms, API reference pages with multi-language samples, internal style guides, and PR/diff summarization in admin tooling.
• Use cases that do not: user-generated content at high volume, real-time collaborative editors, anything needing per-request low-latency highlighting, or environments where you cannot guarantee a Node binary.

When to Consider This Package

Adopt when most of these hold:

• Content is pre-rendered or cached — docs, blog posts, changelogs, CMS pages — so the subprocess cost is paid once, not per viewer.
• Your deploy target can reliably provide Node 20+ and an npm install shiki step alongside Composer. This is the single biggest gate.
• You're on Laravel or league/commonmark, where first-party integration paths (laravel-markdown, commonmark-shiki-highlighter) already exist.
• Visual fidelity matters — brand-consistent, editor-grade themes, dark/light pairs, and language coverage including Blade and Antlers.
• You need line-level semantics (added/deleted/highlighted/focus) for educational or diff-oriented content.
• You want MIT-licensed, self-hosted with no vendor data-sharing review needed.
• Traffic to highlighted pages is moderate and cacheable; large code blocks are fine since 2.3.3 moved input to stdin.

Look elsewhere when:

• You cannot run Node in production (restricted containers, shared hosting, policy-blocked runtimes). highlight.php is the pragmatic fallback; Torchlight is the hosted fallback.
• Highlighting happens on the request path at high volume. Each call shells out to a Node process; without caching this becomes a latency and CPU problem.
• You only render code in the browser. Client-side Shiki or a lightweight JS highlighter avoids the PHP↔Node bridge entirely.
• You need guaranteed long-term maintenance SLAs. This is a single-maintainer-adjacent Spatie OSS package with no commercial support tier; the v1→v2→v4 Shiki upgrades have been breaking (the availability-inspection methods were removed in 2.0.0 and restored in 2.1.0).
• Compliance forbids arbitrary subprocess execution in your runtime.
• Your team is not PHP-centric and already has a JS build pipeline — the bridge adds a moving part without adding capability.

Adoption risk to plan for: the Node-version coupling (NVM users are told to symlink into /usr/local/bin) and the Shiki major-version treadmill are the two operational failure modes seen in the changelog. Budget a CI job that exercises the highlight path, and pin both the Composer and npm sides.

How to Pitch It (Stakeholders)

For executives — one paragraph: Code samples are a credibility surface for any developer-facing product, and today we either under-invest in them or pay a vendor per render. spatie/shiki-php lets us highlight code server-side using the same engine as VS Code, under an MIT license, with no vendor contract and no code leaving our infrastructure. It's a small, well-maintained Spatie package with an active changelog through 2026, and for Laravel projects it plugs into our existing Markdown pipeline rather than requiring a new one. The trade-off is a Node runtime in our deploy image — an operational cost, not a licensing or lock-in cost. Recommendation: adopt for pre-rendered docs and content, cache the output, and revisit only if we ever need per-request highlighting.

For engineering — the short version: We add spatie/shiki-php plus the shiki npm package to the build image (Node 20+). Highlighting is a Node subprocess; treat it as a build-time or cache-warming operation, never a hot path. We get 100+ languages, Blade and Antlers grammars included, custom VS Code theme JSON, dual light/dark themes, and line-level annotations (highlightLines, addLines, deleteLines, focusLines) that we can style with our own CSS. On Laravel we use spatie/laravel-markdown and get most of this for free; on plain league/commonmark we use spatie/commonmark-shiki-highlighter. Two things to own explicitly: (1) pin both the Composer and npm versions — Shiki majors have broken us historically — and (2) add a smoke test in CI that highlights a large code block, since that path previously failed with an argument-list-too-long error before 2.3.3. Cache rendered HTML keyed on code hash + language + theme + line markers, and the performance question disappears.

Known alternatives, stated plainly: Torchlight if we'd rather pay than operate; highlight.php if Node is a hard no; client-side Shiki if highlighting never needs to be server-rendered.