larasup/reference

Hierarchical reference books (dictionaries) for Laravel

v1.0.0 2026-04-09 14:11 UTC

Requires

• php: ^8.2
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• tree
• Reference
• dictionary
• laravel
• hierarchical

README

Hierarchical reference books (dictionaries) for Laravel. Store key-value dictionaries with tree structure support.

Installation

composer require larasup/reference

The package uses Laravel auto-discovery, so the service provider will be registered automatically.

Publish the config (optional):

php artisan vendor:publish --tag=reference-config

Run migrations:

php artisan migrate

Configuration

// config/reference.php
return [
    'table_prefix' => 'reference_', // customize table names prefix
];

This will create reference_books and reference_items tables. Change the prefix to use different table names.

Usage

Via Facade

use Larasup\Reference\Facades\Reference;

// Create a book
$book = Reference::createBook('countries');

// Get or create (idempotent)
$book = Reference::getOrCreateBook('countries');

// Get by entity key
$book = Reference::getBook('countries');

// Add items
Reference::createItem($book, 'ru', ['name' => 'Russia', 'code' => 'RU']);
Reference::createItem($book, 'us', ['name' => 'United States', 'code' => 'US']);

// Hierarchical items
$europe = Reference::createItem($book, 'europe', ['name' => 'Europe'], sort: 1);
Reference::createItem($book, 'fr', ['name' => 'France'], parentId: $europe->id, sort: 1);
Reference::createItem($book, 'de', ['name' => 'Germany'], parentId: $europe->id, sort: 2);

// Get tree structure
$tree = Reference::getTree('countries');
// Returns root items with nested `children` relation loaded

Via Service (DI)

use Larasup\Reference\Services\ReferenceService;

class MyController
{
    public function __construct(
        private readonly ReferenceService $reference,
    ) {}

    public function index()
    {
        $tree = $this->reference->getTree('countries');
    }
}

API

ReferenceService

Method	Description
createBook(string $entity): Book	Create a new book. Throws if already exists.
getBook(string $entity): ?Book	Get book by entity key. Returns null if not found.
getOrCreateBook(string $entity): Book	Get existing or create new book.
createItem(Book\|int $book, string $uid, array $properties = [], ?int $parentId = null, ?int $sort = null): Item	Create an item in a book. Validates book existence, uid uniqueness, and parent ownership.
getTree(Book\|int\|string $book): Collection	Get all items as a tree. Accepts Book model, id, or entity string.

Models

Book — a named dictionary (entity is the unique key).

Item — an entry in a book with:

• uid — unique identifier within the book
• properties — JSON key-value data
• parent_id — optional parent for tree structures
• sort — optional ordering
• status — integer status flag (default: 1)

Validation

The service validates:

• Book entity uniqueness on creation
• Book existence when creating items by id
• Item uid uniqueness within the same book
• Parent item existence and ownership (must belong to the same book)

All validation errors throw Larasup\Reference\Exceptions\ReferenceException.

License

MIT