This extension provides support for ActiveRecord custom records order setup.

For license information check the LICENSE-file.

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist yii2tech/ar-position

or add

"yii2tech/ar-position": "*"

to the require section of your composer.json.

This extension provides support for custom records order setup via column-based position index.

This extension provides [[\yii2tech\ar\position\PositionBehavior]] ActiveRecord behavior for such solution support in Yii2. You may attach it to your model class in the following way:

class Item extends ActiveRecord
{
    public function behaviors()
    {
        return [
            'positionBehavior' => [
                'class' => PositionBehavior::className(),
                'positionAttribute' => 'position',
            ],
        ];
    }
}

Behavior uses the specific integer field of the database entity to set up position index. Due to this the database entity, which the model refers to, must contain field [[positionAttribute]].

In order to display custom list in correct order you should sort it by [[positionAttribute]] in ascending mode:

$records = Item::find()->orderBy(['position' => SORT_ASC])->all();
foreach ($records as $record) {
    echo $record->position . ', ';
}
// outputs: 1, 2, 3, 4, 5,...

Being attached, behavior automatically fills up positionAttribute value fro the new record, placing it to the end of the list:

echo Item::find()->count(); // outputs: 4

$item = new Item();
$item->save();

echo $item->position // outputs: 5

However, you may setup position for the new record explicitly:

echo Item::find()->count(); // outputs: 4

$item = new Item();
$item->position = 2; // enforce position '2'
$item->save();

echo $item->position // outputs: 2 !!!

Existing record can be moved to another position using following methods:

• [[movePrev()]] - moves record by one position towards the start of the list.
• [[moveNext()]] - moves record by one position towards the end of the list.
• [[moveFirst()]] - moves record to the start of the list.
• [[moveLast()]] - moves record to the end of the list.
• [[moveToPosition()]] - moves owner record to the specific position.

You may as well change record position through the attribute, provided to positionAttribute directly:

$item = Item::find()->andWhere(['position' => 3])->one();
$item->position = 5; // switch position to '5'
$item->save();

Sometimes single database entity contains several listings, which require custom ordering, separated logically by grouping attributes. For example: FAQ questions may be grouped by categories, while inside single category questions should be ordered manually. For this case [[\yii2tech\ar\position\PositionBehavior::$groupAttributes]] can be used:

class FaqQuestion extends ActiveRecord
{
    public function behaviors()
    {
        return [
            'positionBehavior' => [
                'class' => PositionBehavior::className(),
                'positionAttribute' => 'position',
                'groupAttributes' => [
                    'categoryId' // multiple lists varying by 'categoryId'
                ],
            ],
        ];
    }
}

In this case behavior will use owner values of groupAttributes as additional condition for position calculation and changing:

echo FaqQuestion::find()->andWhere(['categoryId' => 1])->count(); // outputs: '4'
echo FaqQuestion::find()->andWhere(['categoryId' => 2])->count(); // outputs: '7'

$record = new FaqQuestion();
$record->categoryId = 1;
$record->save();
echo $record->position // outputs: '5'

$record = new FaqQuestion();
$record->categoryId = 2;
$record->save();
echo $record->position // outputs: '8'

Records with custom position order applied make a chained list, which you may navigate if necessary. You may use [[\yii2tech\ar\position\PositionBehavior::getIsFirst()]] and [[\yii2tech\ar\position\PositionBehavior::getIsLast()]] methods to determine if particular record is the first or last one in the list. For example:

echo Item::find()->count(); // outputs: 10

$firstItem = Item::find()->andWhere(['position' => 1])->one();
echo $firstItem->getIsFirst(); // outputs: true
echo $firstItem->getIsLast(); // outputs: false

$lastItem = Item::find()->andWhere(['position' => 10])->one();
echo $lastItem->getIsFirst(); // outputs: false
echo $lastItem->getIsLast(); // outputs: true

Having a particular record instance, you can always find record, which is located at next or previous position to it, using [[\yii2tech\ar\position\PositionBehavior::getNext()]] or [[\yii2tech\ar\position\PositionBehavior::getPrev()]] method. For example:

$item = Item::find()->andWhere(['position' => 5])->one();

$nextItem = $item->findNext();
echo $nextItem->position; // outputs: 6

$prevItem = $item->findPrev();
echo $prevItem->position; // outputs: 4

You may as well get the first and the last records in the list. For example:

echo Item::find()->count(); // outputs: 10
$item = Item::find()->andWhere(['position' => 5])->one();

$firstItem = $item->findFirst();
echo $firstItem->position; // outputs: 1

$lastItem = $item->findLast();
echo $lastItem->position; // outputs: 10