Filament Tree

https://github.com/15web/filament-tree
Admin
A Filament admin panel plugin that allows building and managing Eloquent trees, ideal for menus,...
Tokens:38,956
Snippets:285
Trust Score:6.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Config override example for filament-tree

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/configuration.md

Example configuration file showing all three options with comments explaining their effects.

```php
// config/filament-tree.php
return [
    'allow-delete-parent' => true,   // parents with children may be deleted
    'allow-delete-root' => true,     // root nodes with children may be deleted
    'show-parent-select-while-edit' => false, // compact edit form; re-parent by drag & drop
];
```

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

### Install filament-tree with Composer

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/README.md

Install the filament-tree package via Composer.

```bash
composer require 15web/filament-tree
```

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

### Typical consumer of ParentSelect::make()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/parent-select.md

Shows how to create a parent select for a model, with comments indicating that the edited node and its descendants are disabled, and an example of the resulting options with depth-based indentation.

```php
// Typical consumer — an edited node is disabled along with its
// descendants, so a node can never be its own ancestor.
$select = ParentSelect::make(AwesomeModel::query());

// options will look like:
// 1 => ' Parent A'
// 2 => '-- Child A.1'
// 3 => '-- Child A.2'
// 4 => ' Parent B'
```

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

### TreePage::getModel() example - scoped query

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/tree-page.md

Returns a scoped query for multi-menu setups with a 'menu_id' attribute. Behavioral differences apply when a QueryBuilder is returned.

```php
use App\Models\AwesomeModel;
use Kalnoy\Nestedset\QueryBuilder;

public static function getModel(): string|QueryBuilder
{
    return AwesomeModel::scoped(['menu_id' => 2]);
}
```

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

### Artisan tinker example of fixTree() usage

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/footer.md

Artisan tinker example showing how to call fixTree() on a plain model and on a scoped QueryBuilder, mirroring the button's behavior.

```php
// artisan tinker example of what the button does under the hood
use App\Models\AwesomeModel;
use Kalnoy\Nestedset\QueryBuilder;

// plain model:
AwesomeModel::fixTree();

// scoped model:
$builder = AwesomeModel::scoped(['menu_id' => 2]);
$builder->fixTree();
```

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

### Example model using InteractsWithTree and NodeTrait

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/interacts-with-tree.md

Shows a complete model implementation that uses both NodeTrait and InteractsWithTree, implementing getTreeLabelAttribute() to return 'title'.

```php
use Kalnoy\Nestedset\NodeTrait;
use Studio15\FilamentTree\Concerns\InteractsWithTree;

class AwesomeModel extends Model
{
    use NodeTrait;
    use InteractsWithTree;

    public static function getTreeLabelAttribute(): string
    {
        return 'title';
    }
}
```

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

### MoveItem error handling with try-catch

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/move-item.md

Error handling example showing how to catch exceptions thrown by the MoveItem service. ModelNotFoundException indicates a missing parent, while LogicException signals violated invariants such as a cycling move.

```php
use Illuminate\Database\Eloquent\ModelNotFoundException;
use LogicException;

try {
    app(MoveItem::class)(node: $node, parent: 999 /* missing */, from: 0, to: 0);
} catch (ModelNotFoundException $e) {
    // parent 999 does not exist
} catch (LogicException $e) {
    // invariants violated (e.g. cycling move)
}
```

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

### TreePage::getModel() example - plain model class

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/tree-page.md

Returns a model class string. The package derives the model class from the query when a QueryBuilder is returned.

```php
use App\Models\AwesomeModel;
use Kalnoy\Nestedset\QueryBuilder;

public static function getModel(): string|QueryBuilder
{
    return AwesomeModel::class;
}
```

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

### TreePage::getInfolistColumns() override example

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/tree-page.md

Example override that returns TextEntry and IconEntry columns. Uses a label closure to conditionally show 'Desc' for description and a boolean icon for is_published.

```php
use Filament\Infolists\Components\TextEntry;
use Filament\Infolists\Components\IconEntry;
use App\Models\Category;
use Filament\Forms\Get;

public static function getInfolistColumns(): array
{
    return [
        TextEntry::make('description')->label(fn (Category $record, Get $get) => $record->description !== null ? 'Desc' : ''),
        IconEntry::make('is_published')->boolean()->label(''),
    ];
}
```

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

### packageBooted() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/service-provider.md

Registers four Livewire components (move, row, header, footer) and Filament assets (CSS, JS, and Sortable CDN) under the filament-tree package scope. All assets are loaded on request only when the tree page renders.

```php
public function packageBooted(): void
{
    Livewire::component('filament-tree::move', Move::class);
    Livewire::component('filament-tree::row', Row::class);
    Livewire::component('filament-tree::header', Header::class);
    Livewire::component('filament-tree::footer', Footer::class);

    FilamentAsset::register([
        Css::make('filament-tree', __DIR__.'/../resources/dist/filament-tree.min.css')->loadedOnRequest(),
        Js::make('filament-tree', __DIR__.'/../resources/dist/filament-tree.min.js')->loadedOnRequest(),
        Js::make('sortable', 'https://cdn.jsdelivr.net/npm/sortablejs@1.15.6/Sortable.min.js')->loadedOnRequest(),
    ], package: self::$name);
}
```

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

