Lexorank Sortable

https://github.com/alexcrawford/lexorank-sortable
Admin
A Laravel package that provides sortable behavior to Eloquent models using lexorank-style...
Tokens:37,575
Snippets:407
Trust Score:6.5
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Sync Method Example Usage

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/types.md

An example demonstrating the usage of the sync() method and its resulting output, showing which IDs were attached, detached, and updated.

```php
$result = $post->tags()->sync([1, 2, 3]);

// Result:
[
    'attached' => [2, 3],
    'detached' => [5, 6],
    'updated' => [],
]
```

--------------------------------

### Example Configuration for Multiple Models

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/service-provider.md

An example of how to configure multiple models for sorting, including both simple and many-to-many relation types, within the config/sortable.php file.

```php
'entities' => [
    'articles' => 'App\Models\Article',
    'posts' => [
        'entity' => 'App\Models\Post',
        'relation' => 'tags',
    ],
    'videos' => [
        'entity' => 'App\Models\Video',
        'relation' => 'categories',
    ],
],
```

--------------------------------

### Install LexoRank Sortable with Composer

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Install the package using Composer. Ensure your Laravel version is compatible with the sortable version.

```bash
composer require alexcrawford/lexorank-sortable
```

--------------------------------

### Sort Method Example Failure Response

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/types.md

An example of a failure response from the sort() method, illustrating the structure of errors and failed validation rules for specific fields.

```php
$response = [
    'success' => false,
    'errors' => [
        'id' => ['The id must exist in the selected table.'],
        'entityName' => ['The selected entityName is invalid.']
    ],
    'failed' => [
        'id' => ['exists'],
        'entityName' => ['in']
    ]
];
```

--------------------------------

### Example Usage of morphedBySortedMany

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/traits.md

Illustrates the inverse relationship setup using `morphedBySortedMany`. This example shows a `Tag` model defining relationships to `Post` and `Video` models, enabling retrieval of related posts or videos, ordered by their position.

```php
class Tag extends Model
{
    public function posts()
    {
        return $this->morphedBySortedMany(Post::class, 'taggable');
    }

    public function videos()
    {
        return $this->morphedBySortedMany(Video::class, 'taggable');
    }
}

$tag = Tag::find(1);
$posts = $tag->posts; // All posts with this tag, in position order
$videos = $tag->videos; // All videos with this tag, in position order
```

--------------------------------

### Example Usage of morphToSortedMany

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/traits.md

Demonstrates how to use the `morphToSortedMany` method within Eloquent models to establish sortable polymorphic many-to-many relationships. This example shows a `Post` and `Video` model both relating to `Tag` models via a 'taggable' morph key.

```php
use AlexCrawford\Sortable\MorphToSortedManyTrait;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use MorphToSortedManyTrait;

    public function tags()
    {
        return $this->morphToSortedMany(Tag::class, 'taggable');
    }
}

class Video extends Model
{
    use MorphToSortedManyTrait;

    public function tags()
    {
        return $this->morphToSortedMany(Tag::class, 'taggable');
    }
}
```

--------------------------------

### SortableException Message Examples

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/errors.md

These examples show the different message formats for SortableException based on the type of group value (integer, string, or multi-field).

```php
// Group value: integer
// Message: "You can't move entities with different sortable group: 1 2"

// Group value: string
// Message: "You can't move entities with different sortable group: published draft"

// Multi-field grouping (comparing first differing field)
// Message: "You can't move entities with different sortable group: 5 10"
```

--------------------------------

### Example Request for Simple Sorting

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-controller.md

Use this JavaScript `fetch` request to reorder a model using simple sorting. Ensure the `Content-Type` and `X-CSRF-TOKEN` headers are correctly set.

```javascript
fetch('/sort', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content,
    },
    body: JSON.stringify({
        type: 'moveAfter',
        entityName: 'articles',
        id: 3,
        positionEntityId: 14
    })
})
.then(r => r.json())
.then(data => {
    if (data.success) {
        console.log('Sorted successfully');
    } else {
        console.error('Validation errors:', data.errors);
    }
});
```

--------------------------------

### SortableTrait Integration and Usage Example

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Demonstrates how to use the SortableTrait within an Eloquent model. Shows creating new models, retrieving them in sorted order, reordering models, and navigating to the next or previous model.

```php
use AlexCrawford\Sortable\SortableTrait;

class Article extends Model
{
    use SortableTrait;
    
    protected static $sortableField = 'position';
    protected static $sortableGroupField = 'category_id';
}

// Create articles with automatic positions
$article1 = new Article(['title' => 'First', 'category_id' => 1]);
$article1->save();

$article2 = new Article(['title' => 'Second', 'category_id' => 1]);
$article2->save();

// Get all articles in order
$sorted = Article::where('category_id', 1)->sorted()->get();

// Reorder
$article1->moveAfter($article2);

// Navigate
$next = $article1->next()->first();
$previous = $article1->getPrevious(5);
```

--------------------------------

### HTTP Endpoint for Sorting

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/README.md

Configuration and usage example for the HTTP endpoint that handles sorting requests. The `config/sortable.php` file defines entities and their relations.

