Laravel Nova Eloquent Sortable Laravel Package

Getting Started

Install the package via Composer and publish any required configuration or migrations:

composer require <vendor>/<package>
php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>"
php artisan migrate

The first place to look is the OrderColumn class (and any accompanying trait or interface). Its public methods define the supported reordering operations—typically moveToStart, moveToEnd, moveBefore, moveAfter, and methods for bulk reordering. Check the package README and the OrderColumn tests for concrete examples of the API.

A minimal first use case is a model with an integer order column. Add the provided trait (or use the OrderColumn class directly) to the model, then reorder a record:

$item = Item::find(1);
$item->moveToStart(); // or moveBefore($otherItem), etc.

Ensure the model’s table has the expected order column and that the column is included in $fillable only if you need mass assignment.

Implementation Patterns

• Model setup – Apply the package’s trait (often HasOrder or similar) and declare the order column name if it differs from the default (order). If the package does not provide a trait, use the OrderColumn class as a service to reorder models.
• Drag‑and‑drop reordering – Accept an array of model IDs in their new order from the front end. Within a database transaction, loop through the IDs and update each model’s order column (or call the package’s bulk reorder method if available). Use lockForUpdate() to prevent race conditions.
• Scoped ordering – If you have multiple independent lists (e.g., per category), include a scope column in your queries and order operations. The package may support a “group” or “scope” parameter; otherwise, enforce scoping manually in your reorder logic.
• Creation and deletion hooks – When creating a new model, the package may automatically assign the next order value. When deleting, you may need to compact order values (or accept gaps). Use model events or the package’s provided methods to keep order contiguous if required.
• Bulk updates – For large lists, avoid saving each model individually. Use the package’s bulk method if provided, or build a single CASE WHEN update. Always wrap in a transaction.
• Integration with admin panels – For Laravel Nova, Filament, or custom dashboards, map the UI’s reorder event to the package’s move* methods. Most packages provide a controller or endpoint that accepts a JSON array of IDs.

Gotchas and Tips

• Concurrency – Multiple users reordering the same list can produce duplicate or out‑of‑order values. Use database transactions with row-level locks (lockForUpdate) and consider optimistic locking (a version column) if supported.
• Version 3.0.1 patch – This release fixes minor issues in the OrderColumn class. Always run the latest patch; if you were on 3.0.0, review the diff for any behavioral changes affecting your reordering logic.
• Major version 3.x – Since this is a major release, check the upgrade guide for breaking changes from 2.x. Common breaking changes include renamed methods, changed default column names, or removed traits.
• Gaps after deletion – Order values may become non-contiguous after deletions. If your UI or business logic requires a dense sequence, implement a compaction method (e.g., renumber all rows) and call it after deletes, or use the package’s built‑in compaction if available.
• Soft deletes – If your model uses soft deletes, ensure order queries exclude trashed records unless you explicitly want them included. Use the model’s default scope or add whereNull('deleted_at').
• Config quirks – The package may publish a config file for the default column name, table name, or scope column. Publish it early and adjust as needed. Clear the config cache after changes (php artisan config:clear).
• Debugging – Use DB::listen() or Laravel Telescope to inspect the SQL generated during reordering. Look for unexpected UPDATE statements or missing WHERE clauses that could reorder unintended rows.
• Extension points – You can often extend the OrderColumn class or override trait methods in your model to customise behaviour (e.g., custom order value assignment). Check the package’s contracts and interfaces for safe extension points.