### configurePackage() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/service-provider.md

Configures the package via Spatie's package-tools. Registers the MakeTreePageCommand, views, config file, and translations. The config file is named filament-tree.php and the view/translation namespace is filament-tree.

```php
public function configurePackage(Package $package): void
{
    /*
     * This class is a Package Service Provider
     *
     * More info: https://github.com/spatie/laravel-package-tools
     */
    $package
        ->name(self::$name)
        ->hasCommands([
            MakeTreePageCommand::class,
        ])
        ->hasViews()
        ->hasConfigFile(self::$name)
        ->hasTranslations();
}
```

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

### `handle()` method implementation

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/make-tree-page-command.md

Contains the complete `handle()` method of the command. It parses the page name, determines the panel, computes the namespace and target path, checks for collisions, optionally attaches a cluster, resolves the model statement, copies the stub with replacements, and outputs an info message. Returns `self::SUCCESS` (0) on success, `self::INVALID` (2) on collision without `--force`.

```php
public function handle(Filesystem $filesystem): int
{
    $page = $this->parsePage();

    $pageClass = (string) str($page)->afterLast('\\');
    $pageNamespace = str($page)->contains('\\') ? (string) str($page)->beforeLast('\\') : '';

    $panel = $this->getPanel();

    $pageDirectories = $panel->getPageDirectories();
    $pageNamespaces = $panel->getPageNamespaces();

    foreach ($pageDirectories as $pageIndex => $pageDirectory) {
        if (str($pageDirectory)->startsWith(base_path('vendor'))) {
            unset($pageDirectories[$pageIndex], $pageNamespaces[$pageIndex]);
        }
    }

    $namespace = (\count($pageNamespaces) > 1)
        ? select(
            label: 'Which namespace would you like to create this in?',
            options: $pageNamespaces,
        )
        : (Arr::first($pageNamespaces) ?? 'App\\Admin\\Pages');

    $path = (\count($pageDirectories) > 1)
        ? $pageDirectories[array_search($namespace, $pageNamespaces, true)]
        : (Arr::first($pageDirectories) ?? app_path('Admin/Pages/'));

    $path = (string) str($page)
        ->prepend('/')
        ->prepend($path)
        ->replace('\\', '/')
        ->replace('//', '/')
        ->append('.php');

    if (!$this->option('force') && $this->checkForCollision([$path])) {
        return self::INVALID;
    }

    $potentialCluster = (string) str($namespace)->beforeLast('\\Pages');
    $clusterAssignment = null;
    $clusterImport = null;

    if (
        class_exists($potentialCluster)
        && is_subclass_of($potentialCluster, Cluster::class)
        && filled($potentialCluster)
    ) {
        $clusterAssignment = $this->indentString(
            PHP_EOL.PHP_EOL.'protected static ?string $cluster = '.class_basename(
                $potentialCluster,
            ).'::class;',
        );

        $clusterImport = "use {$potentialCluster};".PHP_EOL;
    }

    $model = $this->getModelStmt();

    $this->copyStub(
        filesystem: $filesystem,
        targetPath: $path,
        replacements: [
            'class' => $pageClass,
            'clusterAssignment' => $clusterAssignment,
            'clusterImport' => $clusterImport,
            'namespace' => $namespace.($pageNamespace !== '' ? "\\{$pageNamespace}" : ''),
            'model' => $model,
        ],
    );

    $this->components->info("Admin tree page [{$path}] created successfully.");

    return self::SUCCESS;
}
```

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

### Header::configureAction() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/header.md

Configures the CreateAction, handling both plain model classes and scoped QueryBuilder instances.

```php
private function configureAction(CreateAction $action): void
{
    $model = $this->component::getModel();

    if ($this->component::getModel() instanceof QueryBuilder) {
        $action
            ->model($model->getModel()::class)
            ->mutateFormDataUsing(
                static fn (array $data): array => [
                    ...$data,
                    ...$model->getModel()->getAttributes(),
                ],
            )
            ->using(static function (array $data) use ($model): Model {
                /** @var class-string<Model> $modelClass */
                $modelClass = $model->getModel()::class;

                $parent = $modelClass::query()->find($data['parent_id']);
                unset($data['parent_id']);

                return $modelClass::create(
                    attributes: $data,
                    parent: $parent,
                );
            });

        return;
    }

    $action->model($model);
}
```

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

### Run make:filament-tree-page command

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/make-tree-page-command.md

Shows three ways to run the make:filament-tree-page command: interactive, fully positional, and with panel and force options.

```bash
# interactive
php artisan make:filament-tree-page

# fully positional
php artisan make:filament-tree-page MenuPage "App\Models\AwesomeModel"

# attach to a specific panel and overwrite
php artisan make:filament-tree-page MenuPage AwesomeModel --panel=admin --force
```

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