```php
// Route
Route::post('/sort', '\AlexCrawford\Sortable\SortableController@sort');

// Config (config/sortable.php)
'entities' => [
    'articles' => 'App\Models\Article',
    'posts' => ['entity' => 'App\Models\Post', 'relation' => 'tags'],
]

// AJAX
fetch('/sort', {
    method: 'POST',
    body: JSON.stringify({
        type: 'moveAfter',
        entityName: 'articles',
        id: 3,
        positionEntityId: 14
    })
});
```

--------------------------------

### BelongsToSortedMany Trait Usage Example

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/traits.md

Demonstrates how to use the BelongsToSortedManyTrait in an Eloquent model to define sortable many-to-many relationships. Shows basic usage and an example with an explicitly defined table name.

```php
use AlexCrawford\Sortable\BelongsToSortedManyTrait;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use BelongsToSortedManyTrait;

    public function tags()
    {
        return $this->belongsToSortedMany(Tag::class);
    }

    // With explicit table name
    public function categories()
    {
        return $this->belongsToSortedMany(Category::class, 'position', 'post_category');
    }
}
```

--------------------------------

### next()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Gets a query builder for entities that come after the current model, ordered from closest to furthest.

```APIDOC
## next()

### Description
Gets a query builder for entities that come after this one. Results are ordered from closest to furthest.

### Method Signature
```php
public function next(int $limit = 0): QueryBuilder
```

### Parameters
#### Path Parameters
- **limit** (int) - Optional - Maximum number of results (0 = unlimited) - Default: 0

### Returns
- **QueryBuilder** - Query ordered by position ascending (closest first)

### Example
```php
$article = Article::find(5);
$next = $article->next()->first(); // Immediately after article 5
$nextFive = $article->next(5)->get(); // Next 5 after article 5
```
```

--------------------------------

### String Type Position Example

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/types.md

Demonstrates how to retrieve and update the LexoRank-encoded position string for a sortable model. The position value changes after using the moveAfter method.

```php
$article = Article::find(1);
echo $article->position; // 'U'

$article->moveAfter(Article::find(2));
echo $article->position; // 'V' or 'U|' depending on layout
```

--------------------------------

### Model Setup for Sortable Trait

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-controller.md

Set up your Eloquent models to use the SortableTrait for single-item sorting or the BelongsToSortedManyTrait for many-to-many relationships.

```php
// app/Models/Article.php
use AlexCrawford\Sortable\SortableTrait;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use SortableTrait;
}

// app/Models/Post.php
use AlexCrawford\Sortable\BelongsToSortedManyTrait;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use BelongsToSortedManyTrait;
    
    public function tags()
    {
        return $this->belongsToSortedMany(Tag::class, 'position');
    }
}

// app/Models/Tag.php
class Tag extends Model {}
```

--------------------------------

### previous()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Gets a query builder for entities that come before the current model, ordered from closest to furthest.

```APIDOC
## previous()

### Description
Gets a query builder for entities that come before this one. Results are ordered from closest to furthest.

### Method Signature
```php
public function previous(int $limit = 0): QueryBuilder
```

### Parameters
#### Path Parameters
- **limit** (int) - Optional - Maximum number of results (0 = unlimited) - Default: 0

### Returns
- **QueryBuilder** - Query ordered by position descending (closest first)

### Example
```php
$article = Article::find(5);
$previous = $article->previous()->first(); // Immediately before article 5
$prevThree = $article->previous(3)->get(); // Last 3 before article 5
```
```

--------------------------------

### Example Request for Many-to-Many Sorting

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-controller.md

This JavaScript `fetch` request demonstrates how to reorder a model within a many-to-many relationship. The `parentId` parameter is crucial for specifying the parent model.

```javascript
fetch('/sort', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content,
    },
    body: JSON.stringify({
        type: 'moveBefore',
        entityName: 'posts',
        id: 5,              // Tag ID to move
        parentId: 1,        // Post ID (parent)
        positionEntityId: 2 // Tag ID to move before
    })
})
.then(r => r.json())
.then(data => {
    if (data.success) {
        console.log('Reordered successfully');
    }
});
```

--------------------------------

### Composer Dependencies for Lexorank Sortable

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/README.md

Specifies the required PHP version and package dependencies for using Lexorank Sortable. Ensure your project meets these requirements before installation.

```json
// composer.json
"require": {
    "php": ">=8.1",
    "illuminate/support": "^10.0|^11.0|^12.0|^13.0",
    "alexcrawford/lexorank-php": "^2.0"
}
```

--------------------------------

### Get Previous Entities with getPrevious()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Use `getPrevious()` to retrieve all entities that come before the current one. The results are returned as a Collection, ordered from furthest to closest.

```php
$article = Article::find(5);
$allBefore = $article->getPrevious(); // All articles before #5, ordered closest-first
```

--------------------------------

### Get Sibling Entities with siblings()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Use the `siblings()` method to get a query builder for entities that appear before or after the current one in the sort order. Set `$isNext` to `true` for subsequent entities and `false` for preceding ones. The `$limit` parameter controls the maximum number of results.

```php
$article = Article::find(5);
$laterItems = $article->siblings(true)->get(); // All after
$earlierItems = $article->siblings(false)->get(); // All before
```

