Feature Position Lock (#21)

Rework position lock

* Update README.md

Author: xalaida

README.md

@@ -81,7 +81,7 @@ public function getStartPosition(): int
 }
 ```
 
-By doing this, the first record will be assigned a position value of `1`.
+In this example, the first record will be assigned a position value of `1`.
 
 #### Ordering
 
@@ -177,18 +177,6 @@ The `swap` method swaps the position of two models. For example:
 $category->swap($anotherCategory);
 ```
 
-#### Without shifting
-
-By default, the positions of other models are automatically shifted when the model position is updated.
-
-If you want to change the model position without shifting the position of other models, you can use the `withoutShiftingPosition` method. For example:
-
-```php
-Category::withoutShiftingPosition(function () {
-    $category->move(5);
-})
-```
-
 #### Arrange models
 
 It is also possible to arrange models by their IDs.
@@ -214,50 +202,20 @@ public function groupPositionBy(): array
 }
 ```
 
-### Locking positions
+### Position lock
 
-By default, when a model is created at the end of the sequence, an extra database query is executed to calculate the latest position in the sequence. 
-Similarly, when a model is created at the beginning or any other position but the latest, additional database queries are needed to shift the positions of other models accordingly. 
-In some cases, you may want to insert models without these additional queries associated with calculating and shifting positions.
-For such scenarios, you can use the `lockPositions` method, which disables all post-insert database queries and assigns positions to models using a specified locker. 
-This can be particularly useful to speed up your tests.
-
-By default, the positions are locked to the value returned by the `getStartPosition` method in your model:
+By default, when you change the position or group of a model, the `PositionObserver` automatically updates the positions of other models in the sequence by performing additional database queries. If you need to disable this behavior for any reason, you can do it like so:
 
 ```php
-Categogy::lockPositions();
+use Nevadskiy\Position\PositionObserver;
 
-$category = Category::create();
-echo $category->position; // 0
+PositionObserver::lockFor(Category::class);
 
-$category = Category::create();
-echo $category->position; // 0
+$category->update(['position' => 1]);
 
