Download the PHP package gsebastiao/laravel-menu without Composer

Laravel Menu

Menus para Laravel guardados na base de dados, com os níveis que precisares (menu › submenu › sub-submenu…), que mostram a cada utilizador só o que ele pode ver.

• Funciona sem nenhum pacote de permissões — ou com o que já usas: gsebastiao/laravel-authz, Spatie, uma tabela tua.
• Rápido: a árvore fica em cache e a cache limpa-se sozinha quando mudas um item.
• Pronto a mostrar: um componente Blade desenha o menu com uma linha.

Índice

1. Requisitos
2. Começar em 5 minutos
3. Criar itens de menu
4. Mostrar o menu
5. Permissões
6. Proteger rotas (middleware)
7. Cache
8. Auditoria (opcional)
9. Configuração
10. Referência rápida
11. Resolução de problemas
12. Atualizar de uma versão anterior
13. Testes

Requisitos

Começar em 5 minutos

1. Instala o pacote

2. Cria a tabela menu_items

3. Cria alguns itens. Para experimentar, usa o menu de exemplo que vem com o pacote:

O primeiro comando copia o exemplo para database/seeders/MenuItemsSeeder.php, onde o podes editar. Podes correr o seeder as vezes que quiseres: os itens são atualizados, não duplicados.

4. Mostra o menu. No teu layout (ex.: resources/views/layouts/app.blade.php):

Pronto: tens um menu a funcionar. Os itens do exemplo que apontam para rotas que ainda não existem no teu projeto aparecem sem link, sem erros.

Queres mudar alguma opção (permissões, cache, nome da tabela...)? Não precisas de publicar o config: basta acrescentar variáveis MENU_* ao teu .env. A lista completa, com o padrão de cada uma, está em Configuração. Se fores mudar o nome da tabela (MENU_TABLE), faz isso antes do migrate.

5. (Opcional) Dá-lhe um estilo simples:

Criar itens de menu

Cada item é uma linha da tabela menu_items. Crias, editas e apagas itens como qualquer model do Laravel:

Podes pôr este código num seeder (como o de exemplo) ou experimentá-lo no php artisan tinker. A cache do menu é limpa automaticamente sempre que crias, editas, apagas ou restauras um item assim.

Os campos de um item

O que pode ir no campo route

Se o nome de rota não existir (ou faltar um parâmetro obrigatório), o item aparece sem link em vez de dar erro na página. Por segurança, endereços javascript: e data: nunca viram link.

Dica: num painel de administração, gere os itens com um CRUD normal (controller + formulário) sobre o model MenuItem.

Mostrar o menu

Com o componente pronto

Mostra o menu do utilizador autenticado, já filtrado pelas permissões, com os submenus aninhados. Também aceita outros itens e atributos para a <ul> principal:

O HTML gerado usa estas classes, para poderes dar-lhe o estilo que quiseres:

Além das classes, o <a> da página atual leva aria-current="page", para que um leitor de ecrã a anuncie. Só esse: os itens-pai ficam apenas com a classe is-active.

Mudar o HTML do componente

Publica a view e edita a cópia (ex.: para usares as classes do Bootstrap ou do Tailwind):

A cópia fica em resources/views/vendor/laravel-menu/components/menu.blade.php e passa a ser usada no lugar da original.

Montar o teu próprio HTML

Se preferires escrever tudo à mão, estas são as peças que o componente usa:

• Menu::forUser() devolve os itens de topo que o utilizador pode ver. Cada item é um array com todos os campos da tabela e uma chave children com os filhos.
• Menu::url($item) devolve o link do item, ou null se não tiver.
• Menu::isActive($item) diz se o item (ou um dos filhos) é a página atual. Um item com a rota users.index também fica ativo em users.create, users.edit, etc.

Permissões

Por omissão não há permissões: todos os itens aparecem a toda a gente. Para esconder itens, são dois passos.

Passo 1: escolhe o modo

No .env:

Passo 2: diz ao pacote quais são as permissões do utilizador

Usas o gsebastiao/laravel-authz? Não precisas de fazer nada: salta para Com o gsebastiao/laravel-authz.

Usas o spatie/laravel-permission? Também não: o pacote usa $user->getAllPermissions() automaticamente.

Tens outra lógica? Define-a no boot() do app/Providers/AppServiceProvider.php:

O $user é o utilizador autenticado (ou null para visitantes). Podes devolver um array ou uma Collection de textos, models, arrays ou enums (de um model ou array é lida a coluna name; no modo id, a coluna id).

Com o gsebastiao/laravel-authz

O gsebastiao/laravel-authz traz grupos e permissões (RBAC) ao teu projeto. Com ele instalado, o menu descobre-o sozinho — não escreves resolver nenhum.

1. Instala e prepara o pacote (se ainda não o fizeste):

2. Põe o trait no teu model User:

3. Escolhe o modo string e guarda o nome da permissão em cada item:

É tudo. A partir daqui cada pessoa só vê o que pode, com a cascata do laravel-authz respeitada: negações individuais, regras dos grupos, validade por datas e o tenant atual. A cache do menu guarda a árvore, não as permissões de cada pessoa — quem perde uma permissão deixa de ver o item logo no pedido seguinte.

O middleware faz a mesma leitura, por isso a rota fica protegida com a mesma permissão que esconde o item:

Quem vê o quê

Verificar permissões no teu código

No modo none, hasPermission() devolve sempre true.

Modo id

Usa este modo se o campo permission guardar ids de uma tabela tua. Indica a tabela no .env:

• O resolver de permissões (passo 2) deve devolver os ids das permissões do utilizador.
• $item->resolvedPermissionLabel() devolve o nome legível da permissão do item, lido dessa tabela (útil num painel de administração).
• Com o gsebastiao/laravel-authz, os valores certos são auth_permissions / id / permission — ver Com o gsebastiao/laravel-authz.

Proteger rotas (middleware)

O pacote regista o middleware menu.permission:

• Quem não tiver a permissão recebe um erro 403.
• No modo none, o middleware deixa passar sempre — o mesmo código serve para projetos com e sem permissões.
• Junta-o ao middleware auth, para que um visitante seja enviado para o login em vez de receber um 403.

Cache

A árvore do menu é guardada em cache e limpa-se sozinha quando um item é criado, editado, apagado ou restaurado através do model (create(), update(), save(), delete(), restore()).

A cache não é limpa sozinha quando alteras os itens por outras vias:

• updates em massa: MenuItem::where(...)->update([...]);
• saveQuietly(), updateQuietly() ou MenuItem::withoutEvents(...);
• alterações diretas na base de dados (SQL, DB::table(...), outra aplicação).

Nesses casos, limpa-a à mão:

As opções da cache ficam no .env (ver a tabela em Configuração):

Auditoria (opcional)

Com o pacote gsebastiao/laravel-auditable, fica registado quem criou, editou, apagou ou restaurou cada item de menu, quando e o que mudou. O laravel-menu não depende desse pacote: só o instalas se quiseres.

1. Instala o pacote de auditoria:

O pacote de auditoria traz a própria migration e o migrate a executa: não precisas de publicar nada. (Só publica o config ou a migration se os quiseres editar — vê o README do laravel-auditable.)

2. Liga a auditoria no .env:

Não tens de mudar mais nada: MenuItem::create(), $item->update(), $item->delete() e $item->restore() passam a ficar registados. Em vez do parent_id, a auditoria guarda o nome do item pai.

Se ligares a auditoria sem o pacote instalado, a aplicação pára no arranque com uma mensagem a explicar como instalá-lo. Assim nunca ficas a pensar que a auditoria está a gravar quando não está.

Configuração

Tudo funciona sem configurar nada, e não precisas de publicar o ficheiro de configuração. Para mudar alguma coisa, usa o .env:

Não deixes uma variável em branco (MENU_CACHE_STORE=): o Laravel lê isso como texto vazio. Para voltar ao padrão, apaga a linha. Com php artisan config:cache, corre-o de novo depois de mudar o .env.

Se preferires editar o ficheiro, publica a configuração:

Tudo o que podes publicar:

Referência rápida

Facade Menu (use Gsebastiao\LaravelMenu\Facades\Menu; — nas views Blade já está disponível):

Model MenuItem:

Comando: php artisan laravel-menu:cache (com --flush só limpa).

Resolução de problemas

O menu aparece vazio. Confirma que há itens com is_active = true. Se usas permissões, vê o que o pacote recebe com dd(Menu::resolveUserPermissions()) — se vier vazio, revê o passo 2 das permissões.