--------------------------------

### Get Next Entities with getNext()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Use `getNext()` to retrieve all entities that come after the current one. The results are returned as a Collection, ordered from closest to furthest. You can specify a `$limit` to restrict the number of results.

```php
$article = Article::find(5);
$next = $article->getNext(3); // Next 3 articles, closest-first
```

--------------------------------

### Frontend Sorting with jQuery UI (Single)

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-controller.md

Implement frontend sorting using jQuery UI Sortable. This example shows how to update the order of table rows and send the new order to the backend via AJAX.

```html
<table class="table">
    <tbody class="sortable" data-entityname="articles">
    @foreach ($articles as $article)
    <tr data-itemId="{{ $article->id }}">
        <td class="handle">☰</td>
        <td>{{ $article->title }}</td>
    </tr>
    @endforeach
    </tbody>
</table>

<script>
$(function() {
    $(".sortable").sortable({
        handle: ".handle",
        update: function(event, ui) {
            var $sorted = ui.item;
            var $previous = $sorted.prev();
            var $next = $sorted.next();
            
            var data = {
                entityName: $(this).data('entityname'),
                id: $sorted.data('itemid'),
                type: 'moveAfter',
            };
            
            if ($previous.length) {
                data.positionEntityId = $previous.data('itemid');
            } else if ($next.length) {
                data.type = 'moveBefore';
                data.positionEntityId = $next.data('itemid');
            }
            
            $.ajax({
                url: '/sort',
                type: 'POST',
                data: JSON.stringify(data),
                contentType: 'application/json',
                headers: {
                    'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr('content')
                },
                success: function(response) {
                    if (response.success) {
                        console.log('Sorted!');
                    } else {
                        console.error('Validation error:', response.errors);
                    }
                }
            });
        }
    });
});
</script>
```

--------------------------------

### Model Without Sortable Grouping

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/errors.md

Illustrates a model configuration without a defined $sortableGroupField. In this setup, SortableException is never thrown, allowing entities to be moved freely.

```php
class Article extends Model
{
    use SortableTrait;
    
    // No $sortableGroupField defined - entities are not grouped
}

$article1 = Article::find(1);
$article2 = Article::find(2);

$article1->moveAfter($article2); // Never throws SortableException
```

--------------------------------

### Define MorphToSortedMany Relations in Parent Models

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/morph-to-sorted-many.md

Define polymorphic sortable relations in parent models like Post and Video. This setup requires the MorphToSortedManyTrait and enables attaching, retrieving, and reordering related tags.

```php
use AlexCrawford\Sortable\MorphToSortedManyTrait;

class Post extends Model
{
    use MorphToSortedManyTrait;

    public function tags()
    {
        return $this->morphToSortedMany(Tag::class, 'taggable');
    }
}

class Video extends Model
{
    use MorphToSortedManyTrait;

    public function tags()
    {
        return $this->morphToSortedMany(Tag::class, 'taggable');
    }
}

// Usage
$post = Post::find(1);
$video = Video::find(1);

// Attach tags (automatically positioned)
$post->tags()->attach([1, 2, 3]);
$video->tags()->attach([1, 2]);

// Retrieve in position order
$postTags = $post->tags; // Ordered by position
$videoTags = $video->tags; // Ordered by position

// Reorder
$tag1 = $post->tags()->find(1);
$tag2 = $post->tags()->find(2);
$post->tags()->moveAfter($tag1, $tag2);
```

--------------------------------

### Query for Previous Models

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Use the `previous` method to get a query builder for entities that appear before the current model. An optional limit can be specified; 0 means unlimited results. Results are ordered from closest to furthest.

```php
$article = Article::find(5);
$previous = $article->previous()->first(); // Immediately before article 5
$prevThree = $article->previous(3)->get(); // Last 3 before article 5
```

--------------------------------

### siblings()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Gets a query builder for entities before or after the current one. This is a core method used by `previous()` and `next()` to fetch all entities on one side of the current entity in the sort order.

```APIDOC
## siblings(bool $isNext, int $limit = 0)

### Description
Gets a query builder for entities before or after this one.

### Parameters
#### Path Parameters
- **isNext** (bool) - Required - `true` for entities after; `false` for entities before
- **limit** (int) - Optional - `0` - Maximum number of results (0 = unlimited)

### Returns
`QueryBuilder` — Query builder for sibling entities

### Example
```php
$article = Article::find(5);
$laterItems = $article->siblings(true)->get(); // All after
$earlierItems = $article->siblings(false)->get(); // All before
```
```

--------------------------------

### Frontend Sorting with jQuery UI (Many-to-Many)

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-controller.md

This example demonstrates frontend sorting for a many-to-many relationship using jQuery UI Sortable. It includes sending parent ID information along with the sorting data.

```html
<table class="table">
    <tbody class="sortable" data-entityname="posts">
    @foreach ($post->tags as $tag)
    <tr data-itemId="{{ $tag->id }}" data-parentId="{{ $post->id }}">
        <td class="handle">☰</td>
        <td>{{ $tag->name }}</td>
    </tr>
    @endforeach
    </tbody>
</table>

<script>
var data = {
    entityName: $(this).data('entityname'),
    parentId: $sorted.data('parentid'),
    id: $sorted.data('itemid'),
    positionEntityId: $previous.data('itemid'),
    type: 'moveAfter',
};
$.post('/sort', data);
```