### Row::infolist()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/row.md

Configures the infolist for the row using the provided Infolist instance. It sets the record, schema, and view.

```php
public function infolist(Infolist $infolist): Infolist
{
    return $infolist
        ->record($this->row)
        ->schema($this->component::getInfolistColumns())
        ->view('filament-tree::infolist');
}
```

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

### Publish configuration file

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/configuration.md

Command to publish the package configuration file to your application's config directory.

```bash
php artisan vendor:publish --tag="filament-tree-config"
```

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

### Publish Views

Source: https://github.com/15web/filament-tree/blob/main/README.md

Use the artisan command to publish the package views.

```bash
php artisan vendor:publish --tag="filament-tree-views"
```

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

### Prepare model with NodeTrait and InteractsWithTree

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/README.md

Prepare the model by using NodeTrait and InteractsWithTree, and define getTreeLabelAttribute to return the label attribute.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Kalnoy\Nestedset\NodeTrait;
use Studio15\FilamentTree\Concerns\InteractsWithTree;

class AwesomeModel extends Model
{
    use NodeTrait;
    use InteractsWithTree;

    public static function getTreeLabelAttribute(): string
    {
        return 'title';
    }
}
```

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

### Manual usage of Helpers::treeKey() in PHP

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/helpers.md

Demonstrates calling the helper directly in application code, producing a key like "1.1.2.-1" for a root leaf.

```php
use Studio15\FilamentTree\Helpers;
use App\Models\AwesomeModel;

$node = AwesomeModel::find(1);
$key = Helpers::treeKey($node); // e.g. "1.1.2.-1" for a root leaf

echo $key;
```

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

### Header::createAction() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/header.md

Builds the 'New node' action, including the ParentSelect field and the after hook for re-rendering.

```php
public function createAction(): CreateAction
{
    $model = $this->component::getModel();

    $action = CreateAction::make()
        ->after(fn (): Event => $this->dispatch('filament-tree-updated'));

    $this->configureAction($action);

    $action->form([
        ParentSelect::make($model instanceof QueryBuilder ? $model : $model::query()),
        ...$this->component::getCreateForm(),
    ]);

    return $action;
}
```

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

### Prepare clean model for tree structure

Source: https://github.com/15web/filament-tree/blob/main/README.md

Steps to prepare a model without existing nested set integration, including trait implementation, migration creation, and migration execution.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Kalnoy\Nestedset\NodeTrait;
use Studio15\FilamentTree\Concerns\InteractsWithTree;

class AwesomeModel extends Model
{
    use NodeTrait;
    use InteractsWithTree;
```

```shell
php artisan make:migration add_tree_to_awesome_model --table=awesome_model_table
```

```php
return new class extends Migration
{
    public function up(): void
    {
        Schema::table('awesome_model_table', function (Blueprint $table) {
            $table->nestedSet();
        });
    }
```

```shell
php artisan migrate
```

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

### Source file tree at tag 1.0.3

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/README.md

List of source files at tag 1.0.3 (commit a9fd9d8) that were read for documentation.

```text
src/FilamentTreeServiceProvider.php
src/Helpers.php
src/MoveItem.php
src/Commands/MakeTreePageCommand.php
src/Components/{Footer,Header,Move,Row,TreePage}.php
src/Components/Form/ParentSelect.php
src/Concerns/InteractsWithTree.php
src/Exception/InvalidModel.php
config/filament-tree.php
resources/views/*.blade.php
resources/lang/en/translations.php
resources/dist/filament-tree.min.{js,css}
stubs/TreePage.stub
```

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

### copyStub() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/make-tree-page-command.md

Copies a stub file to the target path, replacing placeholders like {{ class }} with provided values. Uses the app's stubs/TreePage.stub if it exists, otherwise falls back to the package default stub.

```php
private function copyStub(
    Filesystem $filesystem,
    string $targetPath,
    array $replacements = [],
): void {
    $stubPath = base_path('stubs/TreePage.stub');

    if (!$this->fileExists($stubPath)) {
        $stubPath = $this->getDefaultStubPath().'/TreePage.stub';
    }

    $stub = str($filesystem->get($stubPath));

    foreach ($replacements as $key => $replacement) {
        $stub = $stub->replace("{{ {$key} }}", $replacement);
    }

    $this->writeFile($targetPath, (string) $stub);
}
```

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

### getPanel() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/make-tree-page-command.md

Returns the panel specified by the --panel option, the only registered panel, or prompts the user to select among all panels. Defaults to the default panel when prompting.

```php
private function getPanel(): Panel
{
    $panel = $this->option('panel');

    if ($panel) {
        return Filament::getPanel($panel, isStrict: false);
    }

    $panels = Filament::getPanels();

    if (\count($panels) === 1) {
        return Arr::first($panels);
    }

    $panelIndex = select(
        label: 'Which panel would you like to create this in?',
        options: array_map(
            static fn (Panel $panel): string => $panel->getId(),
            $panels,
        ),
        default: Filament::getDefaultPanel()->getId(),
    );

    return $panels[$panelIndex];
}
```

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