Instalei o gsebastiao/laravel-authz e o menu continua vazio. Confirma três coisas: o MENU_PERMISSION_MODE está em string (ou em id, se guardares ids); o campo permission de cada item é exatamente igual ao nome da permissão no auth_permissions (a comparação distingue maiúsculas de minúsculas); e a permissão chega mesmo ao utilizador — dd(Menu::resolveUserPermissions()) mostra o que o pacote está a ver.

Alterei itens e o menu não mudou. Provavelmente alteraste-os sem passar pelos eventos do model (update em massa, SQL direto…). Corre php artisan laravel-menu:cache. Ver Cache.

Um item aparece sem link. O nome de rota no campo route não existe (confirma com php artisan route:list), falta um parâmetro obrigatório em params, ou é um caminho sem / no início (usa /sobre, não sobre).

O super-administrador não vê todos os itens. O pacote compara listas de permissões e não passa pelo Gate. Faz o resolver devolver todas as permissões nesse caso:

php artisan config:cache falha com "Your configuration files are not serializable". Tens uma closure no config/menu.php (normalmente em user_permissions). Troca-a por Menu::resolvePermissionsUsing() ou por uma classe — ver Permissões.

Target class [Database\Seeders\MenuItemsSeeder] does not exist. O seeder foi publicado por uma versão anterior a 2.1, que o copiava com o namespace errado. Publica-o de novo: php artisan vendor:publish --tag=laravel-menu-seeders --force.

Erro no arranque: "A auditoria do laravel-menu está ativada … mas o pacote … não está instalado". Instala o pacote de auditoria (ver Auditoria) ou define MENU_AUDITING_ENABLED=false.

Erro: "Valor inválido em config('menu.permission_mode')". O MENU_PERMISSION_MODE tem um valor desconhecido (ex.: strings). Usa none, string ou id.

Atualizar de uma versão anterior

De 2.1 para 2.2

Não há passos obrigatórios. Uma única coisa a rever: se já tens o gsebastiao/laravel-authz instalado e não configuraste nenhum resolver de permissões, o menu deixa de esconder todos os itens com permission e passa a mostrar os que cada pessoa pode ver — ver Com o gsebastiao/laravel-authz. Se tens um Menu::resolvePermissionsUsing(...) ou uma classe em config('menu.user_permissions'), nada muda.

De 2.0 para 2.1

Não há passos obrigatórios. Revê apenas:

• Se publicaste o seeder na 2.0, publica-o de novo: php artisan vendor:publish --tag=laravel-menu-seeders --force (a cópia antiga tinha o namespace errado).
• Middleware com várias permissões: menu.permission:a,b passou a aceitar quem tiver a ou b (antes só a era verificada).
• Menus filtrados: grupos sem link que ficam vazios e separadores soltos deixaram de aparecer.
• MENU_PERMISSION_MODE com um valor desconhecido passa a dar erro (antes funcionava como string sem avisar).

O CHANGELOG tem a lista completa.

De 1.x (gsebastiao/laravel-dynamic-menu) para 2.x

Na 2.0 o pacote mudou de nome. A tabela e os dados não mudam, e a migration não volta a correr.

1. Troca o pacote:

2. No teu código, substitui Gsebastiao\DynamicMenu\ por Gsebastiao\LaravelMenu\.
3. Se publicaste a config, renomeia config/dynamic-menu.php para config/menu.php e troca config('dynamic-menu.…') por config('menu.…').
4. No .env, troca o prefixo DYNAMIC_MENU_ por MENU_ (ex.: DYNAMIC_MENU_PERMISSION_MODE → MENU_PERMISSION_MODE).
5. Modo id sem config publicada: a tabela padrão passou de permissions para auth_permissions. Se usas permissions, define MENU_RESOLVER_TABLE=permissions.
6. Nos scripts de deploy, troca php artisan dynamic-menu:cache por php artisan laravel-menu:cache, e as tags dynamic-menu-* do vendor:publish por laravel-menu-*.
7. Corre php artisan laravel-menu:cache (a chave da cache mudou de dynamic_menu para laravel_menu).

Testes

A suíte usa Pest com Orchestra Testbench e corre no CI com Laravel 11, 12 e 13, em PHP 8.2 a 8.4, com e sem o pacote de auditoria.

Licença

MIT. Ver LICENSE.