--------------------------------

### SortableServiceProvider::boot

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/service-provider.md

This method is called after all services are registered. It publishes the package configuration file to the application's `config/` directory.

```APIDOC
## SortableServiceProvider::boot

### Description
This method is called after all services are registered. It publishes the package configuration file to the application's `config/` directory.

### Method
`public function boot(): void`

### Parameters
None

### Response
None

### How to Publish
```bash
php artisan vendor:publish --provider="AlexCrawford\Sortable\SortableServiceProvider"
```
```

--------------------------------

### Publish Configuration

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Run this Artisan command to publish the sortable configuration file to your project.

```bash
php artisan vendor:publish
```

--------------------------------

### Docker Build Command

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Builds the Docker image for the project. Tag the image as 'alexcrawford-sortable'.

```bash
docker build -t alexcrawford-sortable .

```

--------------------------------

### Using Eloquent Model with Sortable Methods

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/types.md

Demonstrates how to use Eloquent Model instances with sortable methods like moveAfter. Ensure models are instances of Illuminate\Database\Eloquent\Model.

```php
$article1 = Article::find(1); // Model instance
$article2 = Article::find(2); // Model instance

$article1->moveAfter($article2); // Model passed as parameter
```

--------------------------------

### Catching SortableException with Try-Catch

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/errors.md

Demonstrates the basic try-catch pattern to handle SortableException. It shows how to access the exception message for error handling.

```php
try {
    $article1->moveAfter($article2);
} catch (SortableException $e) {
    echo $e->getMessage(); // "You can't move entities with different sortable group: 1 2"
    // Handle the error - e.g., show validation message to user
}
```

--------------------------------

### Get Order Column Name

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/traits.md

Returns the name of the configured position column used for sorting.

```php
protected function getOrderColumnName(): string
```

--------------------------------

### Laravel Pint for Code Formatting

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Commands to check and fix code style using Laravel Pint. Use '--test' to only check without modifying files.

```bash
vendor/bin/pint              # Check and fix code style
vendor/bin/pint --test       # Check only (don't modify)
```

--------------------------------

### Get Sorted Tags for a Post

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Retrieves the tags associated with a post, automatically sorted by their position.

```php
$post->tags; // ordered by position by default
```

--------------------------------

### Publish Sortable Configuration

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/service-provider.md

Use this command to publish the sortable package's configuration file to your application's config directory.

```bash
php artisan vendor:publish --provider="AlexCrawford\Sortable\SortableServiceProvider"
```

--------------------------------

### Docker Run Command for All Tests

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Executes PHPUnit, PHPStan, and Laravel Pint checks sequentially within a Docker container to ensure code quality and test coverage.

```bash
docker run --volume $PWD:/project --rm --user $(id -u):$(id -g) alexcrawford-sortable bash -c "vendor/bin/phpunit && vendor/bin/phpstan analyse && vendor/bin/pint --test"

```

--------------------------------

### Get Ordered Entities with Sorted Scope

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Use the `sorted` scope on your model to retrieve entities in their correct sorted order.

```php
$articles = Article::sorted()->get();
```

--------------------------------

### Basic Entity Configuration

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/configuration.md

Defines simple entity mappings for HTTP controllers. Use this for basic one-to-one sorting.

```php
return [
    'entities' => [
        // Simple sorting
        'articles' => '\App\Models\Article',
        
        // Many-to-many sorting
        'posts' => [
            'entity' => '\App\Models\Post',
            'relation' => 'tags',
        ],
    ],
];
```

```php
'entities' => [
    'articles' => 'App\Models\Article',
    'documents' => 'App\Models\Document',
]
```

--------------------------------

### Get Validator for Sortable Entities

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-controller.md

Creates a validation object for the request, building rules for entity existence and pivot table validation.

```php
protected function getValidator(array $sortableEntities, Request $request): Validator
```

--------------------------------

### Sortable Configuration File Template

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/service-provider.md

The default structure of the published config/sortable.php file, illustrating the format for simple and relation-based sorting configurations.

```php
<?php

return [
    'entities' => [
        // 'articles' => '\Article' for simple sorting
        // (entityName => entityModel) 
        // or
        // 'posts' => ['entity' => '\Post', 'relation' => 'tags']
        // for many to many or many to many polymorphic relation sorting
    ],
];
```

--------------------------------

### Sortable Package Configuration

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/configuration.md

Register your sortable entities in the package's configuration file.

```php
// config/sortable.php
return [
    'entities' => [
        'articles' => 'App\Models\Article',
    ],
];
```

--------------------------------

### Get New Position

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/traits.md

A static method used to calculate an intermediate position between two existing positions. Described in full detail under SortableTrait.

```php
public static function getNewPosition(?string $prev, ?string $next = ''): string
```

--------------------------------

### Low-Level Repositioning with Move Action

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/belongs-to-sorted-many.md

The `move()` method provides low-level repositioning using explicit actions like 'moveAfter' or 'moveBefore'. It calculates intermediate position values and updates the pivot table.

