Statamic Buddy Laravel Package

Getting Started

This release is a major version bump (v2.0.0) whose only stated change is the removal of Statamic 3 support. That single line drives almost everything about how you should approach this package, so start by establishing which side of the line you are on.

1. Check your Statamic version first. Run php artisan about (or composer show statamic/cms) and confirm whether you are on Statamic 3, 4, or 5. This determines whether v2 is even installable for you.
2. If you are on Statamic 3: do not upgrade. Pin the package to the v1 line ("vendor/package": "^1.0") and treat v1 as the supported version for your project until you migrate Statamic itself. Statamic 3 is long past end of life, so this is a signal to plan that migration rather than a blocker to work around.
3. If you are on Statamic 4/5: install or upgrade with composer require vendor/package:^2.0. Because this is a major release, read the package README and CHANGELOG.md before touching anything else — the changelog is the only reliable statement about whether any other behaviour changed alongside the dropped support.
4. Look first at: the package's composer.json (to see its statamic/cms constraint), its service provider (to see what is registered — tags, modifiers, fieldtypes, CP nav, middleware), and its config file after publishing (php artisan vendor:publish --provider="Vendor\Package\ServiceProvider").

First use case: get the package rendering something trivial end-to-end — a single tag or modifier in a Antlers template, or a single fieldtype on a test blueprint — before wiring it into anything real. That confirms registration and autoloading are healthy after the major bump, and isolates any install problem from any usage problem.

Implementation Patterns

Treat v1 and v2 as divergent branches. If you maintain multiple Laravel/Statamic applications across different Statamic majors, use Composer's constraint resolution rather than trying to keep one codebase compatible with both. In practice:

// Statamic 4/5 application
"vendor/package": "^2.0"

// Statamic 3 application (frozen)
"vendor/package": "^1.0"

Composer will then resolve the correct package version per application without any application-level branching. This is far cleaner than feature-detecting at runtime.

Upgrade workflow for a Statamic 4/5 app already on v1:

1. Create a branch; do not upgrade in place on a shared environment.
2. Run composer update vendor/package --with-dependencies and read the full diff of composer.lock — a major bump can pull in transitive updates you did not intend.
3. Clear Statamic's caches: php artisan cache:clear, php artisan config:clear, php artisan statamic:stache:clear, php artisan view:clear.
4. Hit every surface where the package is used — CP screens, front-end templates, any queued jobs or commands that touch it.
5. Only then merge.

Pin the Statamic constraint explicitly in your own composer.json. Because v2's whole reason for existing is a Statamic version floor, your application's statamic/cms constraint should be equally explicit (e.g. ^4.0 or ^5.0). Vague constraints like * or >=3 are what make major-bump upgrades unpredictable.

Test the package boundary, not the package. Your own test suite should cover your integration points — the templates that call its tags, the blueprints that use its fieldtypes, the controllers that hit its APIs. You cannot meaningfully test a third-party package's internals, and after a major release you should not assume them anyway. Statamic addon tests generally need statamic/cms bootstrapped via the package's own testing helpers; if the package ships a test suite, running it locally on your PHP/Statamic combination is a cheap smoke test.

Use it as a version signal for your own addons. If you also maintain Statamic addons, this release is a template for the pattern: drop the EOL major, bump the package major, document the constraint in composer.json. Statamic's addon ecosystem has largely converged on this.

Gotchas and Tips

• The changelog line is thin — verify rather than assume. "Remove Statamic 3 support" tells you what the maintainer considered the headline breaking change, not that it was the only change. Check the GitHub compare view (v1.x...v2.0.0) before upgrading anything load-bearing. A major bump with a one-line note is a documentation gap, not a guarantee of minimal change.
• Statamic 3 users will not get a friendly error, only a resolution failure. If your constraint is loose, composer update may resolve v2 on a Statamic 3 app and then fail at boot with a class-not-found or a service provider exception rather than a clear version message. Pin to ^1.0 proactively.
• composer.lock in CI is your safety net. If any pipeline runs composer update rather than composer install, a v2 release can land in CI silently. Lock file discipline matters more than usual right after a major release.
• Stache and addon discovery caches survive composer operations. After upgrading, the symptom of a stale cache looks exactly like a broken package (missing tags, missing fieldtypes, CP nav entries gone). Always clear Statamic's caches before you start debugging the package itself.
• Watch the published config file. If v2 changed config keys, a previously published config/package.php will silently shadow the new defaults and new keys will never apply. Diff your published config against the package's config/package.php after every major bump.
• Extension points are the risky surface. If you have subclassed the package's service provider, extended its fieldtype, overridden its views (php artisan vendor:publish --tag=views), or registered a custom tag that reuses its classes, those are the places a major bump is most likely to break you — even if the changelog says nothing about them. Grep your codebase for the package namespace and audit each hit.
• Statamic 5 requires PHP 8.2+. If the removal of Statamic 3 support accompanies a raised PHP floor in the package's composer.json, check your runtime versions in CI and in production before merging — this is the most common cause of a "surprise" failure after an addon major bump.
• If the upgrade breaks you and the cause is unclear, the fastest path is a deliberate downgrade. composer require vendor/package:^1.0 on a branch, confirm the app is healthy, then reintroduce v2 in isolation. Don't debug a major bump and a feature change simultaneously.