### Publish Translations

Source: https://github.com/15web/filament-tree/blob/main/README.md

Use the artisan command to publish translation files for the package.

```bash
php artisan vendor:publish --tag="filament-tree-translations"
```

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

### Generate Filament tree page

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/README.md

Generate a Filament tree page using the artisan command.

```bash
php artisan make:filament-tree-page
```

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

### Default configuration file

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/configuration.md

The default structure of the config/filament-tree.php file, which returns a plain array of boolean configuration options.

```php
<?php

declare(strict_types=1);

return [
    // You can restrict to delete nodes having children items.
    'allow-delete-parent' => false,

    /*
     * You can restrict to delete root nodes,
     * even if 'allow-delete-parent' is true.
     */
    'allow-delete-root' => false,

    /*
     * If you want to see edit form as compact one,
     * you able to remove parent's select from it.
     * You still can drag'n'drop the nodes.
     */
    'show-parent-select-while-edit' => true,
];
```

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

### Row::infolist()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/row.md

Configures the infolist for the row's record using the component's getInfolistColumns() schema and the filament-tree::infolist view.

```APIDOC
## Row::infolist()

### Description
Configures the infolist for the row's record using the component's getInfolistColumns() schema and the filament-tree::infolist view.

### Method
infolist

### Signature
public function infolist(Infolist $infolist): Infolist

### Parameters
- **$infolist** (Filament\Infolists\Infolist) - Required - Infolist instance provided by the InteractsWithInfolists contract.

### Return Type
Filament\Infolists\Infolist - Renders the page's getInfolistColumns() entries for this row's record via the filament-tree::infolist view.

### Example
```php
public function infolist(Infolist $infolist): Infolist
{
    return $infolist
        ->record($this->row)
        ->schema($this->component::getInfolistColumns())
        ->view('filament-tree::infolist');
}
```
```

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

### Move::render() implementation

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/move.md

Renders the empty filament-tree::move view.

```php
public function render(): View
{
    return view('filament-tree::move');
}
```

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

### Move::render()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/move.md

Renders the 'filament-tree::move' view.

```APIDOC
## Move::render()

### Description
Renders the 'filament-tree::move' view.

### Method
PHP method

### Signature
```php
public function render(): View
```

### Parameters
None.

### Return Type
`Illuminate\Contracts\View\View` — renders the empty `filament-tree::move` view.
```

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

### Header::render() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/header.md

Renders the header view for the component.

```php
public function render(): View
{
    return view('filament-tree::header');
}
```

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

### MoveItem::__invoke() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/move-item.md

Executes the node move. Handles three cases: same parent (sibling reorder), move to root, and new parent (re-parent and shift). Throws ModelNotFoundException if the parent node does not exist.

```php
public function __invoke(Model $node, ?int $parent, int $from, int $to): void
{
    if ($parent === $node->getAttribute(NestedSet::PARENT_ID)) {
        $this->moveItem($node, $from, $to);

        return;
    }

    if ($parent === null) {
        $this->moveToRoot(
            node: $node,
            position: $to,
        );

        return;
    }

    /** @var Model $parentNode */
    $parentNode = $node->query()->findOrFail($parent);

    $parentNode->prependNode($node);
    if ($to > 0) {
        $node->down($to);
    }
}
```

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

### Register service provider in bootstrap/providers.php

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/service-provider.md

Manual registration in bootstrap/providers.php for Laravel 11/12 style. Add the service provider class to the providers array.

```php
<?php

return [
    // ...
    Studio15\FilamentTree\FilamentTreeServiceProvider::class,
];
```

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

### MoveItem::moveToRoot() private method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/move-item.md

Moves a node to the root level. Saves as root, refreshes, counts siblings, and shifts up to the target position.

```php
private function moveToRoot(Model $node, int $position): void
{
    $node->saveAsRoot();

    $siblingsCount = $node->refresh()->siblings()->count();
    $shift = $siblingsCount - $position;

    $node->up($shift);
}
```

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

### TreePage::getCreateForm() abstract method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/tree-page.md

Abstract method returning form fields for the create modal. Parent select is prepended automatically by Header::createAction().

```php
/**
 * @return list<Field>
 */
abstract public static function getCreateForm(): array;
```

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

### ParentSelect::make() method implementation

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/parent-select.md

Builds a Filament `Select` field for choosing a parent node. Options are resolved lazily with depth indentation, and the current record and its descendants are disabled to prevent cycles. Throws `RuntimeException` if a node's depth is negative.

