Statamic Import Image Metadata Laravel Package

Getting Started

The 1.2.0 release note is a single line — "Support for Statamic 5" — and that one line tells you most of what you need to know: this is a Statamic addon, not a general-purpose Laravel package. Statamic 5 ships on Laravel 11 / PHP 8.2+, so this release is effectively a framework-generation bump as much as an addon bump.

Minimum steps to evaluate it:

1. Read the constraints before the docs. composer show vendor/package --all and check the require block on 1.2.0. That answers the two questions that matter: does it still support Statamic 4, and what's the minimum PHP/Laravel? If the answer is "Statamic 5 only," you cannot install this on a Laravel 10 app, and no amount of code review changes that.
2. Look at the diff, not the changelog. With a one-line release note, git diff <previous-tag>..1.2.0 (or the compare view on the repo) is the actual documentation. Look at composer.json, the service provider, and any config/ or routes/ files first — that's where Statamic 5 compatibility work lives.
3. Check the CHANGELOG/UPGRADE file for the versions between your current pin and 1.2.0. If you're jumping from 1.0.x, the Statamic 5 work may be the last entry in a series of changes you've skipped.
4. First use case: install into a throwaway Statamic 5 site, confirm the addon appears and boots (Control Panel → Addons, plus php artisan about for versions), then exercise the single feature you actually need it for. Don't validate against an upgraded legacy project first — too many variables.

If you're still on Statamic 4, the practical "getting started" answer is: stay on the last pre-1.2.0 release and treat this as an upgrade project, not a dependency bump.

Implementation Patterns

The coupled-upgrade pattern. Statamic addons are version-locked to the Statamic major, so composer.json should carry both pins together:

"statamic/cms": "^5.0",
"vendor/package": "^1.2"

Never let these drift across deploys — bumping the site to Statamic 5 while an addon sits at a Statamic 4 build produces a boot-time failure, not a graceful degradation. Treat the pair as one atomic unit in review.

Upgrade order that actually works:

1. Branch. Update PHP to 8.2+, Laravel to 11, statamic/cms to ^5.0 — using Statamic's own upgrade guide.
2. Run composer why-not vendor/package 1.2.0 to see exactly which constraint is blocking (usually a transitive Statamic 4 requirement or an EOL PHP pin).
3. Add the addon at ^1.2.0, then composer update vendor/package --with-dependencies.
4. Re-publish assets/config (see Gotchas — vendor:publish without --force will silently not overwrite, which is often what you want).
5. Clear every cache, then hit the CP and the front-end routes the addon touches.

Bootstrapping assumptions. Statamic addons assume the Statamic container is present — the Stache, the CP route group, Antlers, and the addon repository that discovers your service provider. Consequences for day-to-day work:

• Don't try to unit-test the addon's Statamic-facing code in a bare Laravel skeleton. Use a Statamic-flavoured test bench (Orchestra Testbench pointed at a Statamic install, or the addon's own test suite if it ships one).
• Do isolate your own business logic away from the Statamic surface where you can — plain Laravel services and actions are far easier to test and survive the next major bump.
• Register everything through the addon's service provider (config merge, views, routes, commands, event listeners). If you're adding to this package's internals, that's the seam to extend at.

Config and environment. Publishable config belongs in config/ with env() lookups at the top level only, and everything reads through config() at runtime so php artisan config:cache doesn't bite you. In production, cache config after every deploy.

Integration tip: wire the addon into your own domain code via events/listeners or a thin adapter class rather than calling addon classes directly from controllers and Blade. Statamic majors have historically moved APIs around; an adapter layer turns the next upgrade into a one-file change.

Gotchas and Tips

• This is very likely a breaking release. "Adds Statamic 5 support" in a minor-numbered release almost always means "drops Statamic 4 support" or raises minimum PHP. Verify with composer show --all before trusting the 1.x version number to imply backwards compatibility. Semver does not protect you across Statamic majors.

• Statamic 5 means Laravel 11. That's the real upgrade: new application skeleton, PHP 8.2+, updated config defaults, and possibly changed middleware/exception handling in your own bootstrap/app.php. Budget for the Laravel 11 work, not just the addon.

• Clear caches aggressively after upgrading. In order: php artisan config:clear, route:clear, view:clear, cache:clear, and — critically — php artisan stache:clear. The Stache is Statamic's content index; stale Stache state after a major upgrade produces confusing "my changes did nothing" symptoms that look like addon bugs.

• vendor:publish won't overwrite. If the published config gained new keys in 1.2.0, your existing file silently lacks them. Diff the package's config/ against your config/ after upgrading rather than assuming publishing did the job.

• Check the addon's composer constraints for statamic/cms, not just php. A common failure mode is an addon that allows Statamic ^4.0|^5.0 but a sibling addon that doesn't — you discover this mid-deploy.

• Debugging checklist: php artisan about (versions), composer why-not vendor/package 1.2.0 (constraint conflicts), the addon's boot errors in storage/logs/laravel.log (Statamic addons fail loudly at boot when the major is wrong), and the CP → Addons screen (registration/version mismatch, rather than runtime errors).

• Extension points to look for when you outgrow the feature set: published config, events dispatched by the addon, any Antlers tags or modifiers it registers, and its service provider bindings. Those are the supported seams; subclassing internal classes is not, and it's what breaks on the next Statamic major.

• Caveat on this assessment: it's built from a one-line changelog. The version coupling, cache, and publish behaviour above are reliable Statamic-and-Laravel generalities; the addon's specific API, config keys, and extension points are not documented here. Read the package README and the 1.2.0 diff before relying on any of the implementation specifics.