Statamic Classify Laravel Package

Technical Evaluation

Scope reviewed: visuellverstehen/statamic-classify v4.0.0 (major release). No prior assessment existed, so this establishes the baseline.

Architecture fit

• Composer-distributed Statamic addon; integrates through Statamic's addon/service-provider discovery rather than bespoke application wiring. Low architectural footprint — fits any Laravel app already running Statamic, no new infrastructure, queue, or external service implied by the release notes.
• The addon is one layer removed from Laravel itself: it declares support for Statamic 5/6 and inherits the underlying framework through statamic/cms. That is a deliberate coupling decision worth understanding before adoption.

Integration feasibility

• Hard floor is now PHP 8.3+. Anything on 8.2 (still common in conservative hosting) cannot adopt v4 at all — this is a runtime upgrade prerequisite, not a package upgrade.
• Supported matrix: PHP 8.3/8.4, Laravel 11/12/13, Statamic 5/6. Laravel 10 and Statamic 4 are explicitly dropped, so existing v3.x consumers on those versions are frozen on the 3.x line.
• The release adds Laravel 13 support — a forward-looking compatibility claim that positions the package for teams planning an imminent framework upgrade, and makes v4 the version to adopt if you are upgrading Laravel in the same window.

Technical risk

• Medium overall. No data-model, migration, or configuration-breaking changes are described — the breaking changes are environmental (runtime and dependency floors), which is the cheapest class of major bump to absorb if you are already on the required stack.
• The "removed redundant laravel/framework constraint" item is the subtle one: framework version is now resolved transitively via statamic/cms. That is defensible, but it shifts version pinning responsibility onto the application's composer.json. Teams that relied on the addon to constrain Laravel should verify resolution explicitly.
• CI credibility signal: the changelog states CI was previously not actually exercising matrix.statamic and had broken prefer-lowest jobs. That means compatibility claims in earlier releases were less verified than the matrix suggested. v4's claims are presumably better tested, but it also means historical "supports X" statements from this project should be treated as unvalidated.
• Bus factor: two contributors visible on this release, one dominant. Small-maintainer risk is real for a package in the content-model path. Mitigation is that the surface area is small and the code is MIT-style forkable.
• Test suite migration from PHPUnit to Pest 4 is internal-only and carries no consumer risk, but it does mean contributions, forks, and internal patches must now be written in Pest.

Key questions

1. What is our current PHP, Laravel, and Statamic version set — and is a PHP 8.3 runtime upgrade already on the roadmap?
2. Does v4.0.0 touch blueprints, fieldtypes, stored data, or published config, or is it purely a compatibility bump? (Changelog implies the latter — confirm against the diff.)
3. Do we need a 3.x maintenance window for environments we cannot move to PHP 8.3 in the next two quarters?
4. Can we pin Laravel explicitly in our root composer.json so we do not depend on the transitive constraint?
5. Who owns this package if upstream goes quiet — is forking acceptable to us?

Integration Approach

Stack fit

• Appropriate only for Laravel 11+ / Statamic 5+ / PHP 8.3+ applications. On any older combination, v4 is a non-starter and v3.2.0 remains the target.
• No new runtime dependencies, services, or operational components are introduced by this release — fit is a pure version-window question.

Migration path (v3.2.0 → v4.0.0)

1. Inventory: capture current PHP, Laravel, Statamic, and package versions across every environment, including CI images and local Docker/Herd setups.
2. Upgrade the platform first, in this order: PHP 8.3+ → Laravel 11+ → Statamic 5/6. The package follows; it should not lead.
3. Bump visuellverstehen/statamic-classify to ^4.0 and explicitly pin laravel/framework and statamic/cms in the root manifest to replace the constraint the package no longer provides.
4. Clear compiled/cached config and re-run any Statamic addon discovery steps (php artisan statamic:install equivalents) per project convention.
5. Run the application's own test suite plus a content smoke test — verify fieldtypes render, blueprints load, and existing classified data resolves identically.

Compatibility

• If we maintain multiple apps on mixed Statamic versions, we will need a split constraint (e.g. ^3.2 for Statamic 4 apps, ^4.0 for Statamic 5/6 apps). Support both lines until the older apps retire, and document which is which.

Sequencing

• Treat this as a passenger upgrade: schedule it inside the framework/runtime upgrade epic, not as an independent ticket. Attempting it standalone will fail Composer resolution and generate noise.
• Where the PHP 8.3 move is blocked, defer and record the package on the "frozen on 3.x" list with a review date.

Operational Impact

Maintenance

• A major bump that drops two framework versions and raises the PHP floor is a healthy signal — the project is actively tracking upstream rather than accumulating dead compatibility shims. Expect roughly one major per upstream cycle (Laravel/Statamic majors), so budget for a recurring upgrade task rather than a one-off.
• The removal of the redundant framework constraint reduces the package's own maintenance surface but pushes pinning discipline to consumers. Add a check to our dependency policy that root manifests pin framework versions explicitly.
• No LTS branch is evident; assume v3.x receives at most security-level attention now. Do not plan long-term residency on it.

Support

• Upstream support is community/volunteer with a small contributor base. We should not assume vendor SLAs or timely patches for a future Laravel major.
• Internal ownership: name a single engineer as the go-to for this addon, with a documented fallback (fork the repo under our org, or vendor the source) if upstream stalls.

Scaling

• Negligible operational scaling impact. This is a CMS-side addon; load characteristics follow Statamic's caching and static/SSR strategy, not the addon. No new scaling workstream.

Failure modes

• Composer resolution failure — most likely failure during upgrade, caused by the dropped Laravel 10/Statamic 4 support combined with the removed framework constraint. Symptom is a confusing dependency conflict; mitigation is explicit root-level pins.
• Runtime type/API errors on PHP 8.3 — surfaces at boot or first use of the fieldtype; mitigation is a staging deploy with full content smoke test.
• Silent divergence in classification behaviour — unlikely given the changelog, but confirm the diff is compatibility-only before assuming it.
• Upstream abandonment — low severity, low likelihood; mitigated by small surface area and forking viability. Track as a standing risk, not an active one.
• Trust gap from prior CI — earlier compatibility claims were under-tested; do not extend that scepticism to v4 indefinitely, but do verify our own target versions in staging rather than relying on the matrix.

Ramp-up

• Minimal engineering ramp-up: it is a version bump plus a runtime upgrade already required for other reasons. Estimate low single-digit engineer-days for a single app, dominated by PHP/Laravel upgrade work rather than the package itself.
• Main organisational effort is coordination — environment inventory, CI image updates, and a go/no-go on the PHP 8.3 floor — not learning the package.