Sorter Bundle Laravel Package

Getting Started

Start by installing the package and publishing its assets:

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

Then inspect the published config file first — it typically defines the category/supercategory models, the sort column name, and whether ordering is global or scoped per supercategory. Check the package migrations to confirm the schema: you should expect a sort (or similarly named) integer column and a nullable parent/supercategory foreign key.

Apply the package trait to your model (or use the provided model directly):

use <Vendor>\\<Package>\\Traits\\HasSortableCategories;

class Category extends Model
{
    use HasSortableCategories;
}

Your first real use case is usually an admin-managed category tree: create a few supercategories, attach child categories, and render them in stored order. Seed a small fixture and verify that reordering a child updates only its siblings within the same supercategory. That exercise surfaces most configuration problems early.

Implementation Patterns

Scoped ordering. Most packages like this scope the sort value to the parent/supercategory. When listing categories, always query through the relationship or apply the package scope rather than a raw orderBy('sort') across the whole table. A typical pattern:

$supercategory->children()->ordered()->get();

If the package does not expose an ordered scope, use the documented sort column explicitly and always constrain by parent.

Moving categories between supercategories. Treat a move as a multi-step operation: reassign the parent, let the package recalculate the sort value, then persist. The v0.6.1 fix specifically addresses cases where the sort value failed to update after a supercategory change, so wrap moves in a transaction and assert the resulting order in tests:

DB::transaction(function () use ($category, $newParent) {
    $category->supercategory_id = $newParent->id;
    $category->save();
    // re-fetch and assert sort placement
});

Admin reordering. For drag-and-drop interfaces, send the ordered list of sibling IDs and update sort values in a single transaction. Avoid issuing one HTTP request per row; a bulk reorder endpoint that accepts an array is easier to lock and validate.

Tree rendering. Eager-load children recursively where the package supports it, or load a flat ordered collection and build the tree in memory. For navigation menus, cache the serialized tree and invalidate on create, update, delete, and move events.

API resources. Expose id, name, supercategory_id, and sort in your API resource. If clients can reorder, expose a dedicated reorder endpoint rather than allowing arbitrary sort writes through mass assignment.

Gotchas and Tips

• Sort values are usually sibling-scoped, not global. Do not assume sort = 1 is unique across the table. Queries that ignore the supercategory will appear to have duplicate or unstable ordering.
• Supercategory changes can leave stale sort values. This is exactly what v0.6.1 fixes. If you are on an earlier version, upgrade and re-test any move/reparent workflow. After upgrading, run a one-off repair query or command to normalize existing rows if users have already moved categories under the old behavior.
• Use transactions and, where supported, row locks for reorder operations. Concurrent drag-and-drop saves can produce duplicate sort values. A transaction plus lockForUpdate() on sibling rows is a cheap safeguard.
• Watch for N+1 queries when rendering trees. Recursive accessors that lazy-load children are convenient but expensive. Eager-load or cache.
• Cache invalidation is easy to miss. If you cache the tree, hook into the model’s saved/deleted events rather than clearing cache only in your admin controller.
• Check the migration column type and nullability. A nullable supercategory_id is normal for root categories, but your ordering scope must handle null parents consistently.
• Mass assignment. Do not allow sort and supercategory_id to be freely fillable from public requests; route those changes through dedicated actions.
• Debugging order issues. Log the sibling IDs and sort values before and after a move. If the sort value does not change, confirm the package’s event listeners are registered and that you are not using updateQuietly() or raw queries that bypass model events.
• Extension point. If the package dispatches events on reorder or move, prefer listening to those over overriding model methods. It keeps upgrades, including patch releases like v0.6.1, low-risk.