-$category = Category::create();
-echo $category->position; // 0
+PositionObserver::unlockFor(Category::class);
 ```
 
-Alternatively, you can provide a callback function as the locker. For example:
-
-```php
-Category::lockPositions(static function () {
-    static $count = 0;
-
-    return $count++;
-});
-
-$category = Category::create();
-echo $category->position; // 0
-
-$category = Category::create();
-echo $category->position; // 1
-
-$category = Category::create();
-echo $category->position; // 2
-```
-
-In this example, the callback function is used to increment the position for each new model created, starting from `0`.
-
 ## 📑 Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
@@ -273,3 +231,7 @@ If you discover any security related issues, please [e-mail me](mailto:nevadskiy
 ## 📜 License
 
 The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.
+
+## 🛠️ Todo List
+
+- [ ] support `swap` for models from different groups

src/HasPosition.php

@@ -10,15 +10,6 @@
  */
 trait HasPosition
 {
-    use PositionLocker;
-
-    /**
-     * Indicates if the model should shift position of other models in the sequence.
-     *
-     * @var bool
-     */
-    protected static $shiftPosition = true;
-
     /**
      * Indicates if the model was positioned at the end of the sequence during the current request lifecycle.
      *
@@ -113,23 +104,25 @@ public function scopeOrderByReversePosition(Builder $query): Builder
     /**
      * Move the model to the new position.
      */
-    public function move(int $newPosition): bool
+    public function move(int $position): bool
     {
-        $oldPosition = $this->getPosition();
+        $originalPosition = $this->getPosition();
 
-        if ($oldPosition === $newPosition) {
+        if ($originalPosition === $position) {
             return false;
         }
 
-        return $this->setPosition($newPosition)->save();
+        $this->setPosition($position);
+
+        return $this->save();
     }
 
     /**
      * Swap the model position with another model.
      */
     public function swap(self $that): void
     {
-        static::withoutShiftingPosition(function () use ($that) {
+        static::withPositionLock(function () use ($that) {
             $thisPosition = $this->getPosition();
             $thatPosition = $that->getPosition();
 
@@ -178,26 +171,22 @@ public function newOriginalPositionQuery(): Builder
     }
 
     /**
-     * Execute a callback without shifting positions of models.
+     * Execute the callback with the position lock.
+     *
+     * @template TValue
+     * @param callable(): TValue $callback
+     * @return TValue
      */
-    public static function withoutShiftingPosition(callable $callback)
+    public static function withPositionLock(callable $callback)
     {
-        $shiftPosition = static::$shiftPosition;
-
-        static::$shiftPosition = false;
-
-        $result = $callback();
-
-        static::$shiftPosition = $shiftPosition;
-
-        return $result;
+        return PositionObserver::withLockFor(static::class, $callback);
     }
 
     /**
-     * Determine if the model should shift positions of other models in the sequence.
+     * Force the next position for the model.
      */
-    public static function shouldShiftPosition(): bool
+    public static function forcePosition(?int $position): void
     {
-        return static::$shiftPosition && is_null(static::$positionLocker);
+        PositionObserver::forceFor(static::class, $position);
     }
 }

src/PositionLocker.php

@@ -6,6 +6,83 @@
 
 class PositionObserver
 {
+    /**
+     * The list of models classes that should lock position.
+     *
+     * @var array
+     */
+    protected static $lockFor = [];
+
+    /**
+     * The list of models classes that should force position.
+     *
+     * @var array
+     */
+    protected static $forceFor = [];
+
+    /**
+     * Enable the position lock for the given model.
+     */
+    public static function lockFor(string $model): void
+    {
+        static::$lockFor[$model] = true;
+    }
+
+    /**
+     * Disable the position lock for the given model.
+     */
+    public static function unlockFor(string $model): void
+    {
+        unset(static::$lockFor[$model]);
+    }
+
+    /**
+     * Determine whether the position is locked for the given model.
+     *
+     * @param Model|string $model
+     */
+    public static function isLockedFor($model): bool
+    {
+        $model = is_object($model) ? get_class($model) : $model;
+
+        return isset(static::$lockFor[$model]);
+    }
+
+    /**
+     * Force the position for the given model.
+     */
+    public static function forceFor(string $model, ?int $position): void
+    {
+        static::$forceFor[$model] = $position;
+    }
+
+    /**
+     * Execute the callback with the position lock.
+     *
+     * @template TValue
+     * @param Model|string $model
+     * @param callable(): TValue $callback
+     * @return TValue
+     */
+    public static function withLockFor($model, callable $callback)
+    {
+        $model = is_object($model) ? get_class($model) : $model;
+
+        $isLocked = static::isLockedFor($model);
+
+        if (! $isLocked) {
+            static::lockFor($model);
+        }
+
+        $result = $callback();
+
+        if (! $isLocked) {
+            static::unlockFor($model);
+        }
+
+        return $result;
+    }
+
     /**
      * Handle the "saving" event for the model.
      *
@@ -14,7 +91,9 @@ class PositionObserver
     public function saving(Model $model): void
     {
         $this->assignPosition($model);
+
         $this->markAsTerminalPosition($model);
+
         $this->normalizePosition($model);
     }
 
@@ -51,33 +130,29 @@ protected function shouldSetPosition(Model $model): bool
     }
 
     /**
-     * Determine if the position group is changing for the model.
+     * Get the next position for the model.
      *
      * @param Model|HasPosition $model
      */
-    protected function isGroupChanging(Model $model): bool
+    protected function getNextPosition(Model $model): int
     {
-        $groupPositionColumns = $model->groupPositionBy();
-
-        if (! $groupPositionColumns) {
-            return false;
-        }
-
-        return $model->isDirty($groupPositionColumns);
+        return static::$forceFor[get_class($model)] ?? $model->getNextPosition();
     }
 
     /**
-     * Get the next position for the model.
+     * Determine if the position group is changing for the model.
      *
      * @param Model|HasPosition $model
      */
-    protected function getNextPosition(Model $model): int
+    protected function isGroupChanging(Model $model): bool
     {
-        if ($model::positionLocker()) {
-            return $model::positionLocker()($model);
+        $groupPositionColumns = $model->groupPositionBy();
+
+        if (! $groupPositionColumns) {
+            return false;
         }
 
-        return $model->getNextPosition();
+        return $model->isDirty($groupPositionColumns);
     }
 
     /**
@@ -117,7 +192,7 @@ protected function normalizePosition(Model $model): void
      */
     public function created(Model $model): void
     {
-        if (! $model::shouldShiftPosition()) {
+        if (static::isLockedFor($model)) {
             return;
         }
 
@@ -145,7 +220,7 @@ protected function handleAddToGroup(Model $model): void
      */
     public function updated(Model $model): void
     {
-        if (! $model::shouldShiftPosition()) {
+        if (static::isLockedFor($model)) {
             return;
         }
 
@@ -222,7 +297,7 @@ protected function handlePositionChange(Model $model): void
      */
     public function deleted(Model $model): void
     {
-        if (! $model::shouldShiftPosition()) {
+        if (static::isLockedFor($model)) {
             return;
         }