```php
$post->tags()->move('moveAfter', $tag1, $tag2);
```

--------------------------------

### Configure Models for Simple Sorting

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/service-provider.md

Define simple sorting configurations in config/sortable.php by mapping an entity name to its corresponding model class.

```php
'entities' => [
    'articles' => 'App\Models\Article',
],
```

--------------------------------

### Get Next Position

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/traits.md

Queries the pivot table to find the maximum position and generates a new position string after it. For an empty relation, it returns the initial position.

```php
protected function getNextPosition(): string
```

--------------------------------

### Simple Model Sorting

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/README.md

Demonstrates how to implement and use simple sorting on a model. The `SortableTrait` is used, and a `sortableGroupField` can be defined for category-specific sorting.

```php
// Model
class Article extends Model
{
    use SortableTrait;
    protected static $sortableGroupField = 'category_id';
}

// Usage
$article = Article::find(1);
$article->moveAfter(Article::find(5));

$sorted = Article::where('category_id', 1)->sorted()->get();
```

--------------------------------

### Get Sortable Group Field Name

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Retrieves the field or fields used for grouping sorted entities. This scopes ordering to specific fields like 'category_id'.

```php
public static function getSortableGroupField(): string|array|null
```

```php
class Article extends Model
{
    use SortableTrait;
    protected static $sortableGroupField = 'category_id';
}

$groupField = Article::getSortableGroupField(); // 'category_id'
```

--------------------------------

### move()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/belongs-to-sorted-many.md

Low-level repositioning method that takes an action string ('moveAfter' or 'moveBefore') to determine the repositioning direction.

```APIDOC
## move()

### Description
Implements the core repositioning logic. Called by `moveAfter()` and `moveBefore()`. Calculates intermediate position value using LexoRank and updates the pivot table.

### Method
`move(string $action, Model $entity, Model $positionEntity): void`

### Parameters
#### Path Parameters
- `$action` (string) - Required - Either `'moveAfter'` or `'moveBefore'`
- `$entity` (Model) - Required - The related model to move
- `$positionEntity` (Model) - Required - The reference position model

### Request Example
```php
$post->tags()->move('moveAfter', $tag1, $tag2);
```
```

--------------------------------

### Calculate New Position

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Calculates a new LexoRank string position between two existing positions. Handles edge cases for starting, beginning, and end of sequences.

```php
public static function getNewPosition(?string $prev, ?string $next = ''): string
```

```php
$pos1 = Article::getNewPosition(null, null); // 'U' (first position)
$pos2 = Article::getNewPosition('U', null); // 'V' (after U)
$pos3 = Article::getNewPosition('U', 'V'); // 'U|' (between U and V)
```

--------------------------------

### Articles Table Migration

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/configuration.md

Create the 'articles' table with the necessary columns for sorting, including a position field.

```php
Schema::create('articles', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->unsignedBigInteger('category_id');
    $table->string('position')->charset('utf8mb4')->collation('utf8mb4_bin');
    $table->timestamps();
    
    $table->foreign('category_id')->references('id')->on('categories');
});
```

--------------------------------

### Sync Related Models with New Positions

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/morph-to-sorted-many.md

Use `sync()` to synchronize the related models, detaching and re-attaching all in the specified order with new LexoRank positions. Control detachment of unspecified models with the second parameter.

```php
$post->tags()->sync([1, 2, 3]); // Re-attach in this order
```

--------------------------------

### move()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/morph-to-sorted-many.md

Low-level repositioning with explicit action. Calculates intermediate position using LexoRank and updates the polymorphic table.

```APIDOC
## move()

### Description
Implements the core repositioning logic. Calculates intermediate position using LexoRank and updates the polymorphic table.

### Method
`move(string $action, Model $entity, Model $positionEntity): void`

### Parameters
#### Path Parameters
- **$action** (string) - Required - Either `'moveAfter'` or `'moveBefore'`
- **$entity** (Model) - Required - The related model to move
- **$positionEntity** (Model) - Required - The reference position model

### Request Example
```php
$post->tags()->move('moveAfter', $tag1, $tag2);
```
```

--------------------------------

### Docker Run Command for Code Coverage

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Runs PHPUnit tests with code coverage enabled, outputting results in text format within a Docker container.

```bash
docker run --volume $PWD:/project --rm --user $(id -u):$(id -g) alexcrawford-sortable vendor/bin/phpunit --coverage-text

```

--------------------------------

### Get Sortable Field Name

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Retrieves the name of the column used for storing position values. Models can override the default 'position' by setting a static `$sortableField` property.

```php
public static function getSortableField(): string
```

```php
class Article extends Model
{
    use SortableTrait;
    protected static $sortableField = 'sort_order';
}

$fieldName = Article::getSortableField(); // 'sort_order'
```

--------------------------------

### Register Service Provider

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Add the SortableServiceProvider to your application's configuration file to enable the package's functionality.

```php
'providers' => array(
    // providers...

    'AlexCrawford\Sortable\SortableServiceProvider',
)
```

--------------------------------

### Get Parent Model's Pivot Table Key

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/belongs-to-sorted-many.md

The `getForeignKey()` method returns the foreign key column name for the parent model in the pivot table, such as 'post_id'.

