johankladder/eloquent-sortable

Sortable behaviour for eloquent models

Sortable behaviour for Eloquent models

, _(*1)

This package provides a trait that adds sortable behaviour to an Eloquent model., _(*2)

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., _(*3)

The package also provides a query scope to fetch all the records in the right order., _(*4)

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

Installation

This package can be installed through Composer., _(*6)

$ composer require spatie/eloquent-sortable

Usage

To add sortable behaviour to your model you must:
1. specify that the model will conform to Spatie\EloquentSortable\Sortable
2. use the trait Spatie\EloquentSortable\SortableTrait
3. specify which column will be used as the order column
, _(*7)

Example

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

class MyModel extends Eloquent implements Sortable
{

    use SortableTrait;

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

    ...
}

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., _(*8)

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

If you don't set a value $sortable['sort_by_group_column'] the package will automatically order by table order. If you specify this value it will sort only the rows which are set as column in the same table;, _(*10)

Assuming that the db-table for MyModel is empty:, _(*11)

$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


//the trait also provides the ordered query scope
$orderedRecords = MyModel::ordered()->get();

You can set a new order for all the records using the setNewOrder-method, _(*12)

/**
 * the record for model id 3 will have record_column value 1
 * the record for model id 1 will have record_column value 2
 * the record for model id 2 will have record_column value 3
 */
MyModel::setNewOrder([3,1,2]);

Optionally you can pass the starting order number as the second argument., _(*13)

/**
 * the record for model id 3 will have record_column value 11
 * the record for model id 1 will have record_column value 12
 * the record for model id 2 will have record_column value 13
 */
MyModel::setNewOrder([3,1,2], 10);

You can also move a model up or down with these methods:, _(*14)

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

You can also move a model to the first or last position:, _(*15)

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

You can swap the order of two models:, _(*16)

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

Tests

The package contains some integration/smoke tests, set up with Orchestra. The tests can be run via phpunit., _(*17)

$ vendor/bin/phpunit

Changelog

Please see CHANGELOG for more information on what has changed recently., _(*18)

Contributing

Please see CONTRIBUTING for details., _(*19)

Security

If you discover any security related issues, please email freek@spatie.be instead of using the issue tracker., _(*20)

Postcardware

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using., _(*21)

Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium., _(*22)

We publish all received postcards on our company website., _(*23)

Credits

• Freek Van der Herten
• All Contributors

Alternatives

• Listify
• Rutorike-sortable

Support us

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

Does your business depend on our contributions? Reach out and support us on Patreon. All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff., _(*25)

License

The MIT License (MIT). Please see License File for more information., _(*26)