Eloquent Sortable

https://github.com/spatie/eloquent-sortable
Admin
Eloquent Sortable is a Laravel package that adds sortable behavior to Eloquent models, automatically...
Tokens:24,501
Snippets:182
Trust Score:10
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install eloquent-sortable via Composer

Source: https://github.com/spatie/eloquent-sortable/blob/main/README.md

Run this command to install the package through Composer. For Laravel 6.x or PHP 7.x, use version 3.x of this package.

```bash
composer require spatie/eloquent-sortable
```

--------------------------------

### moveOrderDown() usage example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Example showing how to use moveOrderDown() to swap order with the next model, and the no-op behavior when the model is already last.

```php
$model = MyModel::find(3);
$model = $model->moveOrderDown(); // order_column 3 <-> 4 with the next model

// no-op when already last
$last = MyModel::ordered('desc')->first();
$last = $last->moveOrderDown(); // returns $last, no changes
```

--------------------------------

### Manual provider registration in config/app.php (duplicate)

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-sortable-service-provider.md

Another instance of the manual registration example, shown in the 'Registering the provider manually' section.

```php
// config/app.php
'providers' => [
    // ...
    Spatie\EloquentSortable\EloquentSortableServiceProvider::class,
],
```

--------------------------------

### moveBefore() usage example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Example showing how to use moveBefore() to position a new model directly before an anchor model. The new model is created and then moved before the anchor.

```php
$anchor = MyModel::find(4);
$newModel = MyModel::create(['name' => 'New']);
$newModel->moveBefore($anchor); // $newModel now sits directly before $anchor
```

--------------------------------

### setNewOrderByCustomColumn() example with custom start order

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Shows how to reorder records using a custom primary key column (e.g., 'uuid') with an array of IDs. The optional $startOrder parameter defaults to 1 and increments per record. The second call demonstrates passing a custom start order of 10.

```php
MyModel::setNewOrderByCustomColumn('uuid', [
    '7a051131-d387-4276-bfda-e7c376099715',
    '40324562-c7ca-4c69-8018-aff81bff8c95',
    '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1',
]);

// with a custom start order
MyModel::setNewOrderByCustomColumn('uuid', $uuids, 10);
```

--------------------------------

### Sortable Interface Usage

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-interface.md

Example of implementing the Sortable interface and using its required methods and scope.

```APIDOC
## Sortable Interface

### Description
Defines the contract for Eloquent models that can be sorted. Implementing this interface requires the use of the SortableTrait and the following methods and scope.

### Methods

#### setNewOrder(array $order)
- **Static method** - Sets a new order for the models based on the given array of IDs.

#### ordered()
- **Scope** - Returns a query builder ordered by the sort column.

#### setHighestOrderNumber()
- **Instance method** - Sets the model's order number to the highest value.

#### shouldSortWhenCreating()
- **Instance method** - Returns a boolean indicating whether the model should be sorted when created.

### Example Usage

```php
use Spatie\EloquentSortable\Sortable;
use Spatie\EloquentSortable\SortableTrait;

