Filament Nested List Laravel Package

Getting Started

v1.2 is a small compatibility release: it adds Laravel 12 support and introduces no documented API changes. Treat it as an upgrade-safety release rather than a feature release.

Start by confirming version compatibility before upgrading:

composer require invaders-xx/filament-nested-list:^1.2
composer show invaders-xx/filament-nested-list

Check the package composer.json constraints for Laravel, Filament, and PHP. If you are still on Laravel 10/11, confirm v1.2 still supports your versions; if it narrowed constraints, stay on v1.1 until you upgrade.

Typical setup:

1. Install the package with Composer.
2. Register the package’s Filament plugin in the relevant panel provider, per the package README.
3. Publish config/assets/migrations only if the README instructs you to.
4. Wire your hierarchical model into the nested list UI.

The first practical use case is an admin-managed tree: categories, navigation menus, organisational units, documentation sections, or any parent/child model that needs drag-and-drop ordering.

Look first at:

• The README for the exact plugin class, config keys, and model requirements.
• The v1.1...v1.2 diff to confirm whether only Composer constraints changed.
• Your Filament panel provider and the target model’s parent/children relationships.

Implementation Patterns

Use the package as the UI layer for hierarchical CRUD, not as your domain model. Keep parent/child and ordering logic explicit in your application.

Common day-to-day patterns:

• Register the plugin only on panels that need tree management. Avoid enabling it globally if only one admin panel uses nested lists.
• Back the list with a model that has clear parent_id and sort/order columns, plus parent() and children() relationships.
• Use policies and panel tenancy consistently. Reordering is a write operation and should be authorised like any other update.
• Pair drag-and-drop reordering with transactional persistence. If your model uses nested sets or materialised paths, recalculate them after moves.
• Use the package inside Filament resources/pages for category managers, menu builders, and content trees. Keep resource forms for editing node metadata separate from the nested list screen used for structure and ordering.
• Add custom Filament actions for publish/unpublish, move, duplicate, or delete where the package exposes extension points.
• In multi-tenant apps, scope both the query and reorder operations by tenant. A tree should never display or mutate nodes outside the current tenant.
• For upgrades, add Laravel 11/12 and relevant Filament versions to CI. Run at least one smoke test that loads the nested list page and performs a reorder.
• Test authorisation and cycle prevention, not just rendering. A passing page load does not prove drag-and-drop persistence is safe.

A practical upgrade workflow:

composer update invaders-xx/filament-nested-list --with-dependencies
php artisan optimize:clear
php artisan about

Then manually verify: page loads, tree renders, drag-and-drop persists, policies still apply, and no frontend assets are stale.

Gotchas and Tips

• v1.2 only advertises Laravel 12 support. No breaking changes are called out, but compatibility releases often change Composer constraints. Check the diff and composer why-not before assuming a safe upgrade.
• Laravel 12 support does not automatically mean every Filament plugin in your stack is Laravel 12-ready. Align Filament, Livewire, and third-party plugins together.
• If Composer resolves an unexpected older/newer version, inspect the package constraints directly rather than relying on the release title.
• Nested ordering is prone to data integrity bugs. Prevent cycles, enforce sibling ordering, and wrap moves in transactions.
• Drag-and-drop failures are often authorisation, tenancy scoping, or missing order-column configuration rather than a frontend bug.
• Clear caches after structural changes if your application caches navigation, menus, or tree output.
• Re-publish assets only if the README or diff indicates frontend changes. v1.2 does not document any, so avoid unnecessary asset churn.
• When debugging, verify in this order: plugin registration, model relationships, sort column/config, policy/tenant scope, then frontend assets.
• Keep custom view overrides minimal. Compatibility releases are easier to absorb when you rely on documented extension points rather than copied package views.
• If you maintain older Laravel versions, pin to the last release that supports them and document the constraint in your upgrade plan.