Statamic Attribute Renderer Laravel Package

Getting Started

This release is primarily a compatibility release: v1.2.0 adds Statamic 6 support. Before adopting it, confirm whether the new constraint is additive (supports Statamic 5 and 6) or a hard bump to Statamic 6 only.

1. Check the package constraints first. Open the package’s composer.json and verify the statamic/cms constraint after upgrading. If you are still on Statamic 5, do not assume v1.2.0 is a drop-in update unless the constraint is something like ^5.0|^6.0.
2. Install or upgrade through Composer.

   composer require vendor/package:^1.2
   

   For an existing Statamic 5 site, run the upgrade deliberately:

   composer update vendor/package --with-dependencies
   php artisan statamic:clear-cache
   

3. Look first at the package README and composer.json. Statamic addons are typically auto-discovered via the statamic-addon Composer type. If the addon requires manual registration, it will usually be in config/statamic/addons.php or a service provider.
4. Publish config/assets only if the package provides them.

   php artisan vendor:publish --provider="Vendor\\Package\\ServiceProvider"
   

5. First use case: open the Statamic Control Panel and look for the addon’s fieldtype, widget, navigation item, or utility. If it exposes an Antlers tag or modifier, test it in a template:

   {{ if {package:tag} }}
     ...
   {{ /if }}
   

   If it is a fieldtype, add it to a blueprint and verify it renders and saves correctly in both the CP and via the REST API if applicable.

Because the release note only mentions Statamic 6 support, the first practical evaluation is not “what new features exist?” but “does this version run cleanly on my Statamic/Laravel/PHP matrix?”

Implementation Patterns

Pin to the correct major line. If v1.2.0 supports both Statamic 5 and 6, use a constraint that reflects your platform:

"vendor/package": "^1.2"

If it is Statamic 6-only, treat the upgrade as part of a broader Statamic 6 migration rather than an isolated patch.

Use the addon through Statamic’s normal extension points. Depending on what the package exposes, the day-to-day integration will usually be one of:

• Antlers tag or modifier: use directly in templates; keep package output escaped unless you explicitly need raw HTML.
• Fieldtype: register it in a blueprint, then use the field in entry, term, global, or user blueprints. Test CP editing, validation, and API serialization.
• Widget or utility: expose it through the CP dashboard or utilities navigation for editors.
• Service provider / facade: resolve the package from Laravel’s container in custom code rather than instantiating internals directly.

Keep application code behind a thin wrapper. For anything used in more than one template or controller, wrap the addon call in a small service class or custom Statamic tag. This makes future compatibility releases easier to absorb:

final class PackageFeature
{
    public function __construct(private PackageContract $package) {}

    public function render(array $context): string
    {
        return $this->package->handle($context);
    }
}

Test against the Statamic version you actually deploy. If the addon supports both Statamic 5 and 6, add a CI matrix entry for each supported combination of PHP, Laravel, and Statamic. Statamic 6 compatibility often interacts with Laravel and PHP version constraints, not just the CMS package.

Use Statamic’s testing helpers for addon behavior. For tags, modifiers, and fieldtypes, assert rendered output and saved values rather than only testing the underlying package class. This catches template-context and CP-integration regressions that unit tests miss.

Handle upgrades as platform migrations. On a Statamic 6 upgrade:

composer update statamic/cms vendor/package --with-dependencies
php artisan statamic:clear-cache
php artisan view:clear
php artisan config:clear

Then smoke-test the CP, front-end templates, and any queues or scheduled tasks that touch the addon.

Gotchas and Tips

• “Statamic 6 support” is ambiguous. Confirm whether v1.2.0:

  • adds Statamic 6 alongside Statamic 5, or
  • replaces Statamic 5 support entirely.

  This single detail determines whether v1.2.0 is a routine update or a breaking platform upgrade.

• Composer conflict failures are the most likely upgrade symptom. If composer update fails, inspect the full constraint chain for statamic/cms, laravel/framework, and php. Do not force the update with --ignore-platform-reqs on a production site.

• Statamic caches aggressively. After upgrading, clear Statamic’s caches, Laravel’s config cache, and compiled views. Stale addon manifests or cached Antlers templates can make a compatible package appear broken.

• Check addon discovery. If the package does not appear in the CP after upgrade, verify that it is still auto-discovered, that its service provider is registered, and that config/statamic/addons.php does not contain a stale manual entry.

• Re-publish assets if the package ships CP assets. A compatibility release can change compiled JS/CSS. Run the vendor publish command if the package documents it, then hard-refresh the CP.

• Watch for silent blueprint or fieldtype changes. If the addon provides a fieldtype, open an existing entry and verify that stored data still loads. Statamic 6 changes to fieldtype metadata or Vue components can affect CP rendering even when front-end output is unchanged.

• Test API and front-end output separately. A fieldtype can render correctly in the CP while serializing differently through the REST API, or vice versa.

• Prefer the package’s public extension points over internals. Use documented events, hooks, tags, modifiers, and contracts. Directly extending internal classes is the fastest way to break on the next Statamic compatibility release.

• Keep a rollback path. Before upgrading on a production site, tag or branch the working state and confirm you can restore the previous composer.lock. Compatibility releases are usually safe, but Statamic 6 upgrades can pull in broader dependency changes than the release note implies.

• Verify the upgrade in a staging environment with real content. Statamic sites often carry complex blueprints, multisite configurations, and cached Stache data. A clean install test is not sufficient evidence that the addon works against an existing Statamic 6 site.