```php
$relation->getForeignKey();
```

--------------------------------

### Get Related Model's Pivot Table Key

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/belongs-to-sorted-many.md

The `getRelatedKey()` method returns the foreign key column name for the related model in the pivot table, such as 'tag_id'.

```php
$relation->getRelatedKey();
```

--------------------------------

### Docker Run Command for Tests

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Runs PHPUnit tests within a Docker container. It mounts the current directory to '/project' and runs tests using the specified user.

```bash
docker run --volume $PWD:/project --rm --user $(id -u):$(id -g) alexcrawford-sortable vendor/bin/phpunit

```

--------------------------------

### Get Previous Eloquent Collection

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/types.md

Use the `getPrevious()` method to retrieve a collection of preceding Eloquent model instances. This collection can be iterated over to access individual model properties.

```php
$previous = $article->getPrevious(5);
// Returns Collection of Article instances

foreach ($previous as $item) {
    echo $item->title;
}
```

--------------------------------

### Register Sortable Service Provider

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-controller.md

Add the SortableServiceProvider to your application's providers in `config/app.php` to enable the sorting functionality.

```php
        'providers' => [
            // ...
            AlexCrawford\Sortable\SortableServiceProvider::class,
        ],
```

--------------------------------

### Get Sorted Query Builder

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/types.md

Use the `sorted()` scope to retrieve a query builder instance for sorted Eloquent models. This allows for chaining additional query constraints.

```php
// Returns QueryBuilder
$query = Article::sorted();

// Can chain additional methods
$sorted = Article::sorted()->where('published', true)->get();
```

--------------------------------

### Handling SortableException in a Controller

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/errors.md

Provides an example of catching SortableException within a controller method. It returns a JSON response with an error message and a 422 status code upon exception.

```php
public function moveArticle(Request $request)
{
    try {
        $article = Article::find($request->id);
        $reference = Article::find($request->reference_id);
        
        $article->moveAfter($reference);
        
        return response()->json(['success' => true]);
    } catch (SortableException $e) {
        return response()->json([
            'success' => false,
            'error' => 'Cannot move articles between different categories'
        ], 422);
    }
}
```

--------------------------------

### Move Model Before Another

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Use `moveBefore` to reposition the current model to appear directly before a specified reference entity. The change is automatically saved, and the method respects sortable group boundaries.

```php
$article1 = Article::find(1);
$article2 = Article::find(2);
$article1->moveBefore($article2); // article1 now comes before article2
```

--------------------------------

### move()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/traits.md

A low-level operation for moving models within the sorted sequence. Further information can be found in the relation classes.

```APIDOC
## move()

### Description
Low-level move operation.

### Method
`public function move(string $action, Model $entity, Model $positionEntity): void`

### Details
Described in full detail under relation classes.
```

--------------------------------

### Define MorphToSortedMany Relations in Models

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/morph-to-sorted-many.md

Define inverse polymorphic sortable relations from the perspective of the related model. This is used when querying from the tag's perspective to get all associated posts or videos, ordered by their position.

```php
class Tag extends Model
{
    public function posts()
    {
        return $this->morphedBySortedMany(Post::class, 'taggable');
    }

    public function videos()
    {
        return $this->morphedBySortedMany(Video::class, 'taggable');
    }
}

$tag = Tag::find(1);
$posts = $tag->posts; // All posts with this tag, ordered by position
$videos = $tag->videos; // All videos with this tag, ordered by position
```

--------------------------------

### Basic Sortable Usage

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/configuration.md

Retrieve sorted articles and move individual articles within their sort order.

```php
$articles = Article::where('category_id', 1)->sorted()->get();
$article = Article::find(1);
$article->moveAfter(Article::find(5));
```

--------------------------------

### Configure Sortable Entities

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Define the entities and their corresponding models that you want to make sortable in the `config/sortable.php` file. Supports direct entity mapping or specifying a relation for many-to-many relationships.

```php
'entities' => array(
     'articles' => '\App\Article', // entityNameForUseInRequest => ModelName
     // or
     'articles' => ['entity' => '\App\Article'],
     // or for many to many
     'posts' => [
        'entity' => '\App\Post',
        'relation' => 'tags' // relation name (method name which returns $this->belongsToSortedMany)
     ]
),
```

--------------------------------

### Low-Level Model Movement

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

The `move` method provides low-level control for repositioning a model relative to another, accepting an action string ('moveAfter' or 'moveBefore'). It wraps the operation in a database transaction.

```php
$article = Article::find(1);
$reference = Article::find(5);
$article->move('moveAfter', $reference);
```

--------------------------------

### Attach Tags to Post

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Demonstrates methods for attaching tags to a post, which automatically sets their position. Supports `save`, `attach`, and `sync` operations.

```php
$post->tags()->save($tag) // or
$post->tags()->attach($tag->id) // or
$post->tags()->sync([$tagId1, $tagId2, /* ...tagIds */])
```

--------------------------------

### Many-to-Many Model Sorting

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/README.md

Shows how to implement many-to-many sorting using the `BelongsToSortedManyTrait`. New relationships are automatically positioned at the end.

