Download the PHP package gsebastiao/laravel-authz without Composer

Laravel Authz

Controle quem pode fazer o quê no seu sistema Laravel usando grupos e permissões.

• Coloque usuários em grupos ("Financeiro", "RH"...) e dê permissões aos grupos.
• Dê ou negue uma permissão a um usuário específico, quando precisar de uma exceção.
• Defina validade por data ("tem acesso só até 31/12").
• Funciona com @can, Gate, Policies e middleware de rota do Laravel.
• Multi-tenant, cache e auditoria são opcionais e começam desligados.

Índice

1. Requisitos
2. Instalação
3. Primeiros passos (5 minutos)
4. Onde checar permissões
5. Como a decisão é tomada
6. Referência rápida
7. Recursos opcionais — catálogo no config, cache, multi-tenant, auditoria, nomes de tabela
8. Problemas comuns
9. Atualizando da versão 2.x

1. Requisitos

• PHP 8.2 ou superior
• Laravel 11, 12 ou 13
• Uma tabela de usuários (a users padrão do Laravel serve)

2. Instalação

Passo 1 — instale o pacote:

Passo 2 — rode o instalador:

Ele pergunta se você quer rodar o migrate. São criadas 5 tabelas: auth_groups, auth_groups_users, auth_permissions, auth_permissions_groups e auth_permissions_users.

O pacote traz as próprias migrations e o migrate as executa direto: nada é copiado para o seu projeto, e a pasta database/migrations fica limpa. (Sem o instalador, php artisan migrate faz o mesmo.)

Quer editar o config ou as migrations? Rode php artisan authz:install --publish: ele copia config/authz.php e as migrations para o projeto, e você pode editá-los antes do migrate. Também dá para publicá-los separadamente, com php artisan vendor:publish --tag=authz-config e php artisan vendor:publish --tag=authz-migrations. Se o projeto já tem uma cópia publicada, ela é a que vale.

Sua tabela de usuários não se chama users? Responda não quando o instalador perguntar, coloque AUTHZ_TABLE_USER=sua_tabela no .env (ou ajuste tables.users em config/authz.php) e depois rode php artisan migrate. Veja todas as variáveis em Configurar pelo .env.

Passo 3 — adicione o trait no model de usuário:

Pronto. O pacote já está funcionando.

3. Primeiros passos (5 minutos)

Vamos montar um exemplo real: o grupo Financeiro pode ver e aprovar pagamentos.

3.1 Declare as permissões

Em config/authz.php:

E rode:

Dica: use o formato modulo.acao. O pacote separa o módulo (financeiro) e a ação (aprovar) sozinho. Rode este comando sempre que mudar a lista (ex: no deploy) — ele cria as novas, atualiza as alteradas e nunca apaga nada.

3.2 Crie o grupo e dê as permissões a ele

Num seeder, num php artisan tinker ou numa tela de administração:

3.3 Coloque um usuário no grupo

3.4 Cheque

É isso. Todo o resto do pacote são variações desses quatro passos.

4. Onde checar permissões

Middleware de rota

Visitante não logado vai para a tela de login (401 em requisições JSON); usuário logado sem permissão recebe erro 403. Ou seja: um 403 significa sempre que o usuário está logado e a checagem deu false — nunca que ele não está autenticado.

Nomes não diferenciam maiúsculas de minúsculas nem espaços em volta, tanto para permissões como para grupos. Atenção à diferença entre os separadores: | é "qualquer uma destas" e , é "todas estas" — trocar um pelo outro é a causa mais comum de um 403 inesperado.

Blade

As diretivas nativas @can / @cannot também funcionam.

Gate e @can

O pacote se liga ao Gate do Laravel automaticamente. Suas Policies e Gate::define() sempre têm prioridade — o pacote só responde quando nenhuma regra do seu projeto respondeu. Isso também significa que um "super admin" via Gate::before continua funcionando:

5. Como a decisão é tomada

Um usuário recebe permissões de dois lugares: dos grupos dele e de exceções individuais (regras só para ele). Quando as regras se contradizem, vence a primeira linha desta tabela que se aplicar:

Na prática: se ninguém disse nada sobre o usuário, os grupos decidem. Se nenhum grupo disser nada, a resposta é "não".

