Statamic Widget Newest Users Laravel Package

Getting Started

This release (v1.2.0) is a compatibility release adding Statamic v5 support. That single line carries a meaningful amount of information: the package now supports PHP 8.2+, Laravel 10/11, and the Vite-based control panel toolchain that shipped with Statamic 5. There are no new features or deprecations called out, so the day-to-day API is presumably unchanged from 1.1.x — treat this as a green light to upgrade, not a reason to re-learn the package.

Minimum steps:

composer require <vendor>/<package>:^1.2
php artisan vendor:publish --tag=<package>-config   # if the package ships config
php artisan statamic:stache:clear

Look first at:

1. composer.json of the package — confirm the constraints are statamic/cms: ^5.0 and php: ^8.2, and check the extra.statamic block (that's how Statamic auto-discovers the addon's service provider).
2. src/ServiceProvider.php — registration, config merge, publish paths, and any Statamic::booted() hooks.
3. The config file, if one is published — this is usually the whole surface area of an addon like this.

First use case: register the addon, hit a single front-end route that exercises it in Antlers, and confirm output. If the package exposes a tag, {{ <tag> }} in a template; if it's a fieldtype, add the field to a collection and save an entry. That one round-trip verifies both the PHP side and the CP asset side, which are the two things an addon major-version bump typically breaks.

Implementation Patterns

Version-gate the upgrade, don't shotgun it. Because the release note is purely "Statamic v5 Support", the correct pattern is: upgrade Statamic first on a branch, then bump this package, then run the test suite and a manual CP smoke test. Doing both in one commit makes bisecting failures impossible.

Pin the major explicitly. Use ^1.2 in composer.json rather than * or a caret on the whole package. Addons that add a new Statamic major tend to publish a companion release for the old line (e.g. 1.1.x staying on Statamic 4); an explicit ^1.2 documents which line you're on and prevents a future 1.3 from silently changing constraints.

Config over code. If the package publishes a config, resolve behaviour there rather than subclassing or decorating internals. Addon internals are the least stable surface across a Statamic major; config keys are the vendor's contract with you.

Wrap it behind an application-level seam. For anything called from more than one place (a tag, a controller, a Nova/CP action), put a thin service class or Blade component in front of the package. When the next Statamic major lands, you change one file instead of grepping templates.

Multi-site and localization. Statamic 5 projects are frequently multi-site. If the addon reads or writes content, test the same operation on a second site — origin/derived entry behaviour is where addons most often leak assumptions, and a compatibility release is a good excuse to check it.

Test with Statamic's own harness. Use Statamic\Testing\AddonTestCase (or the package's own base test case) plus RefreshDatabase-style fixtures so your tests boot the real Statamic app. A pure unit test will happily pass while the addon fails to register in a real install.

Gotchas and Tips

• v1.1.x is your escape hatch. If you can't move to Statamic 5 yet (PHP 8.1 host, Laravel 9 dependency, a fieldtype addon that hasn't shipped a Vue 3 build), stay on the previous line and pin it deliberately. This release is additive compatibility, so nothing forces the jump.
• PHP 8.2 and Laravel 10/11 come along for the ride. Statamic 5's floor is PHP 8.2. Check your CI matrix, your platform.php config in composer.json, and any Docker images before assuming "just a composer bump".
• Control panel assets are the usual casualty. Statamic 5 moved the CP build to Vite/Vue 3. If this addon ships a fieldtype or CP nav item, the published assets must be rebuilt — run the package's build step after upgrading and hard-refresh the CP. A stale public/vendor/<package> directory produces blank fieldtypes with no PHP error.
• Clear the stache after upgrading. php artisan statamic:stache:clear (and php artisan cache:clear) resolves a surprising share of "the addon isn't doing anything" reports. Addon registration and config are cached aggressively.
• Check addon discovery, not just composer require. If the service provider doesn't appear in php artisan about / the addon list, the extra.statamic block or the package's composer.json constraints are the place to look — a statamic/cms constraint mismatch can cause Composer to resolve an older release than you asked for.
• Read the diff, not just the release note. One line of notes for a version bump either means "constraints and a couple of API renames" or "we touched everything and didn't write it up." composer diff / the GitHub compare view between 1.1.x and 1.2.0 tells you which, in about thirty seconds.
• Extension points are the risk surface. If you've published the package's views, overridden its config at runtime, or extended its classes, re-verify those after the bump — those are precisely the places a Statamic major breaks, and precisely the places a terse release note won't mention.
• No news is a signal too. With no new features or deprecations listed, don't go looking for behavioural changes. Upgrade, run your existing tests, smoke-test the CP, and move on.