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

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