Filament Carve Laravel Package

Getting Started

• Upgrade the dependency first: remove the abandoned jeffersongoncalves/laravel-carve and require the official bridge markup-carve/laravel-carve:^0.1.7. In 3.x this is the supported path; the old package is no longer the integration point.
• Rename every import from JeffersonGoncalves\Carve\... to MarkupCarve\LaravelCarve\.... This is the most common upgrade breakage and usually surfaces as a "class not found" error.
• Republish the config if you have ever published config/carve.php. Render profiles have moved from the profiles key to converters. Do not assume an old published config is still valid.
• Read the README section "Upgrading from jeffersongoncalves/laravel-carve" before touching application code, then inspect config/carve.php and confirm your converter definitions live under converters.
• First use case: attach AsCarve to a model attribute or pass a model value into CarveEditor/CarveEntry/CarveColumn, and verify the value is treated as Carve source rather than a literal string. This is the behaviour fixed in 3.1.0.
• Clear cached config after publishing or renaming keys: php artisan config:clear.

Implementation Patterns

• Model-driven content: use the AsCarve attribute on a source field so the value is interpreted as Carve input. The 3.1.0 fix means model values now flow through the editor and display components as source, so existing casts/attributes should behave consistently across CarveEditor, CarveEntry, and CarveColumn.
• Editor/entry/column split: use CarveEditor where users author Carve source, CarveEntry for read-only rendered output, and CarveColumn inside table/list views. Keeping the same underlying attribute for all three avoids format drift between authoring and display.
• Converter profiles: define named entries under converters in config/carve.php and select the appropriate converter per context (for example, HTML output for web views and another format for exports). Treat converter names as part of your application contract and reference them consistently.
• Upgrade workflow: search the codebase for JeffersonGoncalves\Carve, replace imports, then search for profiles usages in config and application code and map them to converters. Run a targeted test render before deploying.
• Integration tip: keep Carve rendering close to the model/component layer rather than scattering conversion calls through controllers. This makes it easier to swap converters and to test rendered output independently of HTTP flow.
• If you maintain packages or multiple Laravel versions, note that the AsCarve source-handling fix was backported to 1.x and 2.x, so the rendering fix is available without the dependency and namespace migration. Plan the 3.x upgrade separately from the bug fix.

Gotchas and Tips

• The namespace rename is the primary breaking change. Any direct use of the old vendor namespace, including in custom extensions or cached compiled views, will fail after upgrade. Search broadly, not just app/.
• An old published config/carve.php can leave converters undefined while your code still refers to profiles. This may not throw immediately; it can silently produce default or empty converter behaviour. Republish, or manually rename the key and merge your custom profiles.
• Always run php artisan config:clear after updating the config. Cached config is the most likely reason a correct converters block appears to be ignored.
• The AsCarve fix changes output semantics for model values. If you previously worked around the old behaviour by pre-converting values or treating them as plain strings, remove those workarounds and add a snapshot/feature test around the rendered output.
• Check composer why jeffersongoncalves/laravel-carve after upgrading. A transitive dependency or a stale lockfile can keep the abandoned package installed alongside the new bridge.
• The dependency switch lands in 3.1.0, while the AsCarve fix is backported. If you are pinned to 1.x or 2.x, you get the rendering fix but not the official bridge migration; do not assume the upgrade notes apply identically to those branches.
• Extension point: custom converters should be registered under converters and referenced by name. Keep custom converter configuration in your own config file or a documented merge step so a future republish does not overwrite it.
• Debugging tip: inspect the resolved converter configuration with config('carve.converters') in tinker and confirm the expected converter name exists before debugging component rendering.