```php
public static function make(QueryBuilder $query): Select
{
    $buildTitle = static function (Model $item) use ($query): string {
        $title = $item->getAttribute(
            $query->getModel()::class::getTreeLabelAttribute(),
        );

        $depth = $item->getAttribute('depth');
        if ($depth < 0) {
            throw new RuntimeException('The tree is corrupted, please Fix tree');
        }

        $prefix = Str::repeat(
            string: '--',
            times: $depth,
        );

        return trim("{$prefix} {$title}");
    };

    $options = static fn (): array => $query
        ->withDepth()
        ->defaultOrder()
        ->get()
        ->mapWithKeys(static fn (Model $item): array => [
            $item->getKey() => $buildTitle($item),
        ])
        ->all();

    return Select::make(NestedSet::PARENT_ID)
        ->label(__('filament-tree::translations.parent_node'))
        ->options($options)
        ->disableOptionWhen(static function (?Model $record, string $value): bool {
            $modelValue = (string) $record?->getKey();

            if ($modelValue === $value) {
                return true;
            }

            if ($record !== null) {
                return $record->descendants->contains($value);
            }

            return false;
        })
        ->searchable()
        ->nullable()
        ->native(false)
        ->preload(false);
}
```

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

### Blade usage of Helpers::treeKey()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/helpers.md

Shows how the helper is used in a Blade view to key a Livewire row component, passing the row model and its key.

```blade
<livewire:filament-tree::row
        :component="static::class"
        :row="$row"
        :row-id="$row->getKey()"
        :key="Studio15\FilamentTree\Helpers::treeKey($row)"
/>
```

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

### Error handling for corrupted tree depth

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/parent-select.md

Demonstrates catching the `RuntimeException` thrown when the tree is corrupted (depth < 0) during option resolution, and suggests running `AwesomeModel::fixTree()` to repair it.

```php
try {
    $options = ParentSelect::make(AwesomeModel::query())->getOptions();
} catch (\RuntimeException $e) {
    // 'The tree is corrupted, please Fix tree'
    // run AwesomeModel::fixTree();
}
```

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

### Class declaration of `MakeTreePageCommand` with `AsCommand` attribute

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/make-tree-page-command.md

Declares the `make:filament-tree-page` Artisan command class. The class uses `CanIndentStrings` and `CanManipulateFiles` traits, and defines `$signature` with optional `name` and `model` arguments and `--panel` and `--force` options.

```php
#[AsCommand(name: 'make:filament-tree-page', description: 'Create a new Admin Eloquent tree page class')]
final class MakeTreePageCommand extends Command
{
    use CanIndentStrings;
    use CanManipulateFiles;

    protected $signature = 'make:filament-tree-page {name?} {model?} {--panel=} {--F|force}';

    // ...
}
```

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

### Define Infolist Columns

Source: https://github.com/15web/filament-tree/blob/main/README.md

Implement getInfolistColumns in your page to display meta information next to the node label using Filament Infolist entries.

```php
public static function getInfolistColumns(): array
{
    return [
        TextEntry::make('description')->label(fn(Category $record, Get $get) => $record->description !== null ? 'Desc' : ''),
        IconEntry::make('is_published')->boolean()->label(''),
    ];
} 
```

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

### Concrete method getTreeCaption() default implementation

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/interacts-with-tree.md

The default implementation of getTreeCaption() returns null, meaning no caption is shown. Override this method to display an optional second line under the node label.

```php
public function getTreeCaption(): ?string
{
    return null;
}
```

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

### TreePage::getInfolistColumns() default implementation

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/tree-page.md

Default implementation returning an empty array. Override to display meta information next to node labels, such as TextEntry or IconEntry. The entries are rendered by Row::infolist() through the filament-tree::infolist view.

```php
/**
 * @return list<Entry>
 */
public static function getInfolistColumns(): array
{
    return [];
}
```

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

### Footer::render()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/footer.md

Renders the footer view for the component.

```APIDOC
## Footer::render()

### Description
Renders the footer view for the component.

### Method
Render

### Endpoint
N/A (Livewire component method)

### Parameters
None

### Return Type
`Illuminate\Contracts\View\View`

### Behavior
Returns the view `filament-tree::footer`.
```

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

### Register service provider via composer.json

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/service-provider.md

Alternative registration via Composer's extra.laravel.providers entry in composer.json. This auto-discovers the service provider.

```json
"extra": {
    "laravel": {
        "providers": [
            "Studio15\\FilamentTree\\FilamentTreeServiceProvider"
        ]
    }
}
```

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

### Override getTreeCaption() to display a description

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/interacts-with-tree.md

Shows how to override getTreeCaption() on the model to return a description, e.g., the model's description attribute.

```php
public function getTreeCaption(): ?string
{
    return $this->description;
}
```

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

### Helpers::treeKey() method implementation

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/helpers.md

Static method that builds a dot-separated key from the model's primary key, _lft, _rgt, and parent_id (or -1 if no parent). Returns a non-empty string.

```php
/**
 * @return non-empty-string
 */
public static function treeKey(Model $model): string
{
    $attributes = $model->only([
        $model->getKeyName(),
        NestedSet::LFT,
        NestedSet::RGT,
    ]);

    $attributes[] = $model->getAttribute(NestedSet::PARENT_ID) ?: -1;

    return implode(
        separator: '.',
        array: array_values($attributes),
    );
}
```

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

### Move::moveTreeItem() implementation

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/move.md

Handles the movement of tree items by normalizing input, invoking the MoveItem action, and dispatching refresh events or error notifications.