```php
// Model
class Post extends Model
{
    use BelongsToSortedManyTrait;
    public function tags()
    {
        return $this->belongsToSortedMany(Tag::class);
    }
}

// Usage
$post = Post::find(1);
$post->tags()->attach(5); // Auto-positioned at end
$post->tags()->moveAfter($tag1, $tag2); // Reorder
```

--------------------------------

### Define Sort Route

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Add this route definition to your `routes/web.php` or `routes/api.php` file to handle sorting requests.

```php
Route::post('sort', '\AlexCrawford\Sortable\SortableController@sort');
```

--------------------------------

### Register Sortable Service Provider

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/service-provider.md

Add the SortableServiceProvider to your application's config/app.php file to enable the package's functionality.

```php
    'providers' => [
        // ... other providers ...
        AlexCrawford\Sortable\SortableServiceProvider::class,
    ],
```

--------------------------------

### moveBefore()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/morph-to-sorted-many.md

Repositions a related model to appear before another. Both models must already be attached to the parent.

```APIDOC
## moveBefore()

### Description
Repositions `$entity` to appear directly before `$positionEntity` in the morphable table. Both models must already be attached to the parent.

### Method
`moveBefore(Model $entity, Model $positionEntity): void`

### Parameters
#### Path Parameters
- **$entity** (Model) - Required - The related model to move
- **$positionEntity** (Model) - Required - The related model to move before

### Throws
- `Exception` (from parent if operation fails)

### Request Example
```php
$post = Post::find(1);
$tag1 = $post->tags()->find(1);
$tag2 = $post->tags()->find(2);

$post->tags()->moveBefore($tag1, $tag2); // tag1 now before tag2
```
```

--------------------------------

### Query Between Positions

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/traits.md

Creates a query builder instance to select pivot records within a specified range of positions. Allows for inclusive or exclusive boundaries.

```php
protected function queryBetween(string $left, string $right, bool $leftIncluded = false, bool $rightIncluded = false): Builder
```

--------------------------------

### Move Related Model Before Another

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/morph-to-sorted-many.md

Use `moveBefore()` to reposition an attached model to appear directly before another specified model. Both models must already be attached to the parent.

```php
$post = Post::find(1);
$tag1 = $post->tags()->find(1);
$tag2 = $post->tags()->find(2);

$post->tags()->moveBefore($tag1, $tag2); // tag1 now before tag2
```

--------------------------------

### sorted()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

A query scope that orders models by their position. Use this scope to retrieve models in their intended order.

```APIDOC
## sorted()

### Description
Query scope that orders models by position. Adds an `ORDER BY position` clause to the query.

### Method Signature
```php
public function scopeSorted($query): QueryBuilder
```

### Parameters
#### Path Parameters
- **query** (QueryBuilder) - The query builder instance

### Returns
- **QueryBuilder** - The query ordered by position ascending

### Example
```php
$articles = Article::sorted()->get(); // Ordered by position
$published = Article::where('published', true)->sorted()->get();
```
```

--------------------------------

### Constructor

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/belongs-to-sorted-many.md

Constructs a BelongsToSortedMany relation. This is typically instantiated via the `belongsToSortedMany()` trait method and not directly by the user. It sets up ordering by a specified position column on the pivot table.

```APIDOC
## Constructor

### Description
Constructs a BelongsToSortedMany relation. Automatically sets up ordering by the position column.

### Parameters
#### Path Parameters
- **`$query`** (Builder) - Required - Query builder for the related model
- **`$parent`** (Model) - Required - The parent model instance
- **`$table`** (string) - Required - The pivot table name
- **`$foreignPivotKey`** (string) - Required - The foreign key on the pivot table
- **`$relatedPivotKey`** (string) - Required - The related model's key on the pivot table
- **`$parentKey`** (string) - Required - The parent model's key name
- **`$relatedKey`** (string) - Required - The related model's key name
- **`$relationName`** (string|null) - Optional - The relation name
- **`$orderColumn`** (string|null) - Optional - The position column name (default: `'position'`)
```

--------------------------------

### Move Related Model Before Another

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/belongs-to-sorted-many.md

Use `moveBefore()` to reposition a related model to appear directly before another specified related model. Both models must already be attached to the parent.

```php
$post->tags()->moveBefore($tag1, $tag2);
```

--------------------------------

### SortableServiceProvider::provides

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/service-provider.md

Declares which services this provider registers. Returns an empty array since this package doesn't register services.

```APIDOC
## SortableServiceProvider::provides

### Description
Declares which services this provider registers. Returns an empty array since this package doesn't register services.

### Method
`public function provides(): array`

### Parameters
None

### Response
`array` — An empty array (no services provided to the IoC container)
```

--------------------------------

### moveBefore() with Different Groups

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/errors.md

This exception occurs when moveBefore() is used with entities from different sortable groups. Verify that the entities are in the same group prior to executing this method.

```php
$article1 = Article::find(1); // category_id = 1
$article2 = Article::find(2); // category_id = 2

$article1->moveBefore($article2);
// Throws: SortableException("1 2")
```

--------------------------------

### Extract Entity Info from Configuration

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-controller.md

Parses entity configuration to determine the model class and optional relation name. Use this to extract details about a specific entity from the sortable configuration.

