Taxonomy Terms Order Laravel Package

Technical Evaluation

Architecture fit. This is a narrowly scoped Composer package that extends the Statamic Control Panel — it adds behaviour around taxonomy term management and persists an order value on terms. Architecturally it is an addon, not a framework: it registers into an existing Laravel/Statamic application, adds no services, queues, or external dependencies, and carries no runtime footprint beyond its own service provider. For a TPM this is the lowest-risk category of dependency: additive, contained, and removable with a composer remove.

Integration feasibility. Installation is a single composer require plus whatever registration convention the target Statamic version requires. There is no build step, no asset pipeline, no database migration implied by the notes (the order value appears to ride on existing taxonomy term data). A competent Laravel developer can wire this up in under a day, most of which is verification rather than construction.

Technical risk. Low, with two specific caveats:

1. The reserved order field handle. This is now documented rather than fixed. Any taxonomy in the estate that already defines a field with the handle order — for display, sorting, or an editorial "sort position" convention — will collide. This is a silent-failure class of bug: it will not throw at install time. It requires an audit of existing taxonomy field sets before rollout.
2. Error surface change. v1.0.2 now propagates the Control Panel's own message (e.g. permission denied) instead of a generic error. This is an operational improvement but a behavioural change: any test or support runbook asserting on the previous generic string will need updating.

The v1.0.2 notes contain no breaking changes, no deprecations, and no public API changes. The Composer dist size reduction (≈160 KB → 60 KB) is achieved by excluding tests, CI workflows, and build tooling from the distributed archive. This is artifact hygiene, not a runtime change — but it does mean the published package no longer contains its own test suite, so you cannot validate the addon's behaviour from the vendor directory; validation must come from your own integration tests.

Key questions to resolve before committing:

• Which Statamic major version(s) does v1.0.2 support, and does that match our pinned version? The notes are silent.
• Does the addon apply ordering per-taxonomy, per-site, or globally? This determines multi-site behaviour, which the notes do not address.
• Is order written to the term's own data (making it portable across environments via content sync) or to a separate table (making it environment-local and in need of a migration/sync story)?
• What is the package's release cadence and maintainer count? A 60 KB addon with three patch releases suggests an actively maintained but small project — bus-factor risk.
• Does the empty-state message respect Statamic's localization, or is it hardcoded English?

Integration Approach

Stack fit. Assumes a Laravel + Statamic application using taxonomies for content classification. If the estate uses taxonomies purely as flat tag lists with no editorial ordering requirement, this addon delivers no value and should be declined — the cheapest integration is the one you don't do. Confirm the ordering requirement exists and is currently solved (or unsolved) some other way.

Migration path. No data migration is implied if order is a new field handle. If an existing field must be renamed to free up the order handle, that is a content migration and needs the standard treatment: a scripted rename, a content-sync verification pass across environments, and a rollback plan. Scope this explicitly — it is the only place in this integration where existing content can be lost.

Compatibility. Pin to ^1.0 and verify against the exact Statamic and PHP versions in the estate. Because the distributed package no longer ships its tests, treat our own acceptance test as the compatibility gate: install, order a set of terms, publish, reorder, publish again, and confirm the order survives a cache clear and a content-sync round trip.

Sequencing. Four steps, in order:

1. Audit existing taxonomy field sets for an order handle collision. Blocking.
2. Spike on a staging environment: install, order terms, verify persistence and multi-site behaviour, verify permission-denied messaging renders the CP's message.
3. Pin and integrate to the main application; add the acceptance test to CI so the removed upstream tests are compensated for.
4. Roll out with an entry in the editorial handbook covering the empty state and the reserved field name.

Do not parallelise step 1 with anything — a collision discovered after rollout means content remediation, not a config change.

Operational Impact

Maintenance. Near-zero steady-state. No cron, no queue workers, no external service, no credentials. The maintenance obligation is version tracking: because the package excludes its own CI from the dist, we lose the upstream signal of "tests ran and passed" at install time. Compensate with a scheduled composer outdated check and a manual read of release notes on each bump, since semantic-versioning discipline on a project this size is not guaranteed by tooling.

Support. v1.0.2 is, in substance, a support-ticket reduction release. The two UX changes — a self-explaining empty state when a taxonomy has no terms, and surfacing the Control Panel's actual error message on failed saves and resets — convert two classes of "it's broken" tickets into self-service resolutions. Expect a measurable drop in tier-1 tickets from editors who hit an empty taxonomy and assumed a bug. The trade-off is that permission-denied messages will now appear verbatim to editors, which may prompt access-request tickets instead — a better ticket, but still a ticket. Brief the service desk on both.

Scaling. Negligible. Ordering operations are editorial-frequency, not request-frequency. The concern is not throughput but term count: if any taxonomy holds thousands of terms, the ordering UI is the bottleneck, not the server. Test with a realistic upper bound — the largest taxonomy in the estate — rather than a five-term fixture.

Failure modes. Three to plan for:

• Silent field collision — an existing order field silently shadows or is shadowed by the addon. Manifests as wrong ordering with no error. Mitigated by the pre-install audit.
• Order drift across environments — if order is stored outside content, staging and production diverge after a content sync. Confirm the storage model and test the sync round trip.
• Lost validation coverage — upstream tests are no longer distributed, so a regression in a future patch ships undetected unless our own acceptance test covers it. This is the failure mode most likely to bite six months out, and it is entirely self-inflicted if we skip step 3 of the sequencing.

Ramp-up. Developers: under a day, dominated by the collision audit. Editors: a short handbook entry — "if a taxonomy looks empty, it has no terms yet; if a save fails, read the message." No training programme warranted. The reserved order handle should be added to the team's field-naming conventions document so it is respected in future taxonomy design, not just this integration.