class Article extends Model implements Sortable
{
    use SortableTrait;

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

// Static call:
Article::setNewOrder([9, 3, 7]);

// Scope:
$articles = Article::ordered()->get();

// Instance calls:
$article = Article::find(1);
$article->setHighestOrderNumber();
$article->shouldSortWhenCreating(); // bool
```

### Related
- SortableTrait - concrete implementation
- configuration.md - the $sortable property and config options
- errors.md - setNewOrder() failure conditions
```

--------------------------------

### moveAfter() example: moving a new model after an anchor

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Demonstrates using moveAfter() to position a newly created model immediately after an existing anchor model. The example finds an anchor model by ID, creates a new model, and calls moveAfter() on it.

```php
$anchor = MyModel::find(3);
$newModel = MyModel::create(['name' => 'New']);
$newModel->moveAfter($anchor); // $newModel now sits directly after $anchor
```

--------------------------------

### Registering listener and using instance argument

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-model-sorted-event.md

Example showing how to register the listener and use an instance argument with isFor(). It demonstrates that isFor() performs an exact class match, so subclasses do not match.

```php
use Illuminate\Support\Facades\Event;
use Spatie\EloquentSortable\EloquentModelSortedEvent;

// Register the listener in a service provider:
Event::listen(EloquentModelSortedEvent::class, SortingListener::class);

// Inside the listener, an instance can also be used:
public function handle(EloquentModelSortedEvent $event): void
{
    $instance = MyModel::first();

    if ($event->isFor($instance)) {
        // matches, because get_class($instance) === $event->model
    }

    // exact-class semantics:
    $event->isFor(ChildModel::class); // false even if ChildModel extends MyModel
}
```

--------------------------------

### Basic listener example using EloquentModelSortedEvent

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-model-sorted-event.md

Example of using the event inside a listener. It imports the event with an alias and checks if the event is for a specific model class using isFor().

```php
use Spatie\EloquentSortable\EloquentModelSortedEvent as SortEvent;

class SortingListener
{
    public function handle(SortEvent $event): void
    {
        if ($event->isFor(MyModel::class)) {
            // e.g. flush a cache for MyModel
        }
    }
}
```

--------------------------------

### setNewOrder() basic usage examples

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Shows how to re-order records using setNewOrder() with an array of IDs, a custom start order, and a non-primary column.

```php
// record id 3 -> order_column 1
// record id 1 -> order_column 2
// record id 2 -> order_column 3
MyModel::setNewOrder([3, 1, 2]);

// starting at 10: 3->10, 1->11, 2->12
MyModel::setNewOrder([3, 1, 2], 10);

// re-order using a non-primary column
MyModel::setNewOrder(['uuid-b', 'uuid-a'], 1, 'uuid');
```

--------------------------------

### moveOrderUp() usage example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Shows how to call moveOrderUp() on a model to swap its order with the previous model. If the model is already first, the method returns the model unchanged.

```php
$model = MyModel::find(4);
$model = $model->moveOrderUp(); // order_column 4 <-> 3 with the previous model

// no-op when already first
$first = MyModel::ordered()->first();
$first = $first->moveOrderUp(); // returns $first, no changes
```

--------------------------------

### Automatic order assignment example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Shows how creating a new model triggers the bootSortableTrait() listener to set the order column to max + 1.

```php
$model = new MyModel();
$model->save(); // bootSortableTrait()'s listener sets order_column to max + 1
```

--------------------------------

### moveToStart() example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Moves the model to the first position in the sort scope. If already first, returns unchanged; otherwise takes the first model's order value and increments all other records by 1.

```php
$model = MyModel::find(5);
$model = $model->moveToStart();
echo $model->order_column; // 1 (was 5); all other records shifted up by 1
```

--------------------------------

### swapOrder() example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Swaps the order of two models by delegating to swapOrderWithModel(). The order_column values of the two models are exchanged.

```php
MyModel::swapOrder($firstModel, $secondModel);
// $firstModel->order_column and $secondModel->order_column are exchanged
```

--------------------------------

### scopeOrdered() usage examples

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Shows how to use the ordered() scope to retrieve models in ascending (default) or descending order, and to combine with other constraints.

```php
// ascending (default)
$ascending = MyModel::ordered()->get();

// descending
$descending = MyModel::ordered('desc')->get();

// combine with other constraints
$latest = MyModel::where('active', true)->ordered()->get();
```

--------------------------------

### getHighestOrderNumber() usage example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Queries the maximum order-column value within the model's sort scope. The example creates a new model and calls the method, noting that the next created record gets the returned value plus one.

```php
$highest = (new MyModel())->getHighestOrderNumber();
// $highest is an int; the next created record gets $highest + 1
```

--------------------------------

### shouldSortWhenCreating() example: NoAutoSortModel

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Shows a model class that disables automatic sorting on creation by setting 'sort_when_creating' to false in the $sortable property. The example then demonstrates that shouldSortWhenCreating() returns false and that saving the model does not auto-assign the order_column.

```php
class NoAutoSortModel extends Model implements Sortable
{
    use SortableTrait;

    public $sortable = ['sort_when_creating' => false];
}

$model = new NoAutoSortModel();
var_dump($model->shouldSortWhenCreating()); // false
$model->save(); // order_column is NOT auto-assigned
```

--------------------------------

### getLowestOrderNumber() usage example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Queries the minimum order-column value within the model's sort scope. The example creates a new model and calls the method.

```php
$lowest = (new MyModel())->getLowestOrderNumber();
```

--------------------------------

### swapOrderWithModel() usage example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Shows how to call swapOrderWithModel() to exchange order values between two models. The other model first takes the current model's order value, then the current model takes the other's previous value.

```php
$first = MyModel::find(3);
$second = MyModel::find(4);

$first->swapOrderWithModel($second); // 3 <-> 4
// $first->order_column === 4, $second->order_column === 3
```

--------------------------------

### determineOrderColumnName() example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Instantiates a model and calls determineOrderColumnName() to get the order column name. The comment indicates the default value is 'order_column' when no custom column is configured.

```php
$model = new MyModel();
echo $model->determineOrderColumnName(); // 'order_column' (default)
```

--------------------------------

### setHighestOrderNumber() usage example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Sets the model's order column to one greater than the current maximum order value within the sort query. The example creates a new model, calls the method, and echoes the resulting order column value.

```php
$model = new MyModel();
$model->setHighestOrderNumber();
echo $model->order_column; // e.g. 21 if the previous max was 20
```

--------------------------------

### Implementing Sortable interface with SortableTrait

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-interface.md

Shows a model implementing the Sortable interface and using the SortableTrait. The $sortable property configures the order column name and whether to sort when creating. Includes examples of the required static call, scope, and instance methods.

```php
use Spatie\EloquentSortable\Sortable;
use Spatie\EloquentSortable\SortableTrait;

class Article extends Model implements Sortable
{
    use SortableTrait;

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

// Interface-required static call:
Article::setNewOrder([9, 3, 7]);

// Interface-required scope:
$articles = Article::ordered()->get();

// Interface-required instance calls:
$article = Article::find(1);
$article->setHighestOrderNumber();
$article->shouldSortWhenCreating(); // bool
```

--------------------------------

### Trigger exception with integer $ids

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/errors.md

Minimal example that triggers the exception by passing an integer as $ids, which is neither an array nor an ArrayAccess instance. Also applies to null and any other scalar/object that does not implement ArrayAccess.

```php
MyModel::setNewOrder(42); // throws
```

--------------------------------

### setNewOrderByCustomColumn()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Sets a new order for records using a custom primary key column. It accepts an ordered list of IDs and an optional start order value.

```APIDOC
## setNewOrderByCustomColumn()

### Description
Convenience wrapper around `setNewOrder()` that forces a specific matching column. Equivalent to calling `setNewOrder($ids, $startOrder, $primaryKeyColumn)`.

### Method
PHP static method

### Signature
```php
public static function setNewOrderByCustomColumn(string $primaryKeyColumn, $ids, int $startOrder = 1)
```

### Parameters
- **$primaryKeyColumn** (string) - Required - Column whose values are matched against `$ids` (e.g. `'uuid'`).
- **$ids** (array|\ArrayAccess) - Required - Ordered list of values for `$primaryKeyColumn`.
- **$startOrder** (int) - Optional - Default: `1` - First order value to assign; incremented per record.

### Return Type
void (in effect)

### Throws
`\InvalidArgumentException` for a non-array/non-`ArrayAccess` `$ids`.

### Example
```php
MyModel::setNewOrderByCustomColumn('uuid', [
    '7a051131-d387-4276-bfda-e7c376099715',
    '40324562-c7ca-4c69-8018-aff81bff8c95',
    '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1',
]);

// with a custom start order
MyModel::setNewOrderByCustomColumn('uuid', $uuids, 10);
```
```

--------------------------------

### Trigger exception with string $ids

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/errors.md

Minimal example that triggers the exception by passing a string as $ids. The exception message will be 'You must pass an array or ArrayAccess object to setNewOrder'.

```php
MyModel::setNewOrder('not-an-array'); // throws
```

--------------------------------

### moveToEnd() example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Moves the model to the last position in the sort scope. If already at the maximum order value, returns unchanged; otherwise assigns the maximum order value and decrements all records between old and new position by 1.

```php
$model = MyModel::find(3);
$model = $model->moveToEnd();
echo $model->order_column; // now equals the previous maximum order value
```

--------------------------------

### isFirstInOrder() usage example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Checks if the model is the first record in the sort scope. Returns true when the model's order value equals getLowestOrderNumber(). Use to handle first-position logic.

```php
$first = MyModel::ordered()->first();
if ($first->isFirstInOrder()) {
    // handle first-position logic
}
```

--------------------------------

### setNewOrder()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Static method that re-orders records in a single pass. Updates the order column for each provided id, with optional start order, custom primary key column, and query modification callback.

```APIDOC
## setNewOrder()

### Description
Re-orders records in a single pass. For each id in `$ids` (in order), it updates the matching record's order column to the current `$startOrder` value and increments `$startOrder`. The update runs via `withoutGlobalScope(SoftDeletingScope::class)`, so soft-deleted records are included. When `config('eloquent-sortable.ignore_timestamps')` is `true`, the model class is temporarily added to the framework's `$ignoreTimestampsOn` list so `updated_at` is not touched, and removed again afterwards. After all updates, an `EloquentModelSortedEvent` is dispatched with `static::class`.

### Method
setNewOrder (static)

### Signature
```php
public static function setNewOrder(
    $ids,
    int $startOrder = 1,
    ?string $primaryKeyColumn = null,
    ?callable $modifyQuery = null
): void
```

### Parameters
- `$ids` (array|\ArrayAccess) - Required - Ordered list of key values. The record whose key is first gets the lowest order number, the second gets the next, and so on.
- `$startOrder` (int) - Optional - Default: `1` - The order value assigned to the first record in `$ids`. Incremented by 1 for each subsequent record.
- `$primaryKeyColumn` (?string) - Optional - Default: `null` - Column used to match records. When `null`, the model's qualified key name (`getQualifiedKeyName()`) is used.
- `$modifyQuery` (?callable) - Optional - Default: `null` - Callable receiving the Eloquent `Builder`. It may alter the query (e.g. drop global scopes) before the `update` is executed.

### Return Type
void

### Throws
- \InvalidArgumentException - If `$ids` is neither an array nor an `ArrayAccess` instance. Message: `'You must pass an array or ArrayAccess object to setNewOrder'`.

### Example (basic)
```php
// record id 3 -> order_column 1
// record id 1 -> order_column 2
// record id 2 -> order_column 3
MyModel::setNewOrder([3, 1, 2]);

// starting at 10: 3->10, 1->11, 2->12
MyModel::setNewOrder([3, 1, 2], 10);

// re-order using a non-primary column
MyModel::setNewOrder(['uuid-b', 'uuid-a'], 1, 'uuid');
```

### Example (error handling and query modification)
```php
use Spatie\EloquentSortable\SortableTrait;

// Throwing on a bad argument:
try {
    MyModel::setNewOrder('not-an-array');
} catch (\InvalidArgumentException $e) {
    // $e->getMessage() === 'You must pass an array or ArrayAccess object to setNewOrder'
}

// Dropping a custom global scope before re-ordering:
MyModel::setNewOrder([3, 1, 2], 1, null, function ($query) {
    $query->withoutGlobalScope(new ActiveScope);
});
```
```

--------------------------------

### isLastInOrder() usage example

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Checks if the model is the last record in the sort scope. Returns true when the model's order value equals getHighestOrderNumber(). Use to handle last-position logic.

```php
$last = MyModel::ordered('desc')->first();
if ($last->isLastInOrder()) {
    // handle last-position logic
}
```

--------------------------------

### Run package tests with vendor/bin/phpunit

Source: https://github.com/spatie/eloquent-sortable/blob/main/README.md

Runs the package's integration and smoke tests, set up with Orchestra. Execute from the project root.

```bash
vendor/bin/phpunit
```

--------------------------------

### moveToStart()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Instance method that moves the current model to the first position in the sort scope, shifting other records up by one.

```APIDOC
## `moveToStart()`

### Description
Moves the current model to the first position in the sort scope. If the model is already first, it is returned unchanged. Otherwise the model takes the current first model's order value and is saved, then every other record in the scope is incremented by 1.

### Method
`moveToStart`

### Signature
```php
public function moveToStart(): static
```

### Parameters
None.

### Return Type
`static` — returns `$this` (fluent).

### Example
```php
$model = MyModel::find(5);
$model = $model->moveToStart();
echo $model->order_column; // 1 (was 5); all other records shifted up by 1
```
```

--------------------------------

### Create and save MyModel records to auto-assign order_column

Source: https://github.com/spatie/eloquent-sortable/blob/main/README.md

Creates three MyModel instances and saves each. With an empty table, the first save sets order_column to 1, the second to 2, and the third to 3, because sort_when_creating is enabled.

```php
$myModel = new MyModel();
$myModel->save(); // order_column for this record will be set to 1

$myModel = new MyModel();
$myModel->save(); // order_column for this record will be set to 2

$myModel = new MyModel();
$myModel->save(); // order_column for this record will be set to 3

```

--------------------------------

### configurePackage(Package $package): void

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-sortable-service-provider.md

Configures the package by setting its name and registering the config file. This method is called by the package tools during service provider registration.

```APIDOC
## configurePackage(Package $package): void

### Description
Configures the package by setting the package name to 'eloquent-sortable' and registering the config file via `hasConfigFile()`. This makes config values available under `config('eloquent-sortable.*')` and enables the `vendor:publish` command.

### Method
configurePackage

### Signature
```php
public function configurePackage(Package $package): void
```

### Parameters
- **$package** (Spatie\LaravelPackageTools\Package) - Required - The package definition object provided by laravel-package-tools.

### Return Type
void

### Source
`src/EloquentSortableServiceProvider.php:10-14`

### Example
```php
$package
    ->name('eloquent-sortable')
    ->hasConfigFile();
```
```

--------------------------------

### bootSortableTrait() signature

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

The bootSortableTrait() method signature from the source file, which is automatically invoked by Eloquent and registers a creating event listener.

```php
public static function bootSortableTrait()
```

--------------------------------

### Usage prerequisites for SortableTrait

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Shows how to use the SortableTrait in an Eloquent model, implementing the Sortable interface and setting the $sortable property with order_column_name and sort_when_creating.

```php
use Spatie\EloquentSortable\Sortable;
use Spatie\EloquentSortable\SortableTrait;
use Illuminate\Database\Eloquent\Model;

class MyModel extends Model implements Sortable
{
    use SortableTrait;

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

--------------------------------

### Publish config command

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-sortable-service-provider.md

Command to publish the package's config file to config/eloquent-sortable.php.

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

--------------------------------

### Listen for EloquentModelSortedEvent with isFor helper

Source: https://github.com/spatie/eloquent-sortable/blob/main/README.md

Registers a listener for the Spatie\EloquentSortable\EloquentModelSortedEvent. The handle method receives the event and uses isFor(MyClass::class) to check whether the sorted Eloquent class matches, so post-sorting logic like cache flushing can run conditionally.

```php
use Spatie\EloquentSortable\EloquentModelSortedEvent as SortEvent;

class SortingListener
{
    public function handle(SortEvent $event): void {
        if ($event->isFor(MyClass::class)) {
            // ToDo: flush our cache
        }
    }
}
```

--------------------------------

### Implementing the Sortable interface with SortableTrait

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-interface.md

Shows how to make a model sortable by implementing the Sortable interface and using the SortableTrait. The trait provides concrete implementations for all interface methods.

```php
use Spatie\EloquentSortable\Sortable;
use Spatie\EloquentSortable\SortableTrait;
use Illuminate\Database\Eloquent\Model;

class MyModel extends Model implements Sortable
{
    use SortableTrait;
}
```

--------------------------------

### configurePackage method signature

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-sortable-service-provider.md

The signature of the configurePackage method, which is called by laravel-package-tools to set up the package.

```php
public function configurePackage(Package $package): void
```

--------------------------------

### EloquentSortableServiceProvider class declaration

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-sortable-service-provider.md

The exact class definition from the source file. It extends PackageServiceProvider and configures the package with the name 'eloquent-sortable' and a config file.

```php
class EloquentSortableServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('eloquent-sortable')
            ->hasConfigFile();
    }
}
```

--------------------------------

### moveBefore() signature

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Public method signature for moveBefore() from SortableTrait.php:114. Accepts a Sortable model and returns void.

```php
public function moveBefore(Sortable $model): void
```

--------------------------------

### moveOrderUp()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Swaps the order of the current model with the previous model in order. If the model is already first, it returns unchanged.

```APIDOC
## `moveOrderUp()`