Negação comum x absoluta. Uma negação comum de grupo perde para a concessão de outro grupo. Uma negação absoluta vence qualquer grupo — use para regras de compliance ("estagiário nunca aprova pagamento, mesmo que esteja em outro grupo que aprova"):

Só contam regras vigentes. Uma regra é ignorada se estiver apagada, se a start_date ainda não chegou, se a end_date já passou, se o grupo ou a membresia estiver com status = 0, ou se a permissão estiver desativada.

6. Referência rápida

Permissões e grupos podem ser passados pelo nome ('financeiro.aprovar', 'Financeiro') ou pelo id (7). Nomes de permissão não diferenciam maiúsculas de minúsculas.

No model User (trait HasAuthz)

Prefere separar? HasRoles e HasPermissions também existem e podem ser usados juntos. HasAuthz é só os dois combinados.

No Facade Authz (gerenciar dados)

Comportamentos importantes:

• *`deletefazem soft delete** (dá para recuperar comrestore*). Passe purge: truepara apagar de vez:Authz::deleteGroup($id, purge: true)`.
• *`granteaddUserToGroup` não duplicam.** Se a regra ou membresia já existir, ela é atualizada com as opções informadas.
• *`updatesó aceitam campos conhecidos.** Um campo inválido gera um erro que lista os campos aceitos. Retornamfalse` quando nada mudou.
• Erros de uso (id inexistente, nome duplicado, campo inválido) lançam Gsebastiao\LaravelAuthz\Exceptions\AuthzException com uma mensagem que explica o que fazer.
• Toda escrita roda dentro de uma transação e dispara um evento do Laravel (GroupCreated, UserAddedToGroup, PermissionGrantedToGroup... — veja src/Events).

Opções aceitas

Funções globais

Também existem atalhos globais, úteis em qualquer lugar: authz(), hasPermission(), hasAnyPermission(), hasAllPermissions(), hasRole(), hasAnyRole(), hasAllRoles(), getUserGroups(), getUserPermissions(). Sem $userId, usam o usuário logado.

7. Recursos opcionais

Nada desta seção é necessário para usar o pacote.

Configurar pelo .env (sem editar o config)

O pacote carrega a sua configuração sozinho: não é preciso manter nem editar config/authz.php para mudar as opções abaixo. Ponha no .env só o que quiser mudar:

Não deixe uma variável em branco (AUTHZ_CACHE_STORE=): o Laravel lê isso como texto vazio, não como "sem valor". Para voltar ao padrão, apague a linha. Com php artisan config:cache, rode-o de novo depois de mudar o .env.

Só o catálogo de permissões (permissions, uma lista) precisa do arquivo config/authz.php — veja abaixo. Se não usar o catálogo, o arquivo é opcional.

Catálogo completo no config

Além da forma curta, cada permissão aceita mais detalhes:

Para montar uma tela de "gerenciar permissões", use Authz::getAssignablePermissions().

Cache

Por padrão cada checagem consulta o banco. Em produção, ligue o cache no .env:

Tudo o que é feito pelos métodos do pacote atualiza o cache sozinho. Se você alterar as tabelas direto no banco (SQL, seeder com DB::table), rode:

Outras opções (AUTHZ_CACHE_STORE, AUTHZ_CACHE_TTL...) estão na tabela do .env. Validades por data são reavaliadas quando o TTL expira (padrão: 1 hora).

Multi-tenant (empresas, filiais, sedes...)

Use só se o sistema for dividido em partes que não podem ver os grupos umas das outras. Crie uma classe que diga qual é o tenant atual:

E aponte para ela no .env:

(ou, se preferir, em config/authz.php: 'tenant_context' => \App\Support\TenantAtual::class.)

O que muda:

• Grupos passam a pertencer a um tenant. Pode existir um "Financeiro" em cada empresa, cada um com suas permissões. createGroup() usa o tenant atual. Um grupo com tenant_id NULL é global: vale em todos os tenants (é o caso dos grupos criados antes de você ligar o multi-tenant). Grupos de outro tenant continuam invisíveis.
• Permissões continuam globais, a não ser que você crie uma exclusiva: Authz::createPermission('exportar.massa', 'relatorios', 'exportar', 'Exportar', tenantId: 3). Permissões exclusivas ficam invisíveis e sem efeito nos outros tenants, e não podem ser dadas a grupos de outro tenant.
• Nomes de grupo (assignRole('Financeiro')) são procurados entre os grupos do tenant atual e os globais. Se existirem dois com o mesmo nome (um global e um do tenant), o pacote avisa e pede o id em vez de escolher por você.

Atenção: o id do tenant nunca pode ser 0 nem string vazia.

Os métodos de gerenciamento não verificam se o id que você passou pertence ao tenant atual. Numa tela de administração por tenant, valide isso no seu controller antes de chamar updateGroup, deleteGroup etc.

Auditoria

Com o pacote gsebastiao/laravel-auditable instalado e AUTHZ_AUDIT_ENABLED=true, toda alteração feita pelo pacote é auditada.

Sem o pacote de auditoria, tudo funciona normalmente, apenas sem registrar.

Nomes de tabela diferentes

Use as variáveis AUTHZ_TABLE_* no .env (ou edite tables em config/authz.php) antes de rodar o migrate. Mudar depois não renomeia tabelas já criadas.

8. Problemas comuns

Grupo 'X' não encontrado — confira o nome (maiúsculas e espaços em volta não importam). Com multi-tenant, o grupo precisa ser do tenant atual ou global.

Permissão 'x' não encontrada — rode php artisan authz:sync-permissions depois de declarar a permissão no config.

Dei a permissão mas hasPermission continua false (ou a rota dá 403). Verifique, nesta ordem:

1. O usuário tem uma negação individual? (denyPermission vence tudo)
2. Algum grupo dele tem negação absoluta para essa permissão?
3. A regra, o grupo ou a membresia está com status = 0, start_date no futuro ou end_date no passado?
4. A permissão está desativada ou é exclusiva de outro tenant?
5. Cache ligado e você alterou o banco direto? Rode php artisan authz:cache-reset.
6. Na rota, você usou , (exige TODAS) onde queria | (basta UMA)?

Para ver o que o pacote enxerga do usuário:

Se a permissão aparece nessa segunda lista mas a rota continua a dar 403, o problema está na rota (item 6), não nos dados.

@can('financeiro.aprovar') retorna false mesmo com a permissão. Veja se o seu projeto tem um Gate::define('financeiro.aprovar', ...) ou uma Policy respondendo antes — eles têm prioridade. Confirme também que gates.auto_register está true em config/authz.php.

Já existe um grupo apagado com o nome... — nomes são únicos mesmo depois do soft delete. Use Authz::restoreGroup($id) (ou restorePermission) como a mensagem indica.

Rodei vendor:publish duas vezes. Sem problema: migrations já publicadas não são duplicadas.

migrate diz que a tabela já existe. Não deve acontecer: as migrations do pacote ignoram tabelas que já existem. Se acontecer com um nome de tabela diferente, confira as variáveis AUTHZ_TABLE_* do .env.

9. Atualizando da versão 2.x

A 2.x não conseguia ser instalada numa aplicação nova (o migrate falhava e as migrations não eram publicadas corretamente). Se você contornou isso manualmente e já tem as tabelas:

1. Não publique as migrations de novo — as tabelas não mudaram. (Se rodar php artisan migrate, as migrations do pacote ignoram as tabelas que já existem.)
2. Se usava HasRoles e HasPermissions juntos, agora funciona; ou troque os dois por HasAuthz.
3. Revise o CHANGELOG — algumas regras passaram a ser aplicadas como sempre foram documentadas (grupo inativo e start_date futura deixam de conceder, por exemplo).
4. Opcional: nas instalações novas, apagar um usuário apaga as membresias dele em cascata. Se quiser o mesmo numa instalação antiga, troque a foreign key auth_groups_users.user_id para ON DELETE CASCADE numa migration sua.

Testes

A suíte (85 testes) roda com SQLite em memória e cobre a cascata de decisão, datas de validade, tenant, cache, auditoria, os traits do model, Gate, middlewares, Blade e os comandos artisan. Validada em Laravel 11, 12 e 13.

Licença

MIT