Statamic Flexible Width Laravel Package

Getting Started

• Requirements first. 2.0.0 targets Statamic 6, which in turn pins a newer Laravel/PHP floor than the 1.x line. Check composer.json constraints before touching anything: if you are still on Statamic 5, stay on ^1.0 — there is no dual-support branch in 2.x, so the addon and the CMS must be upgraded as a pair.
• Upgrade order matters. Bump statamic/cms to ^6.0 first, resolve the app, then require the addon at ^2.0. Doing it in one composer require tends to leave you debugging constraint conflicts rather than the addon itself.
• Install/refresh the addon. composer require vendor/package:^2.0, then php artisan vendor:publish --tag=<addon>-config (or --provider="Vendor\Addon\ServiceProvider" if the addon doesn't tag its publishes) and php artisan migrate if it ships tables.
• Confirm discovery. Statamic auto-discovers addons via the extra.statamic block in the package's composer.json. If the addon's settings screen or fieldtype doesn't appear in the CP, run php artisan vendor:publish --tag=statamic / php artisan statamic:stache:clear and composer dump-autoload -o before assuming the install failed.
• Where to look first. Read the addon's config/<addon>.php (it documents every knob you'll actually touch), then its src/ServiceProvider.php — the register()/boot() methods tell you exactly what it registers: fieldtypes, tags, modifiers, widgets, nav items, listeners, or routes. That file is your map of the feature surface.
• First use case. The fastest proof of life is a single Antlers template: drop in the addon's tag or modifier, render it against one entry, and verify output in the CP's live preview. That validates discovery, config, and the Stache index in one pass before you wire it into a real blueprint.

Implementation Patterns

• Config, not code. Treat the published config as the primary API. Environment-specific values belong in .env (the addon's config file typically reads them via env()), so per-environment behaviour doesn't require a deploy-time code change. Re-publish after upgrades to diff the config for new keys.
• Blueprint-driven configuration. Where the addon exposes a fieldtype, configure behaviour on the field itself (in the blueprint) rather than globally. That keeps behaviour portable across environments, since blueprints are content, and it survives config caching.
• Tag/modifier usage in Antlers. Prefer the addon's Antlers tag over reaching into PHP from a Blade partial — it respects the addon's caching and augmentation pipeline. If you must call it from Blade, use the documented facade/helper rather than instantiating the addon's classes directly.
• Multi-site and localization. Test at least one entry in a second site. Statamic 6 tightened several multi-site and origin/propagation behaviours, and addons that store per-entry data need to be verified for propagation rather than assumed correct.
• Static/caching integration. If you run the static cache or a response cache, confirm the addon busts correctly on save. Where it doesn't, hook Entry::saved / the addon's documented events and clear the relevant keys manually — this is the single most common production surprise.
• Testing. Use Statamic's testing helpers (Statamic::fake(), Entry::make()) so your feature tests exercise the addon's real augmentation path instead of mocking it. Add a smoke test that boots the addon and asserts its fieldtype/tag is registered — that catches broken discovery on future major bumps immediately.
• Extension points over forks. Modifiers, custom fieldtypes, and event listeners are the intended seams. If a behaviour needs to differ from the default, listen to the addon's events or subclass its published classes; patching vendor code guarantees pain at the next 2.x minor.

Gotchas and Tips

• 2.0.0 is a breaking boundary, not a feature release. The only change is Statamic 6 support, which almost certainly means dropped Laravel/PHP versions and possible API changes absorbed from the CMS upgrade. Grep your codebase for direct references to addon classes and any Statamic APIs that changed in 6 before deploying.
• Don't mix versions. composer require without a constraint can resolve the addon to 1.x on a Statamic 6 app (or vice versa) in transitive-dependency-heavy installs. Pin ^2.0 explicitly and commit the lock file.
• Clear caches in the right order. php artisan config:clear → php artisan cache:clear → php artisan statamic:stache:clear → php artisan view:clear. A stale Stache index after an upgrade looks exactly like a broken addon and wastes the most debugging time.
• Config caching hides new keys. After upgrading, php artisan config:cache will not pick up keys added in 2.0.0 unless the published config file was refreshed. Diff your published config against the package's before caching.
• Check the changelog for the 1.x → 2.0 diff, not just the headline. "Statamic 6 support" releases routinely include silent renames of config keys, event names, or view namespaces. The release note is a summary; the upgrade guide is the contract.
• Debug discovery with php artisan about (or statamic:addons) rather than dumping the container — it shows which addons Statamic actually loaded and is faster to read than a stack trace.
• Watch the CP asset pipeline. Addon-provided JS/CSS is a common casualty of major Statamic upgrades (Vite version changes). If the CP fieldtype renders blank but the API works, it's assets, not logic — hard-refresh and check the browser console first.
• Report issues with versions specified. If you hit something odd, include Statamic version, addon version, Laravel version, and whether static caching is enabled; addon maintainers triaging a 6-support release need all four.