Weave Code
Laravel Ltree Laravel Package
umbrellio/laravel-ltree
Laravel integration for PostgreSQL ltree that brings hierarchical tree data to Eloquent models. Provides migrations, path helpers, and query scopes for ancestors, descendants, and subtree traversal, making tree-structured data easy to store and search.
LTree Extension (PostgreSQL) for Laravel
Frequently asked questions about Laravel Ltree
- How do I install umbrellio/laravel-ltree in a Laravel application?
- Install it with composer require umbrellio/laravel-ltree, then enable the PostgreSQL ltree extension in a migration. Add the LTreeModel trait to your model and define the parent and path column contract. Finally create the ltree column with the provided createLtreeColumn migration helper and backfill existing rows. The whole setup is additive, so existing reads and writes on your parent column can continue during rollout.
- Does umbrellio/laravel-ltree work with MySQL, MariaDB, or SQLite?
- No. The package is a thin adapter over PostgreSQL's native ltree type and relies on operators such as @>, <@, ~, and @ that other engines do not provide. If MySQL, MariaDB, or SQLite appear anywhere in your pipeline, including local development or CI, this package is a disqualifier for that environment. Make sure every environment, read replica, and backup/restore path runs PostgreSQL with ltree available.
- How do I query ancestors, descendants, and subtrees with this Laravel package?
- The package ships Eloquent query scopes that wrap the native ltree operators, so ancestor, descendant, and subtree lookups chain like any other query builder call. You do not need to write raw SQL or recursive CTEs for typical traversal queries. Because the scopes compose with normal where clauses, you can combine hierarchy filters with your existing model constraints.
- Which Laravel and PHP versions does umbrellio/laravel-ltree support?
- The package targets modern Laravel releases, but you should treat the README's constraint matrix as authoritative for both Laravel and PHP versions. Check those constraints against your pinned composer.json before committing to an upgrade path. On the database side, ltree has shipped with PostgreSQL since 8.3, so database version risk is generally low.
- How do I create an ltree column and index in a Laravel migration?
- Use the package's createLtreeColumn migration helper to add the column, then create a GiST index on it. Use the GiST operator classes for ltree; an index created without them will degrade to sequential scans on hierarchy queries. On large existing tables, build the index concurrently to avoid locking. Enabling the extension should live in its own migration so each step stays independently reversible.
- What characters are allowed in ltree labels and how should I handle user slugs?
- ltree labels must match the pattern A-Za-z0-9_ and are limited to 256 characters per label, with roughly 65KB for the entire path. User-facing slugs, tenant names, and URL segments therefore need normalization and sanitization before they become path labels. If your slugs contain hyphens, dots, or unicode, convert them to safe labels or store a separate display slug column.
- How do I order sibling nodes when using PostgreSQL ltree in Laravel?
- ltree has no native sibling ordering, so the package cannot give you ordered children out of the box. The usual approaches are encoding a sortable prefix in the labels themselves or maintaining a separate sort key column alongside the path. Decide on that convention early, because changing it later means rewriting every descendant path.
- What happens performance-wise when I move a subtree to a new parent?
- A subtree move rewrites the path of every descendant row, so it is an O(n) write proportional to the size of the moved subtree. Parallel moves are a concurrency hazard, so serialize them with a lock or queue if moves can overlap. For read-heavy trees with infrequent restructuring this trade-off is usually acceptable, but measure it against your expected move frequency.
- Is umbrellio/laravel-ltree actively maintained and what if it gets abandoned?
- It is a small package from a small commercial maintainer, with an active release cadence through mid-2025 but a real single-maintainer bus factor. Because the code surface is thin, glue-level work around an Eloquent trait and migration helper, vendoring or forking it is a weekend job rather than a quarter-long effort. Budget for that possibility and pin your version in composer.lock.
- How do I test a Laravel app that uses ltree in CI?
- Your CI database must be PostgreSQL with the ltree extension enabled, and it must not silently fall back to SQLite or MySQL. Run the extension-enabling migration as part of your test bootstrap, and assert that hierarchy scopes return expected results rather than just checking that queries do not error. If you backfilled from an adjacency list, add a reconciliation query comparing row counts per depth in both representations.
Weaver
How can I help you explore Laravel packages today?