Laravel Laravel Package

Product Decisions This Supports

• Docs and developer-content roadmap. Any decision to ship a /docs, /blog, /changelog, API reference, or tutorial section implies a code-rendering decision. This package makes "syntax highlighting" a one-afternoon task instead of a two-sprint infrastructure project, so it de-risks committing to developer-facing content in the roadmap.
• Build vs. buy for presentation infrastructure. The realistic alternatives are: (a) client-side JS highlighting (highlight.js/Prism/Shiki-in-browser), (b) self-hosted Shiki via spatie/shiki-php, which drags a Node runtime into your PHP deploy, or (c) a hosted highlighting API. This package is the cheapest possible path to option (c) on Laravel, and the comparison is a legitimate PM decision rather than an engineering detail — it affects page weight, build pipeline complexity, and on-call surface.
• Time-to-market for technical marketing surfaces. Positioning pages, integration guides, SDK quickstarts, and comparison pages all live or die on readable code samples. Bundling a Blade component plus a CommonMark extension means content authors get diff highlighting, line focus, and multi-language blocks without engineering involvement per post.
• Feature scoping for content authoring. Because highlighting is server-side and cached, you can decide to support richer authoring affordances (highlighted line ranges, error/warning callouts, copy buttons, tabbed language switchers) that client-side libraries make awkward or slow.
• Vendor and cost modeling. Adoption forces an explicit answer to "do we pay for a highlighting service?" That's a small but real line item and a real dependency to track, and it's better decided deliberately at content-platform kickoff than discovered when the bill arrives.
• Not a differentiator, a hygiene factor. Treat this as table stakes for credibility with a developer audience. It should never appear on a roadmap as a feature; it should appear in the "how we ship docs" line of the platform plan.

When to Consider This Package

Adopt when:

• The app is Laravel and renders content server-side (Blade, or Markdown through CommonMark), and code samples appear in user-visible output.
• You want highlighting quality close to VS Code with no front-end JavaScript and no Node in the deploy image.
• The team has no appetite to own a highlighter — no theme maintenance, no grammar updates, no hydration issues.
• Traffic is cache-friendly. Rendering is a network call to a third party; the built-in caching is what makes this viable in production, so content that changes rarely and is read often is the sweet spot.
• The content set is genuinely developer-oriented. If you have twelve code blocks on the whole site, this is overkill.

Look elsewhere when:

• The front end is a SPA or a JS-rendered framework. Use Shiki or highlight.js directly in the browser and skip the API entirely.
• You have hard self-hosting, air-gap, or data-residency constraints. A third-party API receiving your code samples is a procurement and security conversation, and for some organizations a non-starter.
• Rendering happens in a hot path without effective caching (per-request, per-user, uncached previews). Latency and per-call cost both become problems.
• You are not on Laravel, or you're on an older Laravel version outside the package's support window.
• The requirement is truly minimal — plain <pre><code> with a lightweight client-side highlighter is free and adequate for a marketing site with a handful of snippets.
• The dependency count matters to you. The client is MIT-licensed and swappable, but the service behind it is a subscription with its own uptime and pricing history, and 120 stars / zero dependents means you are an early adopter, not part of a crowd.

How to Pitch It (Stakeholders)

For executives (one paragraph): Our developer-facing content — docs, guides, blog, changelog — is judged in the first three seconds, and code samples are the thing being judged. This package lets us render code at near-IDE quality inside our existing Laravel app in roughly a day of engineering, with no new servers, no build pipeline, and no JavaScript shipped to the reader. The engineering cost is negligible; the ongoing cost is a small subscription to the highlighting service, and the client code itself is MIT-licensed and easily replaced if we ever want to change vendors. Recommendation: adopt for the content platform, budget the service as a line item, and revisit if we outgrow it.

For engineering (the practical case): One Composer dependency, a Blade component, and a CommonMark extension. Highlighting is done server-side, so there is no client-side JS, no FOUC, no theme drift between environments, and no Node runtime in the container — which is the main reason to prefer this over the self-hosted Shiki route. Caching is built in and should be configured deliberately from day one; treat every render as a potential network call and cache aggressively. The package is a thin, readable API client, so the lock-in is to the service, not to the code — swapping to a local highlighter later is a contained change behind the same Blade/Markdown surface.

Risks to state out loud: third-party availability and pricing sit on our content rendering path (mitigated by caching and by server-rendered fallback of unhighlighted but readable <pre><code>); code samples leave our infrastructure, which needs a security sign-off in regulated contexts; and adoption is thin, so we should expect to be somewhat self-sufficient if issues arise. None of these are blockers for a content site; all of them would be for a critical product surface.