Laravel Dynamic Menu

Menus dinâmicos e hierárquicos (N níveis) para Laravel, com controlo de permissões flexível e cache para leitura rápida sem joins.

O pacote é 100% independente: não depende de Spatie nem de nenhum outro pacote de permissões. Podes usá-lo num projeto simples sem permissões, com permissões por string, ou apontando para qualquer tabela de permissões do teu projeto.

Índice

• Requisitos
• Instalação
• Conceito central: os três modos de permissão
• Configuração
• Estrutura de um item de menu
• Uso
  • Ler a árvore completa
  • Filtrar pela permissão do utilizador
  • Renderizar em Blade
  • Criar itens
• Modos de permissão em detalhe
• Middleware
• Cache
• Seeder
• Testes
• Licença

Requisitos

Nota sobre Laravel 13 e PHP: o Laravel 13 exige PHP 8.3 no mínimo. Além disso, algumas versões de patch (13.3+) puxam componentes do Symfony 8 que exigem PHP 8.4. Se estiveres em PHP 8.3, considera fixar laravel/framework:^13.0 <13.3 até poderes atualizar o runtime. Em PHP 8.2 usa Laravel 11 ou 12.

Instalação

composer require gsebastiao/laravel-dynamic-menu

Publica a configuração (opcional, mas recomendado):

php artisan vendor:publish --tag=dynamic-menu-config

Corre as migrations (a tabela menu_items é registada automaticamente pelo pacote):

php artisan migrate

Se preferires versionar/editar a migration no teu projeto:

php artisan vendor:publish --tag=dynamic-menu-migrations

O Service Provider e a Facade Menu são registados automaticamente via package auto-discovery.

Conceito central: os três modos de permissão

Cada item de menu tem uma única coluna permission (nullable). Como ela é interpretada depende do permission_mode no config:

A mesma coluna carrega ora uma string ora um id — o config é que decide a leitura. Simples e flexível.

Configuração

Ficheiro config/dynamic-menu.php (resumo dos campos principais):

return [
    // 'none' | 'string' | 'id'
    'permission_mode' => env('DYNAMIC_MENU_PERMISSION_MODE', 'none'),

    // Usado apenas no modo 'id'. Aponta para QUALQUER tabela do teu projeto.
    'resolver' => [
        'table'  => 'permissions',
        'key'    => 'id',
        'column' => 'name',
    ],

    // Callback opcional que devolve as permissões do utilizador.
    // null => o pacote tenta $user->getAllPermissions() e faz fallback para [].
    'user_permissions' => null,

    'cache' => [
        'enabled' => true,
        'store'   => null,   // null = store default (podes pôr 'redis')
        'key'     => 'dynamic_menu',
        'ttl'     => null,   // null = forever
    ],

    'table' => 'menu_items',
    'model' => \Gsebastiao\DynamicMenu\Models\MenuItem::class,
];

Estrutura de um item de menu

Uso

Ler a árvore completa

Devolve todos os itens ativos, já aninhados, servidos da cache (sem joins):

use Gsebastiao\DynamicMenu\Facades\Menu;

$tree = Menu::tree();
// Collection de arrays; cada nó tem uma chave 'children' (array)

Filtrar pela permissão do utilizador

Devolve apenas os itens que o utilizador pode ver, de acordo com o modo configurado. Um pai é mantido se tiver filhos visíveis (evita "buracos" na navegação):

// Utilizador autenticado
$menu = Menu::forUser();

// Um utilizador específico
$menu = Menu::forUser($user);

// Ou passando as permissões diretamente
$menu = Menu::forUser(null, ['user.create', 'admin.access']);

No modo none, forUser() devolve simplesmente a árvore completa.

Renderizar em Blade

Cada nó é um array. Exemplo recursivo simples:

{{-- resources/views/partials/menu.blade.php --}}
<ul>
    @foreach ($items as $item)
        @if ($item['is_separator'])
            <li class="separator"><hr></li>
        @else
            <li>
                <a href="{{ $item['route'] ? (\Illuminate\Support\Str::startsWith($item['route'], ['http', '/']) ? $item['route'] : route($item['route'], $item['params'] ?? [])) : '#' }}"
                   target="{{ $item['target'] ?? '_self' }}">
                    @if ($item['icon']) <i class="icon-{{ $item['icon'] }}"></i> @endif
                    {{ $item['label'] }}
                    @if ($item['badge']) <span class="badge">{{ $item['badge'] }}</span> @endif
                </a>

                @if (!empty($item['children']))
                    @include('partials.menu', ['items' => $item['children']])
                @endif
            </li>
        @endif
    @endforeach
