Engine Laravel Package

Product Decisions This Supports

Build vs. buy for code rendering. This package lets you self-host Torchlight's annotation and rendering pipeline entirely in PHP. It directly answers the question: do we pay for hosted syntax highlighting (Torchlight API, or a similar SaaS), do we shell out to a Node CLI, or do we run an MIT-licensed engine in-process? For a Laravel shop, it collapses a third-party dependency into a composer require. The v1.0.0 release materially strengthens this decision: a 1.0.0 tag with the rendering engine moved onto Phiki 2 means the API surface is now something we can commit a roadmap to rather than coding against a pre-1.0 moving target.

Feature decisions around developer-facing content. Annotated code is a differentiator, not a nicety: line highlighting, inline callouts, diff views, error/warning markers. If your roadmap includes docs, tutorials, changelogs, API references, course material, or a developer blog, this package is the enabler for "code samples that teach" rather than "code samples that are merely colored." The release notes flag "new features" alongside the Phiki 2 upgrade — worth a 30-minute read of the README before planning the next content epic, since new annotation primitives may change what you can promise design.

Architecture and platform decisions. Choosing this removes Node.js from your build and deploy pipeline (relevant if you're currently on the CLI-based Torchlight workflow), eliminates an outbound HTTP call per rendered snippet, and makes rendering deterministic and version-pinned. That's a real win for CI reproducibility and for air-gapped or regulated environments. Riding on Phiki 2 also means our grammar/theme coverage tracks an actively developed upstream engine rather than a bespoke one — that lowers the long-term "we own a rendering engine" exposure.

Data governance / compliance decisions. Code samples never leave your infrastructure. For internal documentation, customer-facing docs that quote proprietary snippets, or anything under a security review, "no external API call" is often the decision-maker rather than the feature set.

Cost modeling. Replaces a per-seat or per-request hosted subscription with zero marginal cost. Worth quantifying against expected page/snippet volume before committing either way.

Upgrade-cost decision (new). v1.0.0 bundles "refactors, bug fixes and new features" with the Phiki 2 engine bump. If we are already on a 0.x version, treat this as a planned migration rather than a patch bump: budget a spike, snapshot the rendered HTML before and after, and expect output deltas. That's cheap if we cached rendered output at publish time; expensive if we render on every request with no golden-file tests.

When to Consider This Package

Adopt when most of the following hold:

• Your application is PHP/Laravel and rendering happens server-side or at cache-warm time.
• You produce meaningful volume of code-heavy content and want annotations as a first-class feature, not a bolt-on.
• You want to remove an external API dependency, a Node runtime, or both from your stack.
• You need output stability — pinned versions producing byte-identical HTML across deploys. Post-1.0.0 this is stronger: pin ^1.0 and you get a SemVer contract instead of 0.x churn, at the cost of the occasional minor upgrade that shifts rendered output.
• You have a place to cache rendered HTML (full-page cache, CDN, or a render-on-publish step in your CMS).

Look elsewhere when:

• Your stack isn't PHP. Astro, Next, Docusaurus, Hugo, and most static-site generators should use Shiki or rehype-based highlighting directly. Running a PHP renderer inside a JS build pipeline is the wrong seam.
• Content volume is low. A handful of snippets doesn't justify a self-hosted engine; the hosted service or a client-side highlighter is cheaper in total cost of ownership.
• You need bleeding-edge grammar coverage. This is a smaller risk than it was — the Phiki 2 upgrade inherits that engine's grammar/theme set — but still verify bundled languages and themes against your actual content. This remains the most common source of "works in the demo, fails on our docs" surprises.
• You need guaranteed long-term vendor support. Public adoption is still thin, which remains a genuine signal: this is a small-ecosystem component, likely maintained alongside a larger companion package. 1.0.0 helps on API stability but not on maintainer headcount. It's MIT and self-contained, so forking is viable — but only if your team is willing to own that fork. If not, that's a real risk to price in.
• You're mid-migration between major engines. 0.x → 1.0.0 is not a drop-in for everyone; if you can't absorb a rendering-output review cycle in the current sprint, defer rather than rush it.
• You're rendering at high request volume without caching. Benchmark first; treat rendered output as something to cache, not recompute per request.

How to Pitch It (Stakeholders)

For executives — one paragraph: Torchlight Engine is an MIT-licensed PHP package that renders highlighted, annotated code samples directly inside our application. It replaces two things we'd otherwise carry: a paid third-party rendering API and a Node.js runtime in our deploy pipeline. Code never leaves our servers, there's no per-request cost, and output is version-pinned and reproducible. It has just reached v1.0.0, which means a stable API we can plan against and an upgrade to the more capable Phiki 2 rendering engine underneath. The remaining trade-off is unchanged: it's a low-profile open-source project with limited public adoption, which we mitigate by pinning the version, caching rendered output, and accepting that we could maintain a fork if needed.

For engineering: composer require torchlight/engine — no infrastructure changes, no new runtime, no outbound network calls. Rendering is deterministic and testable in-process, which means we can snapshot-test our docs output. Rendered HTML should be cached at publish time or at the edge rather than regenerated per request. For v1.0.0 specifically: read the README before bumping (the release notes defer to it), snapshot rendered HTML before and after because the Phiki 2 bump plus refactors can change output, and re-validate grammar/theme coverage plus render latency in the same spike you were already running.

For product/design: This unlocks annotated code as a content capability — highlighted lines, inline commentary, and diff views inside tutorials and API docs. It's the mechanism behind "our docs explain the code," which is the part users actually notice. v1.0.0 adds features on top of that baseline; have someone skim the README changelog for anything authoring-facing before we scope the next docs iteration. It does not change authoring workflows on its own; treat CMS/editor integration as separate scope.