```php
/**
 * @param positive-int $id
 * @param numeric-string|null $ancestor
 * @param numeric-string|null $parent
 * @param non-negative-int $from
 * @param non-negative-int $to
 */
#[On('filament-tree-moved')]
public function moveTreeItem(int $id, ?string $ancestor, ?string $parent, int $from, int $to): void
{
    if ($ancestor === '') {
        $ancestor = null;
    }

    if ($parent === '') {
        $parent = null;
    }

    $modelClass = $this->component::getModel();

    $query = $modelClass instanceof QueryBuilder
        ? $modelClass
        : $modelClass::query();

    /** @var Model $node */
    $node = $query->findOrFail($id);

    try {
        app(MoveItem::class)(
            node: $node,
            parent: $parent === null ? null : (int) $parent,
            from: $from,
            to: $to,
        );
    } catch (LogicException $e) {
        Notification::make()
            ->danger()
            ->title($e->getMessage())
            ->send();

        return;
    }

    $this->dispatch("filament-tree-refresh.{$id}");

    if ($ancestor !== null) {
        $this->dispatch("filament-tree-refresh.{$ancestor}");
    }

    if ($parent !== null) {
        $this->dispatch("filament-tree-refresh.{$parent}");
    }

    // Update root tree
    if ($ancestor === null || $parent === null) {
        $this->dispatch('filament-tree-updated');
    }

    Notification::make()
        ->success()
        ->title(__('filament-tree::translations.item_moved'))
        ->send();
}
```

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

### TreePage::refresh() event listener

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/tree-page.md

Livewire event listener for the global 'filament-tree-updated' event. The empty body forces a re-render of the whole page, i.e., a full tree rebuild.

```php
#[On('filament-tree-updated')]
public function refresh(): void
{
    // Re-render component
}
```

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

### Footer::render() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/footer.md

Render method that returns the view for the footer component, specifically 'filament-tree::footer'.

```php
public function render(): View
{
    return view('filament-tree::footer');
}
```

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

### TreePage::getModel() abstract method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/tree-page.md

Abstract method returning a model class or scoped query. Must be implemented in subclasses.

```php
/**
 * Model class or scoped query
 *
 * @see https://github.com/lazychaser/laravel-nestedset#scoping
 *
 * @return class-string<Model>|QueryBuilder
 */
abstract public static function getModel(): QueryBuilder|string;
```

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

### TreePage::getCreateForm()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/tree-page.md

Abstract method that returns the form fields for the create modal. Parent select is prepended automatically by Header::createAction().

```APIDOC
## TreePage::getCreateForm()

### Description
Returns a list of Filament form fields for the create modal. The parent select is prepended automatically by `Header::createAction()` (`Header.php:40-45`).

### Method
`abstract public static function getCreateForm(): array`

### Parameters
None.

### Return Type
`list<Filament\Forms\Components\Field>` — form fields for the create modal.
```

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

### MoveItem::moveItem() private method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/move-item.md

Reorders a node among its siblings. Computes the shift and calls up() or down() accordingly. No-op when the shift is zero.

```php
private function moveItem(Model $node, int $from, int $to): void
{
    $shift = $from - $to;
    if ($shift === 0) {
        return;
    }

    if ($from > $to) {
        $node->up($shift);

        return;
    }

    $node->down($shift);
}
```

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

### TreePage::getInfolistColumns()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/tree-page.md

Static method to define infolist entries displayed next to each node label in the tree page. Override to show additional metadata like descriptions or status icons.

```APIDOC
## TreePage::getInfolistColumns()

### Description
Returns a list of Filament Infolist entries to be rendered next to each node label in the tree page. Override this static method to display meta information such as a description or an icon for a boolean field.

### Method
Static method

### Signature
`public static function getInfolistColumns(): array`

### Parameters
None.

### Return Type
`list<Filament\Infolists\Components\Entry>` — Infolist entries rendered next to each node label.

### Example
```php
use Filament\Infolists\Components\TextEntry;
use Filament\Infolists\Components\IconEntry;
use App\Models\Category;
use Filament\Forms\Get;

public static function getInfolistColumns(): array
{
    return [
        TextEntry::make('description')->label(fn (Category $record, Get $get) => $record->description !== null ? 'Desc' : ''),
        IconEntry::make('is_published')->boolean()->label(''),
    ];
}
```
```

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

### parsePage() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/make-tree-page-command.md

Prompts for a page name if not provided, validates it against allowed characters, and normalizes it by trimming slashes and converting forward slashes to backslashes. Throws InvalidArgumentException for invalid characters.

```php
public function parsePage(): string
{
    $pageName = $this->argument('name') ?? text(
        label: 'What is the tree page name?',
        placeholder: 'MenuPage',
        required: true,
    );

    if (preg_match('([^A-Za-z0-9_/\\\\])', $pageName)) {
        throw new InvalidArgumentException('Page name contains invalid characters.');
    }

    return (string) str($pageName)
        ->trim('\\/')
        ->replace('/', '\\');
}
```

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