</ul>

{{-- No layout --}}
@include('partials.menu', ['items' => \Gsebastiao\DynamicMenu\Facades\Menu::forUser()])

Criar itens

use Gsebastiao\DynamicMenu\Models\MenuItem;

$admin = MenuItem::create([
    'name'       => 'admin',
    'label'      => 'Administração',
    'icon'       => 'shield',
    'order'      => 1,
    'permission' => 'admin.access', // no modo 'id' seria o id, ex.: '42'
]);

MenuItem::create([
    'parent_id'  => $admin->id,
    'name'       => 'admin.users',
    'label'      => 'Utilizadores',
    'route'      => 'admin.users.index',
    'order'      => 1,
    'permission' => 'users.view',
    'badge'      => 'novo',
    'params'     => ['tab' => 'active'],
]);

A cache é invalidada automaticamente sempre que gravas, apagas ou restauras um item.

Modos de permissão em detalhe

Modo none (default)

Nada a configurar. O campo permission é ignorado, Menu::tree() e Menu::forUser() devolvem tudo, e o middleware deixa passar sempre. Ideal para projetos simples.

// config/dynamic-menu.php
'permission_mode' => 'none',

Modo string

Guardas a permissão como texto. Por omissão, o pacote obtém as permissões do utilizador via $user->getAllPermissions() (compatível com vários setups, incluindo Spatie) e compara as strings. Podes personalizar com o callback user_permissions:

'permission_mode' => 'string',

'user_permissions' => function ($user) {
    // devolve um array/Collection de strings
    return $user?->permissions()->pluck('name')->all() ?? [];
},

$menu = Menu::forUser($user); // já filtrado pelas permissões do $user

Modo id

Guardas o id da permissão (como texto) e apontas o resolver para a tua tabela. O pacote resolve o id contra ela quando precisa do rótulo legível, e compara ids na filtragem:

'permission_mode' => 'id',

'resolver' => [
    'table'  => 'permissions', // a TUA tabela
    'key'    => 'id',
    'column' => 'name',
],

'user_permissions' => function ($user) {
    // devolve os IDS das permissões do utilizador
    return $user?->permissions()->pluck('id')->all() ?? [];
},

Obter o rótulo legível de um item:

$item->resolvedPermissionLabel(); // ex.: 'gerir.tudo' (lido da tua tabela)

Middleware

O pacote regista o alias menu.permission. Protege rotas exigindo uma permissão:

Route::get('/admin', [AdminController::class, 'index'])
    ->middleware('menu.permission:admin.access');

• No modo none, o middleware é um no-op (deixa passar sempre) — o mesmo código funciona em projetos com e sem permissões.
• Nos modos string/id, devolve 403 se o utilizador não tiver a permissão indicada.

Cache

A árvore é lida da cache, sem joins. Configura o store em config/dynamic-menu.php:

'cache' => [
    'enabled' => true,
    'store'   => 'redis', // ou null para o default, 'file', etc.
    'ttl'     => 3600,    // segundos; null = forever
],

A cache é invalidada automaticamente em saved / deleted / restored do model. Para gerir manualmente:

# Reconstruir a cache
php artisan dynamic-menu:cache

# Apenas limpar
php artisan dynamic-menu:cache --flush

Ou por código:

Menu::rebuildCache();
Menu::flushCache();

Seeder

O pacote inclui um seeder de exemplo com uma hierarquia de várias profundidades. Publica-o e adapta:

php artisan vendor:publish --tag=dynamic-menu-seeders

Depois corre:

// database/seeders/DatabaseSeeder.php
$this->call(\Database\Seeders\MenuItemsSeeder::class);

php artisan db:seed --class="Database\\Seeders\\MenuItemsSeeder"

Ou usa diretamente o seeder do pacote sem publicar:

php artisan db:seed --class="Gsebastiao\\DynamicMenu\\Database\\Seeders\\MenuItemsSeeder"

Testes

O pacote usa Pest com Orchestra Testbench.

composer install
vendor/bin/pest

A suite cobre: montagem da árvore em N níveis, ordenação, cache e sua invalidação, filtragem por permissão nos três modos, resolução via tabela no modo id, o middleware e o comando artisan.

Licença

MIT. Ver LICENSE.md.