baril / orderly
Orderable/sortable behavior for Eloquent models.
Installs: 18 355
Dependents: 1
Suggesters: 1
Security: 0
Stars: 2
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- illuminate/cache: ^8.0|^9.0|^10.0|^11.0
- illuminate/console: ^8.0|^9.0|^10.0|^11.0
- illuminate/database: ^8.0|^9.0|^10.0|^11.0
- illuminate/support: ^8.0|^9.0|^10.0|^11.0
Requires (Dev)
- laravel/legacy-factories: ^1.3.2
- orchestra/testbench: ^6.23|^7.0|^8.0|^9.0
- squizlabs/php_codesniffer: ^2.8
This package is auto-updated.
Last update: 2024-10-21 17:40:46 UTC
README
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:
return [ // ... 'providers' => [ Baril\Orderly\OrderlyServiceProvider::class, // ... ], ];
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).
public function up() { Schema::create('articles', function (Blueprint $table) { // ... other fields ... $table->unsignedInteger('position'); }); }
Then, use the \Baril\Orderly\Concerns\Orderable
trait in your model. The
position
field should be guarded as it won't be filled manually.
class Article extends Model { use \Baril\Orderly\Concerns\Orderable; protected $guarded = ['position']; }
You also need to set the $orderColumn
property if you want to use another
name than position
:
class Article extends Model { use \Baril\Orderly\Concerns\Orderable; protected $orderColumn = 'order'; protected $guarded = ['order']; }
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 tofalse
, the model will simply be moved to the first or last position, else it will throw aPositionException
),moveDown($positions = 1, $strict = true)
,swapWith($anotherModel)
,moveBefore($anotherModel)
,moveAfter($anotherModel)
.
$model = Article::find(1); $anotherModel = Article::find(10) $model->moveAfter($anotherModel); // $model is now positioned after $anotherModel, and both have been saved
Also, this trait:
- automatically defines the model position on the
create
event, so you don't need to setposition
manually, - automatically decreases the position of subsequent models on the
delete
event so that there's no "gap".
$article = new Article(); $article->title = $request->input('title'); $article->body = $request->input('body'); $article->save();
This model will be positioned at MAX(position) + 1
.
To get ordered models, use the ordered
scope:
$articles = Article::ordered()->get(); $articles = Article::ordered('desc')->get();
(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:
$entity = Article::find(10); $entity->next(10); // returns a QueryBuilder on the next 10 entities, ordered $entity->previous(5)->get(); // returns a collection with the previous 5 entities, in reverse order $entity->next()->first(); // returns the next entity
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:
$models = Article::orderBy('publication_date', 'desc')->get(); $models->map(function($model, $key) { return $model->moveToOffset($key); });
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:
$collection = Article::orderBy('publication_date', 'desc')->get(); $collection->map(function($model, $key) { return $model->fresh()->moveToOffset($key); });
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:
$collection = Article::orderBy('publication_date', 'desc')->get(); // $collection is not a regular Eloquent collection object, it's a custom class // with the following additional method: $collection->saveOrder();
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:
$ordered = $collection->setOrder([4, 5, 2]);
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
).
⚠️ 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.
// This will reorder all statuses (assuming there are 5 statuses in the table): Status::setOrder([2, 1, 5, 3, 4]); // This will put the status with id 4 at the beginning, and move the other // statuses' positions accordingly: Status::setOrder([4]); // This will only swap the statuses 3, 4 and 5, and won't change the position // of the other statuses: Status::whereKey([3, 4, 5])->setOrder([4, 5, 3]);
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:
class Article extends Model { use \Baril\Orderly\Concerns\Orderable; protected $guarded = ['position']; protected $groupColumn = 'section_id'; }
If the group is defined by multiple columns, you can use an array:
protected $groupColumn = ['field_name1', 'field_name2'];
Orderable groups can be used to handle orderable one-to-many relationships:
class Section extends Model { public function articles() { return $this->hasMany(Article::class)->ordered(); // Chaining the ->ordered() method is optional here, but you can do // it if you want the relation ordered by default. } } class Article extends Model { protected $groupColumn = 'section_id'; }
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:
class Post extends Model { use \Baril\Orderly\Concerns\HasOrderableRelationships; public function tags() { return $this->belongsToManyOrderable(Tag::class); } }
The prototype of the belongsToManyOrderable
method is similar as
belongsToMany
with an added 2nd parameter $orderColumn
:
public function belongsToManyOrderable( $related, $orderColumn = 'position', $table = null, $foreignPivotKey = null, $relatedPivotKey = null, $parentKey = null, $relatedKey = null, $relation = null)
Now all the usual methods from the BelongsToMany
class will set the proper
position to attached models:
$post->tags()->attach($tag->id); // will attach $tag and give it the last position $post->tags()->sync([$tag1->id, $tag2->id, $tag3->id]) // will keep the provided order $post->tags()->detach($tag->id); // will decrement the position of subsequent $tags
You can order the results of the relation by chaining the ordered
method:
$orderedTags = $post->tags()->ordered()->get(); $tagsInReverseOrder = $post->tags()->ordered('desc')->get();
If you want the relation ordered by default, you can use the
belongsToManyOrdered
method in the relation definition, instead of
belongsToManyOrderable
.
class Post extends Model { use \Baril\Orderly\Concerns\HasOrderableRelationships; public function tags() { return $this->belongsToManyOrdered(Tag::class); // the line above is actually just a shortcut to: // return $this->belongsToManyOrderable(Tag::class)->ordered(); } }
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:
$post->tags; // ordered by position, because of the definition above $post->tags()->ordered('desc')->get(); // reverse order $post->tags()->unordered()->get(); // unordered // Note that orderBy has no effect here since the tags are already ordered by position: $post->tags()->orderBy('id')->get(); // This is the proper way to do it: $post->tags()->unordered()->orderBy('id')->get();
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 theprevious
method from theOrderable
trait),after($model)
(similar asnext
).
$tag1 = $article->tags()->ordered()->first(); $tag2 = $article->tags()->ordered()->last(); $article->tags()->moveBefore($tag1, $tag2); // now $tag1 is at the second to last position
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:
$article->tags()->setOrder([$id1, $id2, $id3]);
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
):
class Post extends Model { use \Baril\Orderly\Concerns\HasOrderableRelationships; public function tags() { return $this->morphToManyOrderable('App\Tag', 'taggable', 'tag_order'); } }
Same thing with the morphedByManyOrderable
method:
class Tag extends Model { use \Baril\Orderable\Concerns\HasOrderableRelationships; public function posts() { return $this->morphedByManyOrderable('App\Post', 'taggable', 'order'); } public function videos() { return $this->morphedByManyOrderable('App\Video', 'taggable', 'order'); } }
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:
php artisan orderly:fix-positions "App\\YourModel"
For an orderable many-to-many relation:
php artisan orderly:fix-positions "App\\YourModel" relationName