Antlers Layouts Laravel Package

Getting Started

• Install with composer require <vendor>/<package>:^2.1 and confirm Composer resolves statamic/cms to ^6.0. The v2.1.1 release is specifically a Statamic 6 compatibility patch, so it is the minimum version to target on a Statamic 6 site.
• Check the package's composer.json first: Statamic 6 requires PHP 8.2+ and a Laravel 11/12 stack. If the addon's constraints still allow Statamic 5, you can run the same code on both, but test the CP and frontend on 6 before rolling it out.
• Look for the service provider and any publishable config/tags. Statamic addons are typically auto-discovered; run php artisan vendor:publish --tag=<package>-config if the package ships configuration, then commit the published config.
• First use case: boot the site, open the Control Panel, and confirm the addon's nav item, fieldtype, or widget appears. Then exercise the smallest real feature (a single fieldtype in a blueprint, a single tag in an Antlers template, or a single action in the CP) to verify the Statamic 6 runtime path before wiring it into production content.

Implementation Patterns

• Config-first setup. Keep published config in version control and drive behaviour from it rather than hard-coding values in templates or app code. This makes Statamic 5 → 6 upgrades and multi-site setups easier to diff.
• Blueprint and fieldtype integration. If the package provides fieldtypes or sets, add them to blueprints through the CP or via YAML in resources/blueprints/. Prefer committing blueprint YAML so field configuration is reviewable alongside code.
• Template usage. Use the package's Antlers tags/modifiers in templates, but wrap non-trivial logic in a small view model or custom tag if you find yourself repeating conditionals. Statamic 6's Antlers runtime is the main thing this release targets, so smoke-test any custom tag pairs on 6.
• Programmatic usage. Resolve the package's services through the container (constructor injection or app(...)) rather than static calls, especially in jobs, commands, and middleware. This keeps you compatible with Statamic's addon lifecycle and easier to test.
• Testing. Use Statamic's testing helpers (Statamic::fake(), site/collection fixtures) plus Laravel's RefreshDatabase where the addon persists data. Run a CI matrix against the Statamic versions you support; for this release, include Statamic 6 explicitly.
• Upgrade workflow. For existing Statamic 5 sites, bump the addon and statamic/cms together in a branch, run the test suite, then click through the CP and a representative frontend page. Because v2.1.1 is a patch release, treat it as a compatibility bump rather than a feature change.

Gotchas and Tips

• This is a compatibility release, not a feature release. The only documented change is Statamic 6 support. Don't expect new APIs or behaviour changes; the day-to-day impact is that the addon now runs on Statamic 6.
• Watch the Composer constraint. If your root composer.json pins statamic/cms to ^5.0, the addon upgrade may resolve but the site won't move to 6. Align the root CMS constraint, PHP version, and Laravel version before debugging the addon itself.
• Clear caches after upgrading. Statamic caches addon manifests, stache, and views. Run php artisan config:clear, php artisan view:clear, and the appropriate Stache clear command, then reload the CP. Stale addon manifests are a common cause of "the addon disappeared" after a version bump.
• Check auto-discovery and provider registration. If the addon isn't loading on Statamic 6, confirm it's in config/statamic/... or that package discovery is enabled, and that the service provider still registers tags/fieldtypes under the 6.x lifecycle.
• Re-test CP permissions and nav. Statamic 6 tightened several CP conventions. If the addon adds nav items, permissions, or actions, verify they render for non-super users, not just the super admin.
• Multi-site and localization. Compatibility patches sometimes miss multi-site edge cases. Test at least one additional site/locale if you use them, particularly for fieldtypes that store structured data.
• Debugging tip. If something fails only on Statamic 6, compare the addon's service provider boot order and any deprecated Statamic 5 APIs it calls. Check the Statamic 6 upgrade guide for renamed or removed methods, and prefer the addon's tagged release over dev-main when reporting issues.
• Extension points. If you need to customise behaviour, prefer the package's published config and events over subclassing internals; that keeps you insulated from future Statamic 6 patch releases.