Statamic Cloudflare Laravel Package

Getting Started

This release (2.1.0) is a compatibility release: the package is a Statamic add-on, and 2.1.0 is the first version declaring Statamic 5 support. Nothing in the changelog suggests new end-user features, so treat this as an upgrade/unblock release rather than something to build new work on top of.

Minimal path to first use:

1. Check your host app's baseline first. Statamic 5 requires PHP 8.2+ and Laravel 10/11. If your project is still on PHP 8.1 or Laravel 9, you cannot consume 2.1.0 yet — the constraint will fail at composer update, not at runtime.
2. Read composer.json before anything else. Confirm the statamic/cms constraint on 2.1.0 (^4.0|^5.0 vs ^5.0 only). That single line tells you whether 2.1.0 is a dual-support release you can adopt pre-upgrade or a Statamic-5-only release that forces the platform bump in lockstep.
3. Install and boot:

   composer require <vendor>/<package>:^2.1
   php artisan vendor:publish --tag=<package>-config   # if a config tag is documented
   php artisan statamic:stache:clear
   

4. Where to look first: the package's config/ file (defaults you'll actually override), its service provider (what it registers — fieldtypes, tags, modifiers, nav, permissions), and the README's version/compatibility table. For a Statamic add-on, the provider is the fastest map of surface area.

First use case: install into a scratch Statamic 5 site, open the CP, and exercise whatever the add-on registers (a fieldtype in a blueprint, a tag in an Antlers template, or a nav item). Ten minutes here beats discovering a boot failure in staging.

Implementation Patterns

Pin the constraint, don't float it. Use "^2.1" rather than "*" or a dev branch, and commit the lock file. With a minor version that changes framework support, floating constraints are how you get an unexpected Statamic major pulled into a deploy.

Upgrade sequencing when moving 4 → 5. Do it in this order, one commit each:

1. Bump the host app to Statamic 5 / PHP 8.2 / Laravel 10+ and get the site green without this package's new version (or with it temporarily removed from the manifest if it blocks resolution).
2. Add <vendor>/<package>:^2.1 and resolve.
3. Republish config and diff against your existing overrides — minor releases can add keys, and a missing key plus a cached config is a silent misconfiguration.
4. Re-run your content test pass: Statamic 5 changed enough under the hood (stache, Antlers runtime, Laravel 11 internals) that fieldtype output and tag parsing are where regressions surface.

Keep a compatibility matrix in your own repo. If you maintain multiple sites on different Statamic majors, record "site X → Statamic 4.x → package 2.0.x" and "site Y → Statamic 5.x → package 2.1.x" somewhere durable. With dual-support releases people assume every 2.x works everywhere; that assumption is worth writing down explicitly.

CI matrix, if you're the one integrating. Test the package against both statamic/cms:^4.0 and ^5.0 if 2.1.0 claims both. This is the cheapest way to catch a framework-version regression before a client site does.

Treat 2.1.0 as behaviour-preserving. A minor bump that only adds support generally means no API changes on the Statamic 4 path. If you're staying on Statamic 4, upgrading 2.0.x → 2.1.x should be a low-risk patch-level change — worth doing to stay on a supported line, not worth a release ceremony.

Gotchas and Tips

• The changelog is a single line. There is no detail here on how Statamic 5 support was achieved — whether it's a tested port or a widened constraint. Widen your composer.json requirement only after exercising the add-on's actual features on Statamic 5; a passing composer update proves resolution, not compatibility.
• Watch for the "constraint widened, code unchanged" pattern. Add-ons sometimes bump framework support without changes because nothing needed changing — great, but it means nobody has necessarily run the add-on against Statamic 5's edge cases. Your integration test is the test.
• Don't skip stache:clear and config:clear after upgrading. Stale stache indexes and cached config are the two most common causes of "the add-on stopped working after upgrade" reports, and both are self-inflicted.
• Republish, then diff. If vendor:publish overwrites a config file you'd customised, you lose settings silently. Copy the config out, upgrade, diff, merge.
• Extension points to note while you're in there: Statamic add-ons usually expose config-driven behaviour plus events/hooks. If 2.1.0's only change is the framework constraint, your extension surface is unchanged from 2.0.x — no new hooks to learn.
• Reporting issues: always state the exact package version, Statamic version, PHP version, and Laravel version. On a compatibility release, "it's broken" without that tuple is unactionable for the maintainer.
• Deprecation watch: Statamic 5 dropped a number of Statamic 4 APIs. If the add-on's docs still reference v4-era helpers, prefer whatever the 2.1.0 source actually calls over what the README says — the README may lag the release.