```php
protected function getEntityInfo(array $sortableEntities, string $entityName): array
```

```php
// Config: 'articles' => '\\App\\Article'
$result = $this->getEntityInfo($entities, 'articles');
// Returns: ['\\App\\Article', false]

// Config: 'posts' => ['entity' => '\\App\\Post', 'relation' => 'tags']
$result = $this->getEntityInfo($entities, 'posts');
// Returns: ['\\App\\Post', 'tags']
```

--------------------------------

### MySQL Alternative Binary Position Column

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/configuration.md

An alternative for MySQL/MariaDB using the 'binary' type for the position column, ensuring strict lexicographic ordering.

```php
$table->binary('position', 255); // Pure binary type
```

--------------------------------

### queryBetween()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/traits.md

Protected method that creates a query builder instance to select records within a specified range of positions. It allows for inclusive or exclusive boundary checks.

```APIDOC
## queryBetween()

### Description
Creates a query for positions between two values.

### Method
`protected function queryBetween(string $left, string $right, bool $leftIncluded = false, bool $rightIncluded = false): Builder`

### Parameters
#### Path Parameters
- **left** (string) - Required - Left boundary position
- **right** (string) - Required - Right boundary position
- **leftIncluded** (bool) - Optional - Whether to include left boundary (>= vs >)
- **rightIncluded** (bool) - Optional - Whether to include right boundary (<= vs <)

### Returns
`Builder` - Query builder for pivot records in range
```

--------------------------------

### Move Model After Another

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Use `moveAfter` to reposition the current model to appear directly after a specified reference entity. This method automatically saves the change and respects sortable group boundaries.

```php
$article1 = Article::find(1);
$article2 = Article::find(2);
$article1->moveAfter($article2); // article1 now comes after article2
```

--------------------------------

### Move Eloquent Model Entity Position

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/README.md

Use the `moveBefore($entity)` and `moveAfter($entity)` methods to reorder entities. The position is automatically saved.

```php
$entity = Article::find(1);

$positionEntity = Article::find(10)

$entity->moveAfter($positionEntity);

// if $positionEntity->position is aaa, then $entity->position is aab now
```

--------------------------------

### moveBefore()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

Moves the current model to appear immediately before a specified reference entity. This operation automatically saves the change and respects sortable group boundaries.

```APIDOC
## moveBefore()

### Description
Moves this model to appear immediately before a reference entity. Automatically saves the change and respects sortable group boundaries.

### Method Signature
```php
public function moveBefore(Model $entity): void
```

### Parameters
#### Path Parameters
- **entity** (Model) - Required - The model before which to move this instance

### Throws
- **SortableException** - If moving between different sortable groups

### Example
```php
$article1 = Article::find(1);
$article2 = Article::find(2);
$article1->moveBefore($article2); // article1 now comes before article2
```
```

--------------------------------

### sync()

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/belongs-to-sorted-many.md

Synchronizes the related models, detaching and re-attaching all specified models, which resets their positions in sequence order.

```APIDOC
## sync()

### Description
Synchronizes the relation. All relations are detached first (if `$detaching` is true), then re-attached. This resets all positions in sequence order.

### Method
`sync($ids, bool $detaching = true): array`

### Parameters
#### Path Parameters
- `$ids` (array|Collection) - Required - IDs to sync (or `id => attributes` map)
- `$detaching` (bool) - Optional - Whether to detach models not in `$ids` (default: `true`)

### Returns
- `array` - Sync report with `attached`, `detached`, `updated` keys

### Request Example
```php
$post->tags()->sync([1, 2, 3]); // Re-attach tag IDs 1, 2, 3 in that order
```
```

--------------------------------

### Standard Position Column (SQLite, PostgreSQL)

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/configuration.md

Defines a standard 'position' column for articles using Schema::create. Suitable for SQLite and PostgreSQL.

```php
Schema::create('articles', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->string('position'); // Default text collation works
});
```

--------------------------------

### Move Related Model After Another

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/morph-to-sorted-many.md

Use `moveAfter()` to reposition an attached model to appear directly after another specified model. Both models must already be attached to the parent.

```php
$post = Post::find(1);
$tag1 = $post->tags()->find(1);
$tag2 = $post->tags()->find(2);

$post->tags()->moveAfter($tag1, $tag2); // tag1 now after tag2
```

--------------------------------

### Query for Next Models

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/api-reference/sortable-trait.md

The `next` method returns a query builder for entities that appear after the current model. You can specify a limit for the number of results (0 for unlimited). Results are ordered from closest to furthest.

```php
$article = Article::find(5);
$next = $article->next()->first(); // Immediately after article 5
$nextFive = $article->next(5)->get(); // Next 5 after article 5
```

--------------------------------

### moveAfter() with Different Groups

Source: https://github.com/alexcrawford/lexorank-sortable/blob/main/_autodocs/errors.md

This exception is thrown when moveAfter() is called on an entity, and the reference entity belongs to a different sortable group. Ensure both entities share the same group identifier before attempting to reorder.

```php
$article1 = Article::find(1); // category_id = 1
$article2 = Article::find(2); // category_id = 2

$article1->moveAfter($article2); 
// Throws: SortableException("1 2")
```
Tokens:
Raw