README

Sistema de autorização RBAC (usuários, grupos, permissões e menus) para projetos Laravel — instale e comece a codificar sem duplicar model/migration entre projetos.

Instalação

composer require gsebastiao/laravel-authorization

O Service Provider é descoberto automaticamente (Laravel package auto-discovery). Não é necessário registrar nada em config/app.php.

Pré-requisitos

• Uma tabela users já existente no projeto (o pacote não cria essa tabela — só referencia via FK). Precisa ter id como chave primária padrão do Laravel.
• PHP ^8.2, Laravel ^11 / ^12 / ^13 (Laravel 13 exige PHP 8.3+ — essa exigência já vem do próprio laravel/framework, não precisa se preocupar em travar isso aqui).

Rodando as migrations

As migrations do pacote já são carregadas automaticamente. Basta migrar:

php artisan migrate

Isso cria: auth_groups, auth_groups_users, auth_logins, auth_permissions, auth_permissions_menus, auth_permissions_groups, auth_permissions_users, auth_permissions_audits.

Publicando config (opcional)

Só necessário se você precisa customizar nomes de tabela, conexão de banco, ou comportamento de cache:

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

Isso cria config/authorization.php no projeto-host.

Publicando migrations (opcional)

Só necessário se você precisa editar as migrations antes de rodar (ex: renomear uma tabela por conflito com outro pacote já instalado):

php artisan vendor:publish --tag=authorization-migrations

Uso básico

Via Facade

use Gsebastiao\LaravelAuthorization\Facades\Authorization;

// Verifica se o usuário autenticado tem uma permissão
if (Authorization::hasPermission('usuario.criar')) {
    // ...
}

// Verifica permissão de um usuário específico (não o autenticado)
if (Authorization::hasPermission('relatorio.exportar', $outroUsuarioId)) {
    // ...
}

// Lista de permissões efetivas (já resolvendo grupo + individual + is_absolute)
$permissoes = Authorization::getUserPermissions();

// Árvore de menu filtrada pelas permissões do usuário autenticado
$menu = Authorization::getMenuTree();

Via injeção de dependência

use Gsebastiao\LaravelAuthorization\Models\Authorization;

class DashboardController extends Controller
{
    public function index(Authorization $authorization)
    {
        return view('dashboard', [
            'menu' => $authorization->getMenuTree(),
        ]);
    }
}

Como a permissão efetiva é calculada

Ordem de prioridade (da mais forte para a mais fraca):

1. Negação individual do usuário (auth_permissions_users.is_granted = 0) → sempre vence, ignora qualquer grupo.
2. Concessão individual do usuário (auth_permissions_users.is_granted = 1) → concedido.
3. Negação absoluta de algum grupo (auth_permissions_groups.is_granted = 0 e is_absolute = true) → vence concessão de outro grupo.
4. Concessão de algum grupo → concedido.
5. Só restam negações "fracas" de grupo (is_absolute = false), sem nenhuma concessão → negado.
6. Nenhum registro em lugar nenhum → negado por padrão.

is_absolute existe para resolver conflito entre grupos: se um usuário está em dois grupos e um concede enquanto outro nega, por padrão a concessão vence (comportamento mais permissivo, evita bloqueio acidental). Marque is_absolute = true na negação apenas quando ela precisar ser um controle de segurança real que nenhum outro grupo pode sobrescrever (ex: segregação de função / compliance).

Cache

Permissões efetivas e estrutura de menu são cacheadas via Cache facade do Laravel (respeitando o CACHE_DRIVER já configurado no projeto — funciona com Redis, file, array, etc.).

Importante: sempre que você alterar um vínculo de grupo, permissão de grupo, ou permissão individual de um usuário, invalide o cache dele:

use Gsebastiao\LaravelAuthorization\Facades\Authorization;

Authorization::forgetUserCache($userId);

E sempre que criar/editar/remover um menu:

Authorization::forgetMenuStructureCache();

A forma recomendada é conectar essas chamadas a Model Observers dos seus models administrativos (Group, Permission, GroupUser, etc.), para não depender de lembrar manualmente em cada lugar do código onde essas tabelas são alteradas.

Configuração multi-tenant / conexão customizada

Se as tabelas auth_* vivem numa conexão de banco diferente da padrão do projeto, publique a config e ajuste:

// config/authorization.php
'connection' => 'central', // nome de uma conexão definida em config/database.php

Licença

MIT.