### Description
Swaps the order of the current model with the previous model in order (the first record in descending order whose order value is less than the current one). If no such model exists (i.e. the model is already first), the model is returned unchanged and nothing is modified.

### Method
`moveOrderUp`

### Signature
```php
public function moveOrderUp(): static
```

### Parameters
None.

### Return Type
`static` — returns `$this` (fluent).

### Example
```php
$model = MyModel::find(4);
$model = $model->moveOrderUp(); // order_column 4 <-> 3 with the previous model

// no-op when already first
$first = MyModel::ordered()->first();
$first = $first->moveOrderUp(); // returns $first, no changes
```
```

--------------------------------

### buildSortQuery()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Returns the query builder used for all order calculations and bulk updates. Override this method in your model to restrict sorting to a subset of records, enabling grouping.

```APIDOC
## buildSortQuery()

### Description
Returns the query builder used for all order calculations and bulk updates. The default implementation returns `static::query()`. Override this method in your model to restrict sorting to a subset of records — this is how grouping is implemented.

### Method
`buildSortQuery()`

### Signature
```php
public function buildSortQuery(): Builder
```

### Parameters
None.

### Return Type
`\Illuminate\Database\Eloquent\Builder`

### Example (override for grouping)
```php
class MyModel extends Model implements Sortable
{
    use SortableTrait;

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

--------------------------------

### shouldSortWhenCreating()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Determines whether a new model instance should automatically receive the highest order number on creation. Reads the sortable configuration or falls back to the global config.

```APIDOC
## shouldSortWhenCreating()

