Statamic Aggregate Assets Laravel Package

Getting Started

Install and verify the constraint first. The 0.0.3 release only changes the Composer constraint on statamic/cms — it now requires Statamic >=3.0 with no upper bound (previously capped). Before writing any code, confirm what actually resolved:

composer require <vendor>/<package>:^0.0.3
composer show statamic/cms <vendor>/<package>
composer why-not statamic/cms 4.x   # sanity-check if you're on Statamic 4/5

Because the addon advertises no ceiling, Composer may happily install it alongside a Statamic major it has never been tested against. On an existing Statamic 4/5 site, treat the install as unverified until you've exercised the feature in the Control Panel — not just run composer update.

Where to look first, in order:

1. vendor/<vendor>/<package>/src/ServiceProvider.php — reveals whether it registers a fieldtype, an Antlers tag, a modifier, a CP nav item, or just a config merge. This single file tells you 80% of what the package can do.
2. vendor/<vendor>/<package>/config/ — publishable config is usually here; the keys are the real API surface.
3. vendor/<vendor>/<package>/src/Fieldtypes/, Tags/, Modifiers/ — the actual runtime entry points.
4. README.md — for a 0.0.x package this is often the only documentation, and frequently lags the code.

Clear the right caches before debugging anything. Statamic caches aggressively and a stale stache will make a correctly-installed addon look broken:

php artisan config:clear
php artisan cache:clear
php artisan statamic:stache:clear   # or: php please stache:clear

First use case. Publish config, register the addon's fieldtype (or tag/modifier) on a single, non-critical blueprint or template, and verify it in the CP and on the front end before rolling it across content types. For a 0.0.x addon, proving the happy path on one entry is the whole point of the first session.

Implementation Patterns

Blueprint-first, code-second. Statamic addons of this vintage are usually fieldtypes. The day-to-day workflow is:

1. php artisan vendor:publish --tag=<package>-config (check the provider for the real tag).
2. Add the fieldtype handle to a blueprint via the CP (Fields → Blueprints) rather than editing YAML by hand — the CP validates the handle and merges correctly with existing sets/imports.
3. Render in Antlers with the field's handle, then fall back to {{ if … }} guards for entries created before the field existed.

Keep config out of source control where it varies. Addon config files typically merge defaults via mergeConfigFrom(), so only publish when you need to override. Prefer driving values from .env through the published config rather than editing vendor defaults:

// config/<package>.php
'api_key' => env('PACKAGE_API_KEY'),
'cache_ttl' => env('PACKAGE_CACHE_TTL', 3600),

Wrap third-party calls in your own layer. A 0.0.x package has no stability contract. Put a thin service class or Antlers partial between your templates and the addon so a future breaking change is a one-file edit:

// app/Support/<Feature>.php
public function render(Entry $entry): string
{
    return (string) $entry->get('your_field_handle');
}

Cache at the boundary, not per-render. If the addon performs remote calls, cache the result keyed on entry ID + updated_at, and bust it in an Entry::saved / Entry::deleted listener. Statamic's stache already caches content, so per-request memoisation on top is usually redundant.

Multi-site. Resolve values through the localized entry ($entry->in($site)), not the default-locale entry, and verify the fieldtype respects localizable: true in the blueprint. Fieldtypes that ship without localizable support will silently share one value across sites — catch this during the first-site rollout, not after content entry.

Testing. In Pest/PHPUnit, boot Statamic's test harness and assert against the rendered output rather than the addon's internals:

$this->get('/your-page')->assertSee('expected output');

Deployment. In your deploy script: composer install --no-dev --optimize-autoloader, then php artisan statamic:stache:warm, then php artisan config:cache. Order matters — warming the stache before config is cached has produced surprising results in the past.

Gotchas and Tips

The 0.0.3 constraint change is the headline risk. Widening statamic/cms to "3.0 and up" removes the guardrail that was implicitly protecting you. On Statamic 3.x nothing changes. On 4.x/5.x, the addon now installs but carries no compatibility signal — and Statamic 4 removed/deprecated several fieldtype and Antlers APIs that 3.x addons commonly rely on (Fieldtype method signatures, $this->field->get() behaviour, modifier registration). Pin deliberately:

"<vendor>/<package>": "0.0.3",
"statamic/cms": "^3.4"

Treat 0.0.x as pre-release semver. ^0.0.3 in Composer only allows 0.0.3 — patches at 0.0.4 are not included. If you want automatic patch updates, use ~0.0.3. Either way, lock the version in composer.json rather than relying on composer update to behave.

Config caching hides env() calls. If the addon reads env() directly (rather than through a config file) and you run config:cache, those values become null in production. Grep the vendor source for env( — a common smell in young packages.

Publish tags are guesses until you check. The tag name in the README is often wrong or absent. Read the provider's boot() for publishes([...], '<actual-tag>') and use php artisan vendor:publish interactively to list available tags.

Stache staleness is the #1 false bug report. After editing a blueprint or publishing config, changes may not appear until php please stache:clear. If a field disappears from the CP, clear the stache before assuming the addon broke.

Debugging the CP-side behaviour. APP_DEBUG=true plus the browser network tab beats guesswork; Statamic returns JSON errors to the CP that never surface in laravel.log. For front-end tags, {{ dump }} / {{ dd }} inside the template scope shows exactly what the addon handed Antlers.

Extension points are the provider and config only. With no documented events or contracts at this version, don't build deep subclasses against internal classes — they are not part of any stability promise. Extend via your own wrapper (see Implementation Patterns) and via the addon's config, which is the closest thing to a supported contract.

Upgrade checklist when 0.1.x lands. Re-read the diff of composer.json (constraint churn has already happened once), re-run the CP smoke test on one entry per blueprint, and clear stache + config cache. Given the 0.0.3 precedent, assume constraint changes will ship as patch releases without migration notes.