Nova Blog Laravel Package

Getting Started

This release (9.7.0) wires the package's Category Nova resource into nova-sortable, so categories can be drag-and-drop reordered from the Nova index. If you are adopting the package at this version:

1. composer require <vendor>/<package> — confirm nova-sortable (and a Nova 4/5 compatible major) is pulled in transitively, or add it explicitly if your app already pins it.
2. Publish and run migrations: php artisan vendor:publish --tag=<package>-migrations && php artisan migrate. The categories table needs its order column (typically sort_order or order_column) present — check the published migration rather than assuming the name.
3. Publish config if the package ships one, and register the Nova resource in NovaServiceProvider::resources() (or verify auto-discovery covers src/Nova/Category.php).
4. First use case: seed a handful of categories, open the Nova Category index, drag one row, refresh, and confirm the persisted order survives. That single loop validates the migration, the Sortable field, and the reorder endpoint in one go.

Where to look first: src/Nova/Category.php (the fields() method and any sortable() override), the categories migration, and the package config for the order column name.

Implementation Patterns

Nova-driven ordering. The intended workflow is that merchandisers own ordering in the Nova UI, not developers in code. Treat the order column as UI-owned state: avoid seeders or imports that write arbitrary values after launch, or you will fight the drag-and-drop handler.

Reading ordered data in your app. Use the package's ordered scope (or ->orderBy('sort_order')) everywhere you render categories — navigation, dropdowns, API resources. Centralise this in a repository method or a local scope so the column name lives in one place.

Nested or parented categories. If categories are hierarchical, ordering must be scoped per parent. Verify whether the resource's sortable() call passes a parent/group key; if not, wrap the Nova field configuration yourself so dragging within one parent does not interleave siblings from another.

Cache invalidation on reorder. Ordering is data, so any cached nav/menu structure goes stale the moment someone drags a row. Hook a model observer on saved/updated (or the Nova resource's reorder path) to bust the cache key. This is the most common production gap when adding sortable resources.

API and front-end contracts. Expose sort_order (or rely on collection order) consistently. If your SPA re-sorts client-side, keep the server as source of truth and re-fetch after reorder rather than optimistic-only updates.

Testing. Write a feature test that authenticates as a Nova user and POSTs the reorder payload nova-sortable sends, then asserts the column values. This catches Nova major-version payload changes cheaply.

Gotchas and Tips

• Nova version compatibility is the main upgrade risk. nova-sortable majors track Nova majors. On a 9.x minor bump this is usually safe, but if you are on Nova 3 or a pre-release Nova 5, check the constraint before composer update.
• Publish-with---force will clobber customisations. If you have edited the published Category resource (extra fields, authorization, searchable columns), re-publishing for 9.7.0 will overwrite it. Diff first or re-apply by hand.
• Existing installs may need a migration, not just a composer bump. If your categories table predates the sortable column, the reorder endpoint will silently no-op or 500. Run php artisan migrate and verify the column exists before testing the drag handle.
• Null and duplicate order values. Legacy rows with NULL or duplicated sort_order render unpredictably in the Nova index and break drag maths. Backfill with a deterministic order in a one-off migration (ROW_NUMBER() or an iterated update) before enabling reordering for editors.
• Debugging a failed drag: inspect the PATCH/POST to the Nova reorder endpoint in the network tab, confirm the payload's resourceId/resourceIds shape matches your nova-sortable version, and check the column is fillable or updated via a query builder call rather than mass assignment.
• Authorisation. Reordering is an update action — make sure your Nova policy's update ability gates it, otherwise users with view-only access may still be able to reorder rows.
• Extension point: the Sortable field accepts options for the order column and scope. If you need per-tenant ordering, supply the scope there rather than post-processing in a controller.