Download the PHP package baril/orderly without Composer

Orderly

This package adds an orderable/sortable behavior to Eloquent models. It is inspired by the rutorika/sortable package. It was originally part of the Smoothie package.

Version compatibility

Setup

New install

If you're not using package discovery, register the service provider in your config/app.php file:

Add a column to your table to store the position. The default name for this column is position but you can use another name if you want (see below).

Then, use the \Baril\Orderly\Concerns\Orderable trait in your model. The position field should be guarded as it won't be filled manually.

You also need to set the $orderColumn property if you want to use another name than position:

Basic usage

You can use the following method to change the model's position (no need to save it afterwards, the method does it already):

• moveToOffset($offset) ($offset starts at 0 and can be negative, ie. $offset = -1 is the last position),
• moveToStart(),
• moveToEnd(),
• moveToPosition($position) ($position starts at 1 and must be a valid position),
• moveUp($positions = 1, $strict = true): moves the model up by $positions positions (the $strict parameter controls what happens if you try to move the model "out of bounds": if set to false, the model will simply be moved to the first or last position, else it will throw a PositionException),
• moveDown($positions = 1, $strict = true),
• swapWith($anotherModel),
• moveBefore($anotherModel),
• moveAfter($anotherModel).

Also, this trait:

• automatically defines the model position on the create event, so you don't need to set position manually,
• automatically decreases the position of subsequent models on the delete event so that there's no "gap".

This model will be positioned at MAX(position) + 1.

To get ordered models, use the ordered scope:

(You can cancel the effect of this scope by calling the unordered scope.)

Previous and next models can be queried using the previous and next methods:

Mass reordering

The move* methods described above are not appropriate for mass reordering because:

• they would perform many unneeded queries,
• changing a model's position affects other model's positions as well, and can cause side effects if you're not careful.

Example:

The sample code above will corrupt the data because you need each model to be "fresh" before you change its position. The following code, on the other hand, will work properly:

It's still not a good way to do it though, because it performs many unneeded queries. A better way to handle mass reordering is to use the saveOrder method on a collection:

That's it! Now the items' order in the collection has been applied to the position column of the database.

You can also order a collection explicitely with the setOrder method. It takes an array of ids as a parameter:

The returned collection is ordered so that the items with ids 4, 5 and 2 are at the beginning of the collection. Also, the new order is saved to the database automatically (you don't need to call saveOrder).

:warning: Note: Only the models within the collection are reordered / swapped between one another. The other rows in the table remain untouched.

You can also use the setOrder method, either statically on the model, or on a query builder.

When used like this, the setOrder method returns the number of affected rows.

Orderable groups / one-to-many relationships

Sometimes, the table's data is "grouped" by some column, and you need to order each group individually instead of having a global order. To achieve this, you just need to set the $groupColumn property:

If the group is defined by multiple columns, you can use an array:

Orderable groups can be used to handle orderable one-to-many relationships:

Orderable many-to-many relationships

If you need to order a many-to-many relationship, you will need a position column (or some other name) in the pivot table.

Have your model use the \Baril\Orderly\Concerns\HasOrderableRelationships trait:

The prototype of the belongsToManyOrderable method is similar as belongsToMany with an added 2nd parameter $orderColumn:

Now all the usual methods from the BelongsToMany class will set the proper position to attached models:

You can order the results of the relation by chaining the ordered method:

If you want the relation ordered by default, you can use the belongsToManyOrdered method in the relation definition, instead of belongsToManyOrderable.

In this case, if you occasionally want to order the related models by some other field, you will need to use the unordered scope first:

The BelongsToManyOrderable class has all the same methods as the Orderable trait, except that you will need to pass them a related $model to work with:

• moveToOffset($model, $offset),
• moveToStart($model),
• moveToEnd($model),
• moveToPosition($model, $position),
• moveUp($model, $positions = 1, $strict = true),
• moveDown($model, $positions = 1, $strict = true),
• swap($model, $anotherModel),
• moveBefore($model, $anotherModel) ($model will be moved before $anotherModel),
• moveAfter($model, $anotherModel) ($model will be moved after $anotherModel),
• before($model) (similar as the previous method from the Orderable trait),
• after($model) (similar as next).

Note that if $model doesn't belong to the relationship, any of these methods will throw a Baril\Orderly\GroupException.

There's also a method for mass reordering:

In the example above, tags with ids $id1, $id2, $id3 will now be at the beginning of the article's tags collection. Any other tags attached to the article will come after, in the same order as before calling setOrder.

Orderable morph-to-many relationships

Similarly, the package defines a MorphToManyOrderable type of relationship. The 3rd parameter of the morphToManyOrderable method is the name of the order column (defaults to position):

Same thing with the morphedByManyOrderable method:

Artisan command

The orderly:fix-positions command will recalculate the data in the position column (eg. in case you've manually deleted rows and have "gaps").

For an orderable model:

For an orderable many-to-many relation: