Download the PHP package spatie/eloquent-sortable without Composer

Sortable behaviour for Eloquent models

This package provides a trait that adds sortable behaviour to an Eloquent model.

The value of the order column of a new record of a model is determined by the maximum value of the order column of all records of that model + 1.

The package also provides a query scope to fetch all the records in the right order.

Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

Support us

Learn how to create a package like this one, by watching our premium video course:

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

For Laravel 6.x or PHP 7.x, use version 3.x of this package.

This package can be installed through Composer.

In Laravel 5.5 and above the service provider will automatically get registered. In older versions of the framework just add the service provider in config/app.php file:

Optionally you can publish the config file with:

This is the content of the file that will be published in config/eloquent-sortable.php

Usage

To add sortable behaviour to your model you must:

1. Implement the Spatie\EloquentSortable\Sortable interface.
2. Use the trait Spatie\EloquentSortable\SortableTrait.
3. Optionally specify which column will be used as the order column. The default is order_column.

Example

If you don't set a value $sortable['order_column_name'] the package will assume that your order column name will be named order_column.

If you don't set a value $sortable['sort_when_creating'] the package will automatically assign the highest order number to a new model;

Assuming that the db-table for MyModel is empty:

You can set a new order for all the records using the setNewOrder-method

Optionally you can pass the starting order number as the second argument.

You can modify the query that will be executed by passing a closure as the fourth argument.

To sort using a column other than the primary key, use the setNewOrderByCustomColumn-method.

As with setNewOrder, setNewOrderByCustomColumn will also accept an optional starting order argument.

You can also move a model up or down with these methods:

You can also move a model to the first or last position:

You can determine whether an element is first or last in order:

You can swap the order of two models:

Grouping

If your model/table has a grouping field (usually a foreign key): id,user_id, title, order_column and you'd like the above methods to take it into considerations, you can create a buildSortQuery method at your model:

This will restrict the calculations to fields value of the model instance.

Dispatched events

Once a sort has been completed, an event (Spatie\EloquentSortable\EloquentModelSortedEvent) is dispatched that you can listen for. This can be useful for running post-sorting logic such as clearing caches or other actions that need to be taken after a sort.

The event has an isFor helper which allows you to conveniently check the Eloquent class that has been sorted.

Below is an example of how you can listen for this event:

Tests

The package contains some integration/smoke tests, set up with Orchestra. The tests can be run via phpunit.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Freek Van der Herten
• All Contributors

Alternatives

• Listify
• Rutorike-sortable

License

The MIT License (MIT). Please see License File for more information.