order-records.md

Order Records

• Usage
  • Order Records
  • Fetch Records In Order
  • Move Up
  • Move Down
  • Move To Start
  • Move To End
  • Swap Order
• Customizations
  • Change Order Column
  • Disable Order When Creating
• Implementation Example

This functionality allows you to order model records between them.

Usage

Your models should use the Varbox\Traits\IsOrderable trait and the Varbox\Options\OrderOptions class.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Varbox\Options\OrderOptions;
use Varbox\Traits\IsOrderable;

class YourModel extends Model
{
    use IsOrderable;

    /**
     * Get the options for ordering the model.
     *
     * @return OrderOptions
     */
    public function getOrderOptions(): OrderOptions
    {
        return OrderOptions::instance();
    }
}

Next you should create an ord table column for your model table.
This column will be responsible for storing the model record's order number.

Schema::table('your_table', function (Blueprint $table) {
    $table->unsignedInteger('ord')->default(0);
});

Order Records

An easy method to order all you records is to use the setNewOrder() method.

This method accepts an array of model ids and will set the order incrementally starting from the first array value to the last. In other words, the order will be established based on the array you pass.

$items = YourModel::latest()->get();
$array = $items->pluck('id')->toArray();

YourModel::setNewOrder(array_values($array));

Fetch Records In Order

You can fetch model records in the order you established by using the ordered query scope.

$items = YourModel::ordered()->get();

Move Up

You can swap the order of your model with model above it by using the moveOrderUp() method.

$model = YourModel::find($id);

$model->moveOrderUp();

Move Down

You can swap the order of your model with model below it by using the moveOrderDown() method.

$model = YourModel::find($id);

$model->moveOrderDown();

Move To Start

You can set a certain model to be at the first position by using the moveToStart() method.

$model = YourModel::find($id);

$model->moveToStart();

Move To End

You can set a certain model to be at the last position by using the moveToEnd() method.

$model = YourModel::find($id);

$model->moveToEnd();

Swap Order

You can swap the order of two models by using the swapOrder() method.

$model1 = YourModel::find($id);
$model2 = YourModel::find($id);

$model2->swapOrderWithModel($model1);

// or the static call version

YourModel::swapOrder($model2, $model1);

Customizations

The order functionality offers a variety of customizations to fit your needs.

Change Order Column

By default, the ordering functionality works based on a ord table column.

You can change the name of that column by using the setOrderColumn() method in your definition of the getOrderOptions() method.

/**
 * Set the options for the IsOrderable trait.
 *
 * @return OrderOptions
 */
public function getOrderOptions(): OrderOptions
{
    return OrderOptions::instance()
        ->setOrderColumn('position');
}

Disable Order When Creating

By default, when creating a new model record, the ord value for it will be the highest, thus making it last in order.

You can disable this behavior by using the doNotOrderWhenCreating() method in your definition of the getOrderOptions() method.

Please note that by doing so the value of the ord column will be the default one.

/**
 * Set the options for the IsOrderable trait.
 *
 * @return OrderOptions
 */
public function getOrderOptions(): OrderOptions
{
    return OrderOptions::instance()
        ->doNotOrderWhenCreating();
}

Implementation Example

For an implementation example of this functionality please refer to the Full Example page.