### TreePage::mount()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/tree-page.md

Livewire mount hook that validates the model contract before the page renders. Throws an InvalidModel exception if the model does not use the required traits, which the Livewire framework surfaces as a page failure.

```APIDOC
## TreePage::mount()

### Description
Livewire mount hook that validates the model contract before the page renders. Throws an InvalidModel exception if the model does not use the required traits, which the Livewire framework surfaces as a page failure.

### Method
Instance method (Livewire lifecycle hook)

### Signature
`public function mount(): void`

### Parameters
None.

### Return Type
`void`

### Throws
- `Studio15\FilamentTree\Exception\InvalidModel` — If the model (or the model behind a QueryBuilder) does not use `Kalnoy\Nestedset\NodeTrait`.
- `Studio15\FilamentTree\Exception\InvalidModel` — If the model does not use `Studio15\FilamentTree\Concerns\InteractsWithTree`.
```

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

### Define create and edit forms

Source: https://github.com/15web/filament-tree/blob/main/README.md

Implement getCreateForm and getEditForm methods in your tree page class to define the fields for managing tree records.

```php
public static function getCreateForm(): array
{
    return [
        TextInput::make('title')->required(),
        TextInput::make('slug')->required()->unique(ignoreRecord: true),
    ];
}

public static function getEditForm(): array
{
    return [
        TextInput::make('title')->required(),
        TextInput::make('slug')->required()->unique(ignoreRecord: true),
        Toggle::make('is_published'),
        TextInput::make('description')->nullable(),
    ];
}
```

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

### FilamentTreeServiceProvider class declaration

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/service-provider.md

Class declaration for the FilamentTree service provider. Extends Spatie's PackageServiceProvider and defines the static $name property used for config, views, translations, and asset scoping.

```php
/**
 * FilamentTree Plugin Service Provider
 *
 * @author 15web.ru <info@15web.ru>
 */
final class FilamentTreeServiceProvider extends PackageServiceProvider
{
    public static string $name = 'filament-tree';

    // ...
}
```

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

### Command signature

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/make-tree-page-command.md

The Artisan command signature as used on the command line. Shows the optional positional arguments `name` and `model`, and the `--panel` and `-F|--force` options.

```text
make:filament-tree-page {name?} {model?} {--panel=} {--F|force}
```

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

### Move component class declaration

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/move.md

The class definition for the Move component, which extends the Livewire Component class.

```php
final class Move extends Component
{
    /**
     * @var class-string<TreePage>
     */
    public string $component;

    // ...
}
```

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

### Row::render()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/row.md

Renders the row component using the filament-tree::row view, which handles recursive rendering of child components.

```php
public function render(): View
{
    return view('filament-tree::row');
}
```

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

### ParentSelect::make()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/parent-select.md

Static method that builds a Filament Select field for choosing a parent node. It accepts a nested-set query, renders options with depth indentation, and disables the current record and its descendants to prevent cycles.

```APIDOC
## ParentSelect::make()

### Description
Static method that creates a Filament `Select` field for picking a node's parent. It renders the tree with depth indentation, disables illegal options (self and own descendants), and is used both in create and edit forms.

### Method
`public static function make(QueryBuilder $query): Select`

### Parameters
- **$query** (`Kalnoy\Nestedset\QueryBuilder`) - Required - The nested-set query (or scoped query) whose nodes become options. When the owning page returns a plain model class, callers pass `Model::query()`; `Row::editAction()` passes the scoped builder when present.

### Return Type
`Filament\Forms\Components\Select`

### Throws
- `RuntimeException` - If a node's `depth` attribute is `< 0` (corrupted tree). Message: `The tree is corrupted, please Fix tree`.

### Returned Field Configuration
- `Select::make('parent_id')` - Bound to the nested-set `parent_id` attribute (`Kalnoy\Nestedset\NestedSet::PARENT_ID`).
- `->label(__('filament-tree::translations.parent_node'))` - Label from translations (`Parent tree item`).
- `->options($options)` - Options resolved lazily: `withDepth()->defaultOrder()->get()`, keyed by node key, titled `--…-- title` by depth.
- `->disableOptionWhen(...)` - Disables the current record itself and any of its descendants (prevents cycles).
- `->searchable()` - Searchable select.
- `->nullable()` - Empty value allowed → root node.
- `->native(false)` - Rendered as a styled (non-native) select.
- `->preload(false)` - Does not preload options; resolved on demand.

### Example
```php
// Typical consumer — an edited node is disabled along with its
// descendants, so a node can never be its own ancestor.
$select = ParentSelect::make(AwesomeModel::query());

// options will look like:
// 1 => ' Parent A'
// 2 => '-- Child A.1'
// 3 => '-- Child A.2'
// 4 => ' Parent B'
```

### Usage
Called from the packaged components; usable directly in your own pages:

```php
use Studio15\FilamentTree\Components\Form\ParentSelect;
use App\Models\AwesomeModel;

// In a Filament form schema outside the tree page:
ParentSelect::make(AwesomeModel::query())
    ->required();                    // chain Filament field methods further
```

### Error Handling
A depth-corrupted tree throws on option resolution; the page provides the Fix tree button to repair it:

```php
try {
    $options = ParentSelect::make(AwesomeModel::query())->getOptions();
} catch (\RuntimeException $e) {
    // 'The tree is corrupted, please Fix tree'
    // run AwesomeModel::fixTree();
}
```
```

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

### MoveItem direct usage

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/move-item.md

Direct use of the MoveItem service from application code, e.g. in custom drag handlers or reordering logic. It moves a node to a new parent and position, using the node's key as the parent argument.

```php
use Studio15\FilamentTree\MoveItem;
use App\Models\AwesomeModel;

$node = AwesomeModel::find(42);
$newParent = AwesomeModel::find(7);

app(MoveItem::class)(
    node: $node,
    parent: $newParent?->getKey(),
    from: 2,
    to: 0,
);
```

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

### getModelStmt() method

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/make-tree-page-command.md

Returns a PHP statement returning the model class, or a placeholder if the model argument is blank or the class does not exist. Emits a warning when the class is not found.

```php
private function getModelStmt(): string
{
    $placeholder = '// TODO: Set tree model';

    $modelName = $this->argument('model') ?? text(
        label: 'What is the model class?',
        placeholder: 'MenuItem',
    );

    if (blank($modelName)) {
        return $placeholder;
    }

    $modelClass = $this->parseModel($modelName);

    if (!class_exists($modelClass)) {
        $this->warn("Model '{$modelClass}' not found");

        return $placeholder;
    }

    return "return {$modelClass}::class;";
}
```

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

### Helpers::treeKey()

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/helpers.md

Builds a stable, unique string key for a tree node by composing its primary key, _lft, _rgt, and parent_id (or -1 if no parent) into a dot-separated string. This key is used as the Livewire :key for Row components.

```APIDOC
## Helpers::treeKey()

### Description
Builds a stable, unique string key for a tree node by composing its primary key, _lft, _rgt, and parent_id (or -1 if no parent) into a dot-separated string. This key is used as the Livewire :key for Row components.

### Method
Static method

### Signature
public static function treeKey(Model $model): string

### Parameters
- **$model** (Illuminate\Database\Eloquent\Model) - Required - A nested-set node.

### Return Type
string (non-empty-string)

### Example
For a node with id = 12, _lft = 1, _rgt = 2 and no parent, the result is the non-empty string "12.1.2.-1".

### Usage
Primarily consumed by Blade views to key rows:

```blade
<livewire:filament-tree::row
        :component="static::class"
        :row="$row"
        :row-id="$row->getKey()"
        :key="Studio15\FilamentTree\Helpers::treeKey($row)"
/>
```

Manual use in application code:

```php
use Studio15\FilamentTree\Helpers;
use App\Models\AwesomeModel;

$node = AwesomeModel::find(1);
$key = Helpers::treeKey($node); // e.g. "1.1.2.-1" for a root leaf

echo $key;
```

### Notes
The key is guaranteed non-empty: the minimum it contains is the primary key itself, so implode() always yields at least one character. Since _lft/_rgt change on every structural mutation, the key changes whenever the node is re-parented or re-ordered, which is what makes Livewire discard and rebuild the affected Row components.
```

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

### Mount the move component in Blade

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/move.md

Include this component in your tree.blade.php file to enable move functionality. It is driven by JS drop events and requires no further application-level calls.

```blade
<livewire:filament-tree::move :component="static::class" />
```

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

### Usage in a Filament form schema

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/parent-select.md

Shows how to use `ParentSelect::make()` directly in a Filament form schema outside the tree page, with the ability to chain further Filament field methods like `->required()`.

```php
use Studio15\FilamentTree\Components\Form\ParentSelect;
use App\Models\AwesomeModel;

// In a Filament form schema outside the tree page:
ParentSelect::make(AwesomeModel::query())
    ->required();                    // chain Filament field methods further
```

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

### Generated TreePage class

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/make-tree-page-command.md

The generated file from stubs/TreePage.stub. Extends TreePage and requires implementing getModel, getCreateForm, getEditForm, and getInfolistColumns.

```php
<?php

namespace App\Admin\Pages;

use Kalnoy\Nestedset\QueryBuilder;
use Studio15\FilamentTree\Components\TreePage;

class MenuPage extends TreePage
{
    public static function getModel(): string|QueryBuilder
    {
        return App\Models\AwesomeModel::class;
    }

    public static function getCreateForm(): array
    {
        return [
            //
        ];
    }

    public static function getEditForm(): array
    {
        return [
            //
        ];
    }

    public static function getInfolistColumns(): array
    {
        return [
            //
        ];
    }
}
```

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

### Class declaration for Helpers

Source: https://github.com/15web/filament-tree/blob/main/_autodocs/api-reference/helpers.md

Declares the final class Helpers with a placeholder for its contents. The class is final and contains static methods.

```php
final class Helpers
{
    // ...
}
```
Tokens:
Raw