Statamic Site Essentials Laravel Package

Getting Started

This is a Statamic addon, so the first thing to verify is your Statamic major before touching the addon version. As of v1.4.0, Statamic 4 is no longer supported; the package now requires Statamic ^5.73 or ^6.4.

1. Confirm your baseline:

   composer show statamic/cms
   php artisan about
   

2. If you're still on Statamic 4, upgrade Statamic (and its Laravel floor) first — do not attempt to pull the addon in alongside Statamic 4, because Composer will either refuse the install or you'll end up resolving an older addon release without realising it.
3. Install the addon:

   composer require <vendor>/<package>:^1.4
   

   Pinning ^1.4 explicitly makes the Statamic 4 drop visible in your lockfile rather than silently resolving to a pre-1.4 version.
4. Publish anything the addon ships (config, assets, migrations) if the install docs call for it:

   php artisan vendor:publish --tag=<package>-config
   php please stache:clear
   

5. Where to look first in the codebase: the addon's service provider in vendor/<vendor>/<package>/src/, then config/ and resources/ for tags, fieldtypes, or views it registers. That tells you the actual public surface — tags/modifiers/fieldtypes/CP routes — faster than reading the README end to end.

First use case: get one tag, fieldtype, or CP screen wired into a single entry or template in a local environment, confirm it renders, then roll it out. Statamic addons are usually low-ceremony to try and higher-ceremony to roll back once content is authored against them, so start small.

Implementation Patterns

Lockstep upgrade workflow. Treat the addon version and the Statamic major as a single unit. When bumping one, bump the other in the same PR and run the full test suite. A useful pre-flight check:

composer why-not statamic/cms ^6.4
composer outdated "statamic/*"

Pinning and CI matrix. If you maintain multiple sites on Statamic 5 and 6, run CI against both ^5.73 and ^6.4. The addon explicitly supports both, so regressions are most likely to show up at the boundaries — Statamic's newer APIs, deprecations, and CP asset conventions.

Template usage. Once registered, the addon's Antlers tag/modifier is typically used directly in templates:

{{ <package_tag> }}
    ...
{{ /<package_tag> }}

For Blade-heavy sites, check whether the addon exposes a facade or a Blade component — Statamic addons vary here, and mixing Antlers and Blade approaches in the same project is a common source of "it works in one template and not another" confusion.

Content-model integration. If the addon provides a fieldtype, add it to a blueprint in resources/blueprints/ and test it against a real entry in a non-production environment before changing live blueprints. Fieldtype changes touch the Stache, so pair blueprint edits with:

php please stache:clear
php please stache:warm

Testing. Use Statamic's testing helpers (or the addon's own test suite as a template) and assert against rendered output rather than internal classes where possible. That keeps your tests resilient across the 5.73 → 6.4 range.

Deployment. On every deploy that changes the addon or Statamic version:

composer install --no-dev --optimize-autoloader
php artisan config:clear && php artisan config:cache
php artisan view:clear
php please stache:clear

Addon discovery and the addon manifest cache are the usual suspects when a deploy "works locally" but not in production.

Gotchas and Tips

• The Statamic 4 drop is the headline breaking change. If your composer.json allows Statamic 4 and the addon constraint is loose, a composer update can resolve to a pre-1.4 addon without any error. Pin ^1.4 and verify with composer show after updating.
• Upgrade order matters. Statamic first (to ^5.73 or ^6.4), then the addon. Doing it the other way round leaves you in an unresolvable state that's annoying to unwind.
• Statamic 6 is not just a version bump. Expect changes in CP asset registration, Vue/Inertia conventions, and some deprecated APIs. If the addon publishes CP assets, run php please vendor:publish / rebuild assets as its docs instruct and hard-refresh the CP — stale cached CP assets after an upgrade are a classic false alarm.
• Stache staleness. After upgrading, symptoms like "fieldtype missing", "tag not found", or old blueprint definitions usually mean a stale Stache index. php please stache:clear resolves most of them.
• Addon discovery. If the addon doesn't appear in the CP, check config/statamic/addons.php (or the cached manifest) and that the service provider is auto-discovered or manually registered.
• Extension points. Before forking or patching, check for published config, events, and bindings in the service provider — most behavioural tweaks should be config or event listeners, not vendor edits.
• Debugging tips. Use php please commands for Statamic-side inspection, php artisan tinker for quick checks against the addon's classes, and Laravel's log for tag/fieldtype exceptions. If a tag renders empty, verify the variable scope in the template before assuming the addon is broken.
• Support window. Since v1.4.0 targets Statamic 5.73+ and 6.4+, older Statamic 5 patch releases are effectively unsupported. Keep Statamic itself current within the major you're on.