artistan/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)

Postcardware

You're free to use this package (it's MIT-licensed), but if it makes it to your production environment you are required to send us a postcard from your hometown, mentioning which of our package(s) you are using., _(*6)

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

The best postcards will get published on the open source page on our website., _(*8)

Installation

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

$ composer require Artistan/eloquent-sortable

Usage

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

Example

use Artistan\EloquentSortable\Sortable;
use Artistan\EloquentSortable\SortableTrait;

class MyModel extends Eloquent implements Sortable
{

    use SortableTrait;

    public $sortable = [
        'order_column_name' => 'order_column',
        'sort_when_creating' => true,
        /* 'order_unique' => ['another_key'], // optional additional keys for allowing multiple sorts in a table. */
    ];

    ...
}

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

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

If you don't set a value $sortable['order_unique'] the package will assume that your model will sort all values. If it is set, then sorting will be done with matching the key(s) provided., _(*13)

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

$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, _(*15)

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

/**
 * 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:, _(*17)

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

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

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

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

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

Tests

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

$ vendor/bin/phpunit

Changelog

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

Contributing

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

Security

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

Credits

• Freek Van der Herten
• All Contributors

Alternatives

• Listify
• Rutorike-sortable

About Spatie

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

License

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