Filament Carve Laravel Package

Technical Evaluation

Architecture fit. The package is a thin Laravel integration layer over the Carve markup engine: a service provider, a publishable config/carve.php, an AsCarve cast for model attributes, and UI components (CarveEditor, CarveEntry, CarveColumn) that bind Carve rendering into admin/form/table surfaces. That is a good architectural fit for Laravel apps that need structured markup authoring without owning parser code — the coupling surface is a config file and a handful of namespaced classes, so the blast radius of upgrades is bounded and mostly mechanical.

Integration feasibility. Release 3.1.0 is a low-to-moderate effort upgrade. Two mechanical changes (namespace rename JeffersonGoncalves\Carve\ → MarkupCarve\LaravelCarve\, and config key rename profiles → converters) plus one dependency swap. The dependency swap is the substantive one: it moves the app off an abandoned third-party wrapper and onto the official markup-carve/laravel-carve bridge (^0.1.7). That is a supply-chain improvement, not a feature change — but it is a silent breaking change for anyone who references the old vendor classes directly or has a cached/published config.

Technical risk.

• The new bridge is ^0.1.7 — pre-1.0 semver. The caret constraint permits breaking changes on 0.2.0. This is now our most version-fragile dependency in the path, and it sits directly under our editor components.
• The config key rename fails at runtime, not at install: config/carve.php cached with profiles will produce missing-converter behaviour or exceptions after the bump, with no composer-level warning.
• Dual-package presence risk: if the old jeffersongoncalves/laravel-carve remains anywhere in the dependency graph (transitively or via a stale lockfile), we can get two providers registering overlapping bindings.
• Backports to 1.x and 2.x imply upstream is maintaining three majors concurrently. Good for our patching options, but it means our major-version choice must be an explicit decision, not drift.

Key questions.

• Which major are we actually on, and does the team intend to stay on it now that upstream supports three lines?
• Do we consume CarveEditor/CarveEntry/CarveColumn directly in app code, or only through the published config? The former multiplies the rename scope.
• Are custom render profiles defined anywhere outside config/carve.php (env vars, DB settings, per-tenant config)?
• What is our tolerance for a 0.x bridge under a core feature path — do we pin exactly, and who watches its releases?
• Has anyone verified the AsCarve source-handling fix (#8) against our own cast usage, or is that a fix we've never actually exercised?

Integration Approach

Stack fit. Verified compatibility across Laravel and PHP versions is not stated in the release notes and should be confirmed against the bridge's composer.json before scheduling. The components' shape suggests a Filament-style admin stack; the Filament major must be checked for alignment, since editor/table components are the most version-sensitive part of any admin framework integration.

Migration path. Contained and scriptable:

1. Bump the package minor (3.0.x → 3.1.0) and remove any explicit jeffersongoncalves/laravel-carve requirement.
2. Global rewrite of JeffersonGoncalves\Carve\ imports across app/, tests/, and any first-party packages.
3. Re-publish config/carve.php and diff it against the current file — do not overwrite blindly.
4. Port every custom entry from profiles to converters, preserving nesting and defaults.
5. php artisan config:clear in every environment, including CI and any container image that caches config at build time.

Compatibility. Treat this as a breaking release despite the minor version number, because the vendor namespace and config schema both change. Two verification gates: composer why jeffersongoncalves/laravel-carve must return empty after the bump, and a grep for the old namespace must return no hits outside vendor/.

Sequencing. Isolate on a branch; bump and rewrite imports first; then config port; then run the full suite with config:cache enabled (not just the default dev config) so the converters-key failure surfaces in CI rather than production. Staging validation should specifically exercise a model with an AsCarve attribute through editor → save → render, since that is the path both changes touch. Deploy only with a cache-clear step in the release runbook, and ship the config port in the same release as the composer bump — never separately.

Operational Impact

Maintenance. Net positive on maintenance debt: removing an abandoned package eliminates a class of "no upstream fix available" incidents. The cost is that we trade an abandoned dependency for an immature one. Recommend an exact pin on the bridge (0.1.7, not ^0.1.7) with a deliberate, reviewed bump process, because a 0.2.0 could rename or restructure the converter layer again.

Support. Upstream ownership has moved to the official markup-carve organisation, which materially improves our support posture — bugs now have a real destination. Concurrent 1.x/2.x/3.x maintenance means security fixes are likely to reach us regardless of major, which reduces upgrade pressure but also removes the forcing function that keeps us current.

Scaling. Markup conversion is CPU-bound and, in the default integration, happens on the request path. The converters abstraction makes it tempting to stack profiles; each additional profile is additional parse work per render. For high-traffic read paths, cache rendered output keyed on content hash rather than re-converting per request, and push any bulk/backfill conversion to queues.

Failure modes. Ranked by likelihood and blast radius:

• Config cache staleness — highest likelihood. Old profiles key persists post-deploy, converters resolve to nothing. Mitigation: cache-clear in the deploy runbook, not as a manual step.
• Partial namespace rewrite — a missed import throws Class not found at the point of use, often only on a rarely-hit page. Mitigation: static grep gate in CI.
• Duplicate providers — both bridges present, ambiguous bindings. Mitigation: composer why assertion.
• Silent rendering regression — AsCarve source-handling behaviour changed (#8), so previously-passed-through values now render differently. This is the one that won't throw; it needs a visual/content diff on a representative sample, not just a green test suite.
• Bridge minor bump — future 0.x release breaks the converter contract. Mitigation: exact pin.

Ramp-up. Low for application developers — the surface is a cast and three components. Moderate for whoever owns the published config and render profiles, since converters is a new mental model and the only documentation is a README section. Budget a short internal write-up of our profile definitions post-migration so the knowledge isn't trapped in a config file only one person has read.