spatie/eloquent-sortable

If your sorting should be scoped to a specific group (e.g., a user_id), implement the buildSortQuery method in your model. This method should return a query builder that includes the necessary constraints to restrict sorting calculations to that group.

// MyModel.php

public function buildSortQuery()
{
    return static::query()->where('user_id', $this->user_id);
}

You can publish the package configuration to config/eloquent-sortable.php using the Artisan command.

php artisan vendor:publish --tag=eloquent-sortable-config

Install the package using Composer. For Laravel 6.x or PHP 7.x, you must use version 3.x of the package.

composer require spatie/eloquent-sortable

In Laravel 5.5 and above, the service provider is automatically registered. For older versions, manually add the provider to your config/app.php file.

'providers' => [
    ...
    Spatie\EloquentSortable\EloquentSortableServiceProvider::class,
];

To make a model sortable, you must:

1. Implement the Spatie\EloquentSortable\Sortable interface.
2. Use the Spatie\EloquentSortable\SortableTrait trait.
3. (Optional) Define a $sortable property to override default configuration settings like order_column_name or sort_when_creating.

use Spatie\EloquentSortable\Sortable;
use Spatie\EloquentSortable\SortableTrait;

class MyModel extends Model implements Sortable
{
    use SortableTrait;

    public $sortable = [
        'order_column_name' => 'order_column',
        'sort_when_creating' => true,
    ];

    // ...
}

If you need to sort based on a column other than the primary key (e.g., a UUID), use setNewOrderByCustomColumn.

Arguments:

1. string $column: The name of the custom column.
2. array $values: An array of values from that column in the desired order.
3. int $startingOrder (optional): The integer value to start the ordering from.

// Using UUIDs instead of primary keys
MyModel::setNewOrderByCustomColumn('uuid', [
   '7a051131-d387-4276-bfda-e7c376099715',
   '40324562-c7ca-4c69-8018-aff81bff8c95',
   '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1'
]);

// Using UUIDs with a starting order of 10
MyModel::setNewOrderByCustomColumn('uuid', [
   '7a051131-d387-4276-bfda-e7c376099715',
   '40324562-c7ca-4c69-8018-aff81bff8c95',
   '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1'
], 10);

Use setNewOrder to reorder all records in the model based on an array of IDs.

Arguments:

1. array $ids: An array of model IDs in the desired order.
2. int $startingOrder (optional): The integer value to start the ordering from.
3. mixed $query (optional): A query instance or null.
4. callable $queryModifier (optional): A closure to modify the query (e.g., to remove global scopes).

The package dispatches a Spatie\EloquentSortable\EloquentModelSortedEvent after a sort operation completes. You can listen for this event to perform post-sorting actions like clearing caches. Use the isFor() helper on the event to check which class was sorted.

use Spatie\EloquentSortable\EloquentModelSortedEvent as SortEvent;

class SortingListener
{
    public function handle(SortEvent $event): void {
        if ($event->isFor(MyClass::class)) {
            // Perform post-sorting logic, e.g., flush cache
        }
    }
}

The SortableTrait provides an ordered() query scope to fetch all records according to their order column.

$orderedRecords = MyModel::ordered()->get();

You can swap the order positions of two specific model instances using the static swapOrder method.

MyModel::swapOrder($myModel, $anotherModel);

The SortableTrait provides several methods to manipulate the order of a single model instance:

• $model->moveOrderDown(): Moves the model one position down.
• $model->moveOrderUp(): Moves the model one position up.
• $model->moveToStart(): Moves the model to the first position.
• $model->moveToEnd(): Moves the model to the last position.
• $model->isFirstInOrder(): Returns true if the model is currently first.
• $model->isLastInOrder(): Returns true if the model is currently last.

$myModel->moveOrderDown();
$myModel->moveOrderUp();

$myModel->moveToStart();
$myModel->moveToEnd();

$myModel->isFirstInOrder();
$myModel->isLastInOrder();