### Description
Determines whether a new model instance should automatically receive the highest order number on creation. Reads `$this->sortable['sort_when_creating']` if set, otherwise falls back to `config('eloquent-sortable.sort_when_creating', true)`.

### Method
shouldSortWhenCreating

### Signature
`public function shouldSortWhenCreating(): bool`

### Parameters
None.

### Return Type
`bool`

### Example
```php
class NoAutoSortModel extends Model implements Sortable
{
    use SortableTrait;

    public $sortable = ['sort_when_creating' => false];
}

$model = new NoAutoSortModel();
var_dump($model->shouldSortWhenCreating()); // false
$model->save(); // order_column is NOT auto-assigned
```
```

--------------------------------

### swapOrder()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Static method that swaps the order of two models by delegating to the first model's swapOrderWithModel method.

```APIDOC
## `swapOrder()`

### Description
Static wrapper that swaps the order of two models by delegating to `$model->swapOrderWithModel($otherModel)`.

### Method
`swapOrder`

### Signature
```php
public static function swapOrder(Sortable $model, Sortable $otherModel): void
```

### Parameters
- `$model` (Sortable) - Required - First model to swap.
- `$otherModel` (Sortable) - Required - Second model to swap.

### Return Type
`void`

### Example
```php
MyModel::swapOrder($firstModel, $secondModel);
// $firstModel->order_column and $secondModel->order_column are exchanged
```
```

--------------------------------

### Configure sortable model with $sortable property

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/types.md

Declare the public $sortable array on a consuming model to configure sortable behaviour. Both keys are optional; when absent, values fall back to the package config. `order_column_name` sets the column storing the order value (default 'order_column'), and `sort_when_creating` controls whether sorting happens on creation (default true).

```php
public $sortable = [
    'order_column_name' => 'order_column', // string, default
    'sort_when_creating' => true,          // bool, default
];
```

--------------------------------

### swapOrderWithModel()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Exchanges the order-column values of the current model and another model. Both models are persisted via save().

```APIDOC
## `swapOrderWithModel()`

