Symfony Carve Laravel Package

Product Decisions This Supports

• Build vs. buy for markup rendering. Carve is a markup language with a maintained PHP parser (carve-php); this bundle is the Symfony/Twig integration layer. Adopting it replaces a bespoke parser, sanitizer, and include-resolver effort with a dependency — the classic "don't build your own transpiler" call, made cheaper by the small surface area (a renderer plus two Twig filters).
• Feature: content partials and reusable snippets (new in 0.1.5). Opt-in file-backed rendering via CarveRenderer::renderFile() / renderFileWithReport() lets authored documents include other documents from a single absolute include_root. This unlocks the patterns product teams actually ask for: shared admonition/legal/disclaimer blocks, per-locale snippet libraries, docs sections assembled from fragments, and email or in-app help content with a common header/footer — without a CMS.
• Feature: caching strategy owned by the application. renderFileWithReport() returns the resolved and attempted include targets, so we can key our own cache on the exact dependency set of a rendered document. That means correct invalidation when a partial changes, and no guessing at a directory-wide mtime. This is the difference between "we can cache rendered output safely" and "we re-render on every request."
• Roadmap signal: filesystem access is deliberately opt-in and narrow. render() and the Twig filters still accept anonymous strings only and never touch disk. Content that arrives from users, a database, or an API stays on the string path; only filesystem-authored content goes through renderFile(). We can adopt includes for editorial content without widening the blast radius of any user-content rendering path.
• Operational decision: logging without path leakage. Warnings routed to the logger deliberately omit resolver details, so include failures won't spill absolute filesystem paths into application logs or error trackers. Good default; if we need diagnosability we consume the report rather than parsing log lines.
• Dependency posture. Requiring carve-php ^0.1.9 and adding psr/log at runtime (for the optional warning logger) is a clean, low-ceremony bump — no framework coupling, no service-provider config sprawl.
• Sequencing note for a Laravel-first roadmap. This is a Symfony/Twig bundle. In a Laravel/Blade codebase the value sits almost entirely in carve-php plus a thin rendering service we write ourselves; the Twig filters and the Symfony wiring are not reusable. That reframes the decision as "adopt the parser (buy) and own a ~50-line adapter" rather than "adopt this bundle."

When to Consider This Package

Consider it when:

• You are on Symfony with Twig and want markup rendering as a service or filter with no custom glue; this release's file-backed path fits naturally into Twig-rendered editorial content.
• Editorial content genuinely benefits from composition. If your docs, help centre, or marketing content repeats blocks across pages, the include pass plus report-based cache keys is a real reduction in authoring and invalidation work.
• You want a modern markup dialect rather than strict CommonMark — Carve's feature set (semantic blocks, attributes) is the draw, and you accept the ecosystem trade-off.
• Your content trust boundary is clear. Filesystem-authored content goes through renderFile() with a pinned absolute include_root; user-supplied content stays on the string path. If you can state that split in one sentence, adoption is straightforward.
• You can absorb pre-1.0 churn. At 0.1.x, minor versions may still change method names, constructor signatures, or the report shape. Fine for internal tooling and content pipelines; a harder sell for a public API contract.
• You want cache correctness without building a dependency graph. Consuming the report is materially less work than instrumenting includes yourself.

Look elsewhere when:

• You need CommonMark/GitHub-flavored parity — rendered output must match GitHub, or you depend on the CommonMark test suite and its tooling.
• Untrusted authors supply templates with includes. Even with a pinned root, an include resolver is a path-traversal and disclosure surface. Prefer a string-only renderer with no filesystem access, or a sandboxed template engine, for anything user-authored.
• You are Laravel-only and want a supported integration. You would be maintaining an adapter against a Symfony bundle's dependency graph; evaluate carve-php directly instead.
• You need stability guarantees — LTS, semver, deprecation policy, security-response commitments. None of that is offered at 0.1.x.
• Your needs are trivial (occasional string-to-HTML with no includes). A single carve-php call is enough; the bundle is surplus.
• You require streaming or incremental rendering of very large documents; this is a whole-document renderer.

How to Pitch It (Stakeholders)

For executives (one paragraph). We can render our documentation and product copy with a small, well-scoped open-source parser instead of maintaining our own markup code. The latest release adds the piece we were missing for composed content: documents can pull in shared fragments from one approved folder, and the renderer tells us exactly which fragments each page used — so caching stays correct and stale pages stop shipping. It is deliberately opt-in: content that comes from users or the database is still rendered as plain text with no file access. The main caveat is maturity — the project is pre-1.0, so we should treat the public API as movable and confine it behind a thin internal service. And because it is a Symfony/Twig integration, in a Laravel codebase the realistic play is adopting the underlying parser and owning a small adapter. Recommendation: pilot on internal docs content, not on the customer-facing critical path.

For engineering (key points).

• New API: CarveRenderer::renderFile() and renderFileWithReport(). Requires an absolute include_root; there is no implicit working-directory fallback to reason about.
• render() and the Twig filters are unchanged and remain string-only — no filesystem access on those paths. Keep user/database-sourced content there and make that a test, not a convention.
• renderFileWithReport() exposes resolved and attempted include targets. Use that tuple as your cache key; it makes partial-level invalidation exact rather than directory-wide.
• Warnings sent to the logger omit resolver details by design (no absolute paths in logs). If you need to diagnose a failed include, read the report — don't log-scrape.
• Dependency changes: carve-php ^0.1.9 (required for the include pass) and psr/log added at runtime for the optional warning logger. Pin both; the carve-php floor is not optional.
• Security review should cover: who can write to include_root, whether symlinks or traversal can escape it, and whether include depth/cycles are bounded. Treat include_root as a trust boundary and mount it read-only where possible.
• Pre-1.0: wrap the renderer in our own small interface so a future rename of renderFileWithReport or a change to the report shape is a one-file change. Add a golden-file test over a representative document set to catch rendering drift on upgrade.
• For Laravel: skip the bundle wiring, depend on carve-php directly, bind a CarveRenderer-shaped service in the container, and reimplement the report/cache-key contract ourselves — it is small and keeps us off an unsupported integration path.