README.md

Laravel Eloquent Sequencer

This package allows you to create and manage sequences for your Eloquent models.

Installation

Install the package via composer:

composer require gurgentil/laravel-eloquent-sequencer

Configuration

To publish the configuration file run:

php artisan vendor:publish --provider="Gurgentil\LaravelEloquentSequencer\LaravelEloquentSequencerServiceProvider"

Configuration parameters

You can change the default colum name, the initial value and the sequencing strategy in config/eloquentsequencer.php:

return [
    'column_name' => 'position',
    'initial_value' => 1,
    'strategy' => 'always',
];

The strategy configuration determines when sequencing should be triggered and accepts one of the following values: always, on_create, on_update or never.

Model configuration

The $sequenceable attribute specifies the sequence column name for the model:

protected static $sequenceable = 'order';

The relationship key(s) that will group the sequence items together:

protected static $sequenceableKeys = [
    'task_list_id',
];

In the example above, a task list has many tasks.

For polymorphic relationships specify both relationship keys:

protected static $sequenceableKeys = [
    'commentable_id',
    'commentable_type',
];

Usage

In the example below, a task list may have many tasks.

use Gurgentil\LaravelEloquentSequencer\Traits\Sequenceable;
use Illuminate\Database\Eloquent\Model;

class Task extends Model
{
    use Sequenceable;

    protected $fillable = [
        'position',
    ];
    
    protected static $sequenceableKeys = [
        'task_list_id',
    ];

    public function taskList()
    {
        return $this->belongsTo(TaskList::class);
    }
}

Create an object

Task::create([
    'position' => 1,
    'task_list_id' => 1,
]);

If no value is provided for the sequence attribute, the object will be placed at the end of the sequence.

Task::create(['task_list_id' => 1]);

Update and delete objects

The other items in the sequence will be rearranged to keep the sequence consistent.

$task->update(['position' => 4]);

$task->delete();

Get sequence value of an object

$value = $task->getSequenceValue();

Get sequence column name

$columnName = Task::getSequenceColumnName();

Disable automatic sequencing

$task->withoutSequencing()->update(['position' => 3]);

$task->withoutSequencing()->delete();

Scope query to order results by sequence value

$tasks = Task::sequenced()->get();

Artisan commands

Assign sequence values to all records that have their values set to null.

php artisan sequence:populate \\App\\Task

Flush all sequence values for a model.

php artisan sequence:flush \\App\\Task

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Gustavo Rorato Gentil
• Michael Slowik
• All Contributors

License

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

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.