### Description
Exchanges the order-column values of the current model and `$otherModel`. Both models are persisted via `save()`. The other model first takes the current model's order value, then the current model takes the other model's previous order value.

### Method
`swapOrderWithModel`

### Signature
```php
public function swapOrderWithModel(Sortable $otherModel): static
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$otherModel` | `Sortable` | yes | — | The model to swap order values with. |

### Return Type
`static` — returns `$this` (fluent).

### Example
```php
$first = MyModel::find(3);
$second = MyModel::find(4);

$first->swapOrderWithModel($second); // 3 <-> 4
// $first->order_column === 4, $second->order_column === 3
```
```

--------------------------------

### Manual provider registration in config/app.php

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-sortable-service-provider.md

Register the service provider manually in Laravel versions before 5.5. Add this to the 'providers' array in config/app.php.

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

--------------------------------

### moveOrderDown(): static

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Swaps the order of the current model with the next model in order. If the current model is already last, it returns unchanged without modifying anything.

```APIDOC
## moveOrderDown(): static

### Description
Swaps the order of the current model with the next model in order (the first record in the sort scope whose order value is greater than the current one). If no such model exists (i.e., the model is already last), the model is returned unchanged and nothing is modified.

### Method
moveOrderDown

### Signature
public function moveOrderDown(): static

### Parameters
None.

### Return Type
static - returns $this (fluent)

### Example
```php
$model = MyModel::find(3);
$model = $model->moveOrderDown(); // order_column 3 <-> 4 with the next model

// no-op when already last
$last = MyModel::ordered('desc')->first();
$last = $last->moveOrderDown(); // returns $last, no changes
```
```

--------------------------------

### buildSortQuery() override for grouping

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Override buildSortQuery() to restrict sorting to a subset of records, enabling grouping. The default implementation returns static::query().

```php
class MyModel extends Model implements Sortable
{
    use SortableTrait;

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

--------------------------------

### EloquentModelSortedEvent::__construct

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-model-sorted-event.md

Constructor for the EloquentModelSortedEvent class. Initializes the event with the fully-qualified class name of the sorted model.

```APIDOC
## EloquentModelSortedEvent::__construct

### Description
Creates a new EloquentModelSortedEvent instance with the given model class name.

### Method
Constructor

### Signature
```php
public function __construct(string $model)
```

### Parameters
- **$model** (string) - Required - Fully-qualified class name of the sorted model.

### Return Type
None (constructor).

### Source
`src/EloquentModelSortedEvent.php:11-14`
```

--------------------------------

### moveOrderDown() signature

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Public method signature for moveOrderDown() from SortableTrait.php:128. Returns static for fluent chaining.

```php
public function moveOrderDown(): static
```

--------------------------------

### Composer.json auto-discovery entry

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-sortable-service-provider.md

The composer.json extra.laravel.providers entry that enables auto-discovery of the service provider in Laravel 5.5 and above.

```json
"extra": {
    "laravel": {
        "providers": [
            "Spatie\\EloquentSortable\\EloquentSortableServiceProvider"
        ]
    }
}
```

--------------------------------

### setNewOrder() error handling and query modification

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Shows how to catch an InvalidArgumentException when passing a non-array, and how to drop a custom global scope before re-ordering.

```php
use Spatie\EloquentSortable\SortableTrait;

// Throwing on a bad argument:
try {
    MyModel::setNewOrder('not-an-array');
} catch (\InvalidArgumentException $e) {
    // $e->getMessage() === 'You must pass an array or ArrayAccess object to setNewOrder'
}

// Dropping a custom global scope before re-ordering:
MyModel::setNewOrder([3, 1, 2], 1, null, function ($query) {
    $query->withoutGlobalScope(new ActiveScope);
});
```

--------------------------------

### moveBefore(Sortable $model): void

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Moves the current model to the position immediately before the given reference model. All records in the sort scope with an order value greater than or equal to the reference model's order value are incremented by 1, then the current model is assigned the reference model's order value and saved.

```APIDOC
## moveBefore(Sortable $model): void

### Description
Moves the current model to the position immediately before the given reference model. All records in the sort scope whose order value is greater than or equal to the reference model's order value are incremented by 1, then the current model is assigned the reference model's order value and saved via save().

### Method
moveBefore

### Signature
public function moveBefore(Sortable $model): void

### Parameters
- **$model** (Sortable) - Required - The reference model this instance should be positioned before.

### Return Type
void

### Example
```php
$anchor = MyModel::find(4);
$newModel = MyModel::create(['name' => 'New']);
$newModel->moveBefore($anchor); // $newModel now sits directly before $anchor
```
```

--------------------------------

### moveAfter()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Moves the current model to the position immediately after the given model. Increments order values of records after the reference model and assigns the new position.

```APIDOC
## moveAfter()

### Description
Moves the current model to the position immediately after `$model`. All records in the sort scope whose order value is greater than `$model`'s order value are incremented by 1, then the current model is assigned `$model`'s order value + 1 and saved via `save()` (which fires normal Eloquent model events — changed in v5.0.0 from the previously used `saveQuietly()`).

### Method
moveAfter

### Signature
`public function moveAfter(Sortable $model): void`

### Parameters
#### Parameters
- **$model** (Sortable) - Required - The reference model this instance should be positioned after.

### Return Type
`void`

### Example
```php
$anchor = MyModel::find(3);
$newModel = MyModel::create(['name' => 'New']);
$newModel->moveAfter($anchor); // $newModel now sits directly after $anchor
```
```

--------------------------------

### Sortable interface declaration

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-interface.md

The exact interface declaration from src/Sortable.php, defining the methods that must be implemented: setHighestOrderNumber, scopeOrdered, setNewOrder, and shouldSortWhenCreating.

```php
interface Sortable
{
    /**
     * Modify the order column value.
     */
    public function setHighestOrderNumber(): void;

    /**
     * Let's be nice and provide an ordered scope.
     *
     * @param \Illuminate\Database\Eloquent\Builder $query
     *
     * @return \Illuminate\Database\Query\Builder
     */
    public function scopeOrdered(Builder $query);

    /**
     * This function reorders the records: the record with the first id in the array
     * will get order 1, the record with the second it will get order 2,...
     *
     * @param array|\ArrayAccess $ids
     * @param int $startOrder
     */
    public static function setNewOrder($ids, int $startOrder = 1): void;

    /**
     * Determine if the order column should be set when saving a new model instance.
     */
    public function shouldSortWhenCreating(): bool;
}
```

--------------------------------

### moveToEnd()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Instance method that moves the current model to the last position in the sort scope, shifting intermediate records down by one.

```APIDOC
## `moveToEnd()`

### Description
Moves the current model to the last position in the sort scope. If the model already holds the maximum order value, it is returned unchanged. Otherwise the model is assigned the maximum order value and saved, and every record between the old and new position is decremented by 1.

### Method
`moveToEnd`

### Signature
```php
public function moveToEnd(): static
```

### Parameters
None.

### Return Type
`static` — returns `$this` (fluent).

### Example
```php
$model = MyModel::find(3);
$model = $model->moveToEnd();
echo $model->order_column; // now equals the previous maximum order value
```
```

--------------------------------

### EloquentModelSortedEvent constructor signature

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-model-sorted-event.md

The constructor signature for EloquentModelSortedEvent. It accepts a string $model parameter representing the fully-qualified class name of the sorted model.

```php
public function __construct(string $model)
```

--------------------------------

### EloquentModelSortedEvent isFor() signature

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-model-sorted-event.md

The signature of the isFor() method. It accepts either a Model instance or a string class name and returns a boolean indicating whether the event concerns the given model.

```php
public function isFor(Model|string $model): bool
```

--------------------------------

### Register EloquentSortableServiceProvider in Laravel 5.5 and above

Source: https://github.com/spatie/eloquent-sortable/blob/main/README.md

In Laravel 5.5 and above the service provider is registered automatically. In older versions, add this provider to the 'providers' array in config/app.php.

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

--------------------------------

### Propagation from setNewOrderByCustomColumn()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/errors.md

Demonstrates that setNewOrderByCustomColumn() delegates directly to setNewOrder(), propagating the same InvalidArgumentException unchanged. The exception message is identical.

```php
MyModel::setNewOrderByCustomColumn('uuid', 'invalid'); // throws the same InvalidArgumentException
```

--------------------------------

### EloquentModelSortedEvent class declaration

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-model-sorted-event.md

The full class declaration of EloquentModelSortedEvent, including the public $model property, the constructor, and the isFor() method. This is the exact source from src/EloquentModelSortedEvent.php:7-24.

```php
class EloquentModelSortedEvent
{
    public string $model;

    public function __construct(string $model)
    {
        $this->model = $model;
    }

    public function isFor(Model|string $model): bool
    {
        if (is_string($model)) {
            return $model === $this->model;
        }

        return get_class($model) === $this->model;
    }
}
```

--------------------------------

### EloquentModelSortedEvent::isFor

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-model-sorted-event.md

Checks whether the event concerns a given model. Accepts either a model instance or a class name and performs an exact class match.

```APIDOC
## EloquentModelSortedEvent::isFor

### Description
Determines if the event is for the specified model. If a string is provided, it is compared with strict equality against the event's model class. If a Model instance is provided, its class is compared with strict equality. Note that subclasses do not match.

### Method
Method

### Signature
```php
public function isFor(Model|string $model): bool
```

### Parameters
- **$model** (\Illuminate\Database\Eloquent\Model|string) - Required - Either a model instance or a class name to compare against.

### Return Type
bool - `true` if the argument matches the sorted model class, `false` otherwise.

### Source
`src/EloquentModelSortedEvent.php:16-23`

### Example
```php
use Spatie\EloquentSortable\EloquentModelSortedEvent as SortEvent;

class SortingListener
{
    public function handle(SortEvent $event): void
    {
        if ($event->isFor(MyModel::class)) {
            // e.g. flush a cache for MyModel
        }
    }
}
```
```

--------------------------------

### determineOrderColumnName()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Resolves the order column name for the model. It reads from the model's sortable configuration or falls back to a config value.

```APIDOC
## determineOrderColumnName()

### Description
Resolves the order column name: reads `$this->sortable['order_column_name']` if set, otherwise falls back to `config('eloquent-sortable.order_column_name', 'order_column')`.

### Method
PHP instance method

### Signature
```php
public function determineOrderColumnName(): string
```

### Parameters
None

### Return Type
string - The name of the order column.

### Example
```php
$model = new MyModel();
echo $model->determineOrderColumnName(); // 'order_column' (default)
```
```

--------------------------------

### Dispatch site of EloquentModelSortedEvent

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/eloquent-model-sorted-event.md

The dispatch site of the event in SortableTrait::setNewOrder(). It is dispatched after all update statements have run and, when ignore_timestamps is enabled, after the class is removed from the $ignoreTimestampsOn list.

```php
// src/SortableTrait.php:75
Event::dispatch(new EloquentModelSortedEvent(static::class));
```

--------------------------------

### Catch InvalidArgumentException in consumer code

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/errors.md

Shows how to catch the \InvalidArgumentException in consumer code. The exception message is exactly 'You must pass an array or ArrayAccess object to setNewOrder'.

```php
use Spatie\EloquentSortable\Sortable;
use Spatie\EloquentSortable\SortableTrait;

try {
    MyModel::setNewOrder($ids);
} catch (\InvalidArgumentException $e) {
    // $e->getMessage() === 'You must pass an array or ArrayAccess object to setNewOrder'
    report($e); // or re-throw / handle
}
```

--------------------------------

### isFirstInOrder()

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Determines whether the current model is the first record in the sort scope. Returns true when the model's order value equals getLowestOrderNumber().

```APIDOC
## isFirstInOrder()

### Description
Determines whether the current model is the first record in the sort scope. Returns `true` when the model's order value equals `getLowestOrderNumber()`.

### Method
`isFirstInOrder()`

### Signature
```php
public function isFirstInOrder(): bool
```

### Parameters
None.

### Return Type
`bool` — `true` when the model's order value equals `getLowestOrderNumber()`.

### Example
```php
$first = MyModel::ordered()->first();
if ($first->isFirstInOrder()) {
    // handle first-position logic
}
```
```

--------------------------------

### setNewOrder() throws InvalidArgumentException for invalid $ids

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/errors.md

Shows the exact source code of the setNewOrder() method in src/SortableTrait.php (lines 44-61), which throws an \InvalidArgumentException when $ids is not an array or ArrayAccess instance. The message is 'You must pass an array or ArrayAccess object to setNewOrder'.

```php
public static function setNewOrder(
    $ids,
    int $startOrder = 1,
    ?string $primaryKeyColumn = null,
    ?callable $modifyQuery = null
): void {
    if (! is_array($ids) && ! $ids instanceof ArrayAccess) {
        throw new InvalidArgumentException('You must pass an array or ArrayAccess object to setNewOrder');
    }
    // ...
}
```

--------------------------------

### Disable auto-sort per model

Source: https://github.com/spatie/eloquent-sortable/blob/main/_autodocs/configuration.md

Disables auto-sorting for a model by setting sort_when_creating to false, leaving the order column for the developer to set manually.

```php
class ManualOrderModel extends Model implements Sortable
{
    use SortableTrait;

    public $sortable = [
        'sort_when_creating' => false, // order column is left for the developer to set
    ];
}
```
Tokens:
Raw