Taxonomy Terms Order Laravel Package

Getting Started

• Install with composer require the vendor/package shown in the release, then let Statamic/Laravel auto-discover the addon's service provider. Run php artisan statamic:stache:clear (and php artisan cache:clear) so the new CP page and the order field are picked up.
• Look first at the Control Panel: Taxonomies → [your taxonomy] → Order. That page is the primary surface of this addon in 1.0.2 — it lists terms and lets you save or reset their ordering. Second, check the addon's config/service provider for any publishable config and confirm which field it writes to.
• First use case: pick a taxonomy that already has terms, drag them into the desired sequence, save, and verify the values land on the term's order field in the Stache. Then render that order on the front end (e.g. {{ taxonomy:tags order_by="order" }} or a Term::query()->orderBy('order') in PHP) to prove the round trip.

Implementation Patterns

• Treat the CP page as the editor-facing tool, and the order field as the integration API. Editors reorder visually; your templates and queries read order. This keeps front-end code independent of the addon's UI.
• Programmatic ordering: for imports, seeds, or migrations, write the order field directly on taxonomy terms rather than driving the CP. Run the addon's reset action afterwards if you need contiguous numbering.
• Front-end sorting: use Statamic's taxonomy query builder with an explicit order_by="order" / sort="order". Don't assume default term ordering matches what editors see in the CP.
• Deploy workflow: because ordering is content, it travels with the Stache/content files. After a content sync or a restore, re-save or reset the order page if numbers look stale, and clear caches in the same deploy step.
• Multi-taxonomy: expect one order page per taxonomy and a separate save/reset per context. Build any custom tooling around the taxonomy handle, not a single global order.
• Pin the constraint (^1.0) in composer.json. This is an early 1.x addon; the CP internals may move even where the order field contract holds.

Gotchas and Tips

• order is reserved. Do not add your own order field to taxonomy terms — the addon owns it. If you need a second sort dimension (e.g. weight, priority), use a different handle and do the secondary sort in your query.
• Permission failures are now legible. In 1.0.2, failed saves and resets return the Control Panel's message instead of a generic error. If a save fails with "permission denied", the fix is a role/permission grant on the taxonomy — not a bug in the addon.
• Empty taxonomies are no longer a mystery. The order page now explains that a taxonomy has no terms. If you still see nothing useful, check that terms exist for the current site/locale and aren't filtered out.
• Debugging saves: watch the CP network response for the save/reset request — that JSON now carries the real error. On the server side, read the term's order value out of the Stache to confirm whether the write landed.
• Distribution is leaner in 1.0.2. Tests, CI, and build tooling are stripped from the Composer package (~60 KB). That's good for install size, but there are no tests to read in vendor/ — go to the source repository if you need to understand behavior or contribute a fix.
• Caching: term listings cached in your own app won't know about a reorder. Clear application cache on deploy and after bulk ordering changes.
• Extension points are thin. The order page is CP UI; the stable hook for custom work is the order field plus the addon's reset/save actions. Prefer that over overriding CP assets, which will break across minor releases.