Statamic Bard Mutator Laravel Package

Getting Started

This release is a compatibility release — the headline change is Statamic 6 support — so treat 3.0.5 as the entry point for Statamic 6 projects and as a deliberate upgrade decision for existing ones.

First steps

1. Check your Statamic version before requiring it.

   composer show statamic/cms | grep versions
   

   If you are still on Statamic 5, do not blindly take ^3.0.5. Pin the last 5-compatible release (composer require vendor/package:3.0.4) and schedule the Statamic 6 upgrade as its own task. Mixing a Statamic 6-only addon release with a Statamic 5 app is the most common way this goes wrong.

2. Install on a Statamic 6 app:

   composer require vendor/package:^3.0.5
   composer why-not statamic/cms 6.*   # sanity check nothing else is blocking
   

3. Where to look first (in this order):

   • composer.json of the release — confirm the statamic/cms and laravel/framework constraints it now expects.
   • The package's ServiceProvider — what it registers (tags, modifiers, fieldtypes, nav items, permissions, middleware). That list is your feature surface.
   • config/ inside the package — anything publishable.
   • CHANGELOG / upgrade notes for 3.0.x as a whole, not just 3.0.5.

4. First use case: publish the config, drop the package's fieldtype into one blueprint (or its tag into one Antlers template), and verify in the Control Panel before rolling it across content types.

php artisan vendor:publish --tag=package-config
php artisan config:clear && php artisan stache:clear

Implementation Patterns

Config-first, not code-first. Publish and commit the config file, then drive behaviour from it. This is what makes the addon survivable across future Statamic majors — you edit config, not vendor code.

Blueprint-scoped fieldtypes. Add the fieldtype to a single blueprint first, save an entry, and confirm the value round-trips through the Stache before adding it to shared/global sets. Fieldtypes that misbehave in Statamic 6 usually fail on augmentation, not on save.

Keep Antlers and Blade separate. If you use the package's tags, wrap them in a small Antlers partial (or a Blade component) rather than scattering them through templates:

{{ partial:components/thing :entry="id" }}

That indirection is your migration seam when the addon's API shifts.

Cache layering. In production, run with the Stache warm and the config cached. After any 3.0.5 deploy:

php artisan config:cache
php artisan stache:warm
php artisan view:clear

Test against both majors in CI. A matrix of statamic/cms: ^5.0 and ^6.0 on the addon's edge will catch the constraints drift early. In app code, use Statamic's testing helpers (Statamic::fake(), Entry::make()) so your tests don't depend on a live CP.

Integration tips

• Register package permissions/nav items only if you actually want them in the CP; otherwise disable via config to keep the editor clean.
• If the addon exposes events, listen rather than subclass — subclassing internals is what breaks on major bumps.
• Use php artisan about and composer outdated --direct as your pre-upgrade snapshot.

Gotchas and Tips

The 3.0.5 trap. A patch-version bump that adds a new major-platform support is not a patch for you. Semver-wise it's additive, but in practice Statamic 6 pulls a newer Laravel and PHP floor. Read the release's composer.json constraints before running composer update, and always test in a branch with a lockfile diff you have reviewed.

Constraint conflicts. composer why-not statamic/cms 6.* is the fastest diagnostic. Common blockers are other addons still pinned to Statamic 5 — you'll end up upgrading in dependency order, not alphabetically.

Clear everything, in order. Half of "the addon is broken after upgrade" reports are stale caches:

php artisan cache:clear
php artisan config:clear
php artisan view:clear
php artisan stache:clear
php artisan stache:warm

Also clear the browser's CP assets if the addon ships JS/CSS (Vite manifest mismatch after a version bump is a classic).

Antlers/Blade runtime differences. Statamic 6 may ship updated Antlers behaviour. If a tag renders empty after upgrade, test the same call in a Blade view and in php artisan tinker — that isolates template-runtime issues from addon issues.

Never edit vendor/. If you need a behaviour change, publish the config, or use the package's documented extension points (custom tag, modifier, fieldtype subclass registered in your provider). Vendor patches vanish on the next composer update.

Deployment discipline. Commit composer.lock. Run composer install --no-dev --optimize-autoloader in the pipeline, not update. Cache config after the deploy's env vars are in place, otherwise you'll ship a config cache built against the wrong environment.

Debugging checklist when something regresses on 3.0.5:

1. composer show vendor/package statamic/cms — actual installed versions.
2. Toggle the addon's config off/on to confirm it's the culprit.
3. Check storage/logs/laravel.log for registration-order errors during boot.
4. Reproduce on a fresh Statamic 6 skeleton install — that separates your app's upgrade debt from the addon's.

Extension points to prefer: events over overrides, config over constants, your own service provider over vendor/ edits, and a thin template partial over inline tag usage.