Statamic 404 Logger Laravel Package

Getting Started

This release is a compatibility bump, not a feature drop: the package now declares support for Statamic 5. Before you touch any application code, confirm the runtime floor that Statamic 5 imposes — PHP 8.2+, Laravel 11+, and a Statamic ^5.0 constraint in composer.json. If you are still on Statamic 4, stay on the 1.0.x line.

Minimal upgrade path:

1. composer require <vendor>/<package>:^1.1 statamic/cms:^5.0 --with-all-dependencies
2. Run php artisan vendor:publish --provider="<Vendor>\<Package>\ServiceProvider" --tag=config if you previously had a published config, and diff it against the new stub.
3. Clear the cached addon manifest and the Stache: rm -f bootstrap/cache/statamic-addons.php then php artisan stache:clear.
4. Boot the CP and confirm the addon appears under Addons, then open a control panel page that uses its fieldtype/tag.

Where to look first: the package's composer.json (to read the actual statamic/cms and illuminate/* constraints), then src/ServiceProvider.php for what it registers (tags, modifiers, fieldtypes, routes, middleware), then tests/ for the supported-version matrix. The published README is usually only accurate for the headline feature.

First real use case: open an existing blueprint that uses the addon's fieldtype in the CP, edit and save an entry, and confirm the Stache writes cleanly. That single loop exercises augmentation, validation, and caching — the three places Statamic 5 upgrades most often break.

Implementation Patterns

Pin the matrix, don't pin the package. If you maintain multiple sites, keep the addon at ^1.1 and constrain Statamic per-application. For addons you own that need to straddle 4 and 5, use "statamic/cms": "^4.0|^5.0" and branch conditionally on Statamic::version() rather than forking.

Blueprint-driven usage. Reference the fieldtype by handle in YAML (type: your_fieldtype), keep config in the blueprint rather than the published config file where possible, so per-environment config drift doesn't bite you. Fieldtype config changes in the CP are Stache-tracked — commit them to resources/blueprints, not to the database.

Antlers usage. When wiring the addon's tags into templates, prefer the pair syntax for anything returning arrays, and isolate custom tag output in a partial. Statamic 5's Antlers runtime changed how tag return values are coerced; wrapping output in a partial makes regressions obvious and localised.

Testing. For the addon itself, extend Statamic's AddonTestCase and run against both ^4.0 and ^5.0 in CI (a matrix job in GitHub Actions). For applications consuming it, add one feature test per integration point: a tag rendering test and an entry save/augment test. Those two catch the majority of version-bump breakage.

Deployment. Statamic addons register at boot and their manifest is cached. In your deploy script, clear the addon manifest cache before stache:warm, otherwise a warm cache can be built from a stale manifest and the addon silently disappears from the CP.

Gotchas and Tips

• Statamic 5 is not a drop-in for PHP 8.1 or Laravel 10. If other addons in the project haven't shipped 5.x support, Composer will resolve backwards and you'll end up on this package's 1.0.x without realising it. Inspect composer show statamic/cms after install.
• The upgrade isn't reversible in place. Snapshot the database and content/ before upgrading; Statamic migrations and Stache format changes are awkward to roll back.
• Stale addon manifest is the #1 "the addon broke" false alarm. If the package vanishes from the CP after upgrading, delete bootstrap/cache/statamic-addons.php and reload before debugging anything else.
• Published config files shadow new defaults. A config file published on 1.0.x will not receive new keys added in 1.1.x. Re-publish and diff.
• Antlers deprecations surface as notices, not errors. Turn on APP_DEBUG in staging and scan storage/logs for Antlers deprecation warnings, because they frequently point at tag usage the new runtime handles differently.
• Extension points worth knowing: the addon's service provider is the place to swap implementations (bind your own class over the addon's contract), and most Statamic addons expose events on entry save/augment. Hook those rather than overriding the fieldtype class — it survives minor bumps far better.
• Cache tags and static caching. If you use Statamic's static caching, invalidate on the addon's events; otherwise a version bump that changes output format will serve old HTML from the static cache and you'll misdiagnose it as a code bug.