PHPackages                             bitoliveira/laravel-info-approval - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. bitoliveira/laravel-info-approval

ActiveLibrary[Utility & Helpers](/categories/utility)

bitoliveira/laravel-info-approval
=================================

A Laravel package to add approval workflows to Eloquent models.

0.2.2(1mo ago)030MITPHPPHP >=8.2

Since Sep 22Pushed 1mo agoCompare

[ Source](https://github.com/bitoliveira/laravel-info-approval)[ Packagist](https://packagist.org/packages/bitoliveira/laravel-info-approval)[ RSS](/packages/bitoliveira-laravel-info-approval/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (1)Dependencies (14)Versions (5)Used By (0)

Laravel Info Approval
=====================

[](#laravel-info-approval)

Sistema completo de aprovações para modelos Eloquent no Laravel com suporte a múltiplos níveis, estratégias flexíveis e API REST.

[![Tests](https://camo.githubusercontent.com/a02f74b68b41920d1ade545c1f2854367d4f647a9bba33481d1a92024f6374c0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d353525323070617373696e672d627269676874677265656e)](./tests)[![Coverage](https://camo.githubusercontent.com/32855e94577df9d0a30995653b17d33a5fbfdf644518f96ea0374313397d19b7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d3130302532352d627269676874677265656e)](./tests)[![Laravel](https://camo.githubusercontent.com/9155763cf33a2b51aeaef66d0ea60fcfd9ab1057741c2a39171ffcb1195c921d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d313125374331322d726564)](https://laravel.com)[![PHP](https://camo.githubusercontent.com/344e820b219cee3234648531306104364bd684892ad13c5dc79e66eb82a15b90/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e322532422d626c7565)](https://php.net)[![License](https://camo.githubusercontent.com/b8cadaa967891081f8f165695470689986c028821dd8a040132f6e661795dc0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c7565)](./LICENSE)

---

🚀 Início Rápido
---------------

[](#-início-rápido)

```
composer require bitoliveira/laravel-info-approval
php artisan migrate
```

```
use bitoliveira\Approval\Traits\HasApprovals;

class Employee extends Model {
    use HasApprovals;
}

// Criar aprovação
$approval = $employee->requestApproval('update_field', [
    'field' => 'salary',
    'new_value' => 3500,
], userId: auth()->id());

// Aprovar
app(\bitoliveira\Approval\Services\ApprovalService::class)
    ->approve($approval, approverId: auth()->id());
```

**📚 [Guia Rápido de 5 Minutos](./QUICKSTART.md)** | **📖 [Documentação Completa](./USAGE.md)** | **🌐 [API REST](./API.md)**

---

✨ Funcionalidades
-----------------

[](#-funcionalidades)

### 🎯 Core

[](#-core)

- ✅ **Aprovações Polimórficas** - Qualquer modelo Eloquent pode ter aprovações
- ✅ **Três Estratégias** - Single, Majority, Unanimous
- ✅ **Multi-Nível** - Aprovações hierárquicas (Manager → Director → CEO)
- ✅ **Controle por Roles** - Integração com spatie/laravel-permission
- ✅ **Histórico Completo** - Log detalhado de todas as ações
- ✅ **Soft Deletes** - Preserva histórico mesmo após exclusão

### 🌐 API

[](#-api)

- ✅ **REST API Completa** - Pronta para apps mobile
- ✅ **Autenticação Sanctum** - Segurança integrada
- ✅ **Validações Robustas** - Form Requests customizados
- ✅ **Resources Padronizados** - Responses formatados
- ✅ **Paginação** - Suporte nativo Laravel

### 🔍 Consultas

[](#-consultas)

- ✅ **11 Query Scopes** - Filtros reutilizáveis e encadeáveis
- ✅ **Busca Avançada** - Por status, tipo, usuário, ação
- ✅ **Performance** - Queries otimizadas

### 📢 Eventos

[](#-eventos)

- ✅ **4 Eventos** - ApprovalRequested, Approved, Rejected, LevelAdvanced
- ✅ **Notificações** - Integração fácil com Laravel Notifications
- ✅ **Observabilidade** - Auditoria completa

### 🛡️ Segurança

[](#️-segurança)

- ✅ **Exceções Customizadas** - Tratamento de erros específico
- ✅ **Validação de Permissões** - Automática por role
- ✅ **Proteção de Duplicação** - Não permite aprovar 2x
- ✅ **Auditoria** - Rastreamento completo de ações

---

📦 Instalação
------------

[](#-instalação)

### 1. Via Composer

[](#1-via-composer)

```
composer require bitoliveira/laravel-info-approval
```

### 2. Publicar Arquivos (Opcional)

[](#2-publicar-arquivos-opcional)

```
# Configuração
php artisan vendor:publish --tag=approval-config

# Migrations
php artisan vendor:publish --tag=approval-migrations
```

### 3. Migrar Banco de Dados

[](#3-migrar-banco-de-dados)

```
php artisan migrate
```

---

🎯 Uso Básico
------------

[](#-uso-básico)

### 1. Adicionar a Trait ao Modelo

[](#1-adicionar-a-trait-ao-modelo)

```
use bitoliveira\Approval\Traits\HasApprovals;

class Employee extends Model
{
    use HasApprovals;

    protected $fillable = ['name', 'salary', 'department'];
}
```

### 2. Criar Aprovação

[](#2-criar-aprovação)

```
$employee = Employee::find(1);

$approval = $employee->requestApproval('update_field', [
    'field' => 'salary',
    'new_value' => 3500,
], userId: auth()->id());

// Status: pending
// Mudança NÃO aplicada ainda
```

### 3. Aprovar ou Rejeitar

[](#3-aprovar-ou-rejeitar)

```
use bitoliveira\Approval\Services\ApprovalService;

$service = app(ApprovalService::class);

// Aprovar
$service->approve($approval, approverId: auth()->id());
// Agora o salário é 3500 ✅

// OU Rejeitar
$service->reject($approval, approverId: auth()->id());
```

---

🎨 Estratégias de Aprovação
--------------------------

[](#-estratégias-de-aprovação)

### Single (Padrão)

[](#single-padrão)

Uma aprovação é suficiente:

```
$approval = $employee->requestApproval('update_field', [
    'field' => 'salary',
    'new_value' => 3000,
    'strategy' => 'single',
], userId: 1);
```

### Majority

[](#majority)

Maioria deve aprovar:

```
$approval = $employee->requestApproval('update_field', [
    'field' => 'salary',
    'new_value' => 3500,
    'strategy' => 'majority',
    'approvers' => [1, 2, 3, 4], // Precisa de 2 (maioria)
], userId: 1);
```

### Unanimous

[](#unanimous)

Todos devem aprovar:

```
$approval = $employee->requestApproval('update_field', [
    'field' => 'salary',
    'new_value' => 4000,
    'strategy' => 'unanimous',
    'approvers' => [1, 2, 3], // Todos devem aprovar
], userId: 1);
```

---

🏢 Aprovações Multi-Nível
------------------------

[](#-aprovações-multi-nível)

Crie fluxos hierárquicos de aprovação:

```
$levels = [
    ['roles' => ['Manager']],   // Nível 1: Manager
    ['roles' => ['Director']],  // Nível 2: Director
    ['roles' => ['CEO']],        // Nível 3: CEO
];

$approval = $employee->requestApproval('update_field', [
    'field' => 'salary',
    'new_value' => 5000,
], userId: 1, levels: $levels);

// Aprovação em cascata
$service->approve($approval, approverId: $managerId);   // → Nível 2
$service->approve($approval, approverId: $directorId);  // → Nível 3
$service->approve($approval, approverId: $ceoId);       // ✅ Aprovado!
```

**Recursos:**

- ✅ Quantos níveis quiser
- ✅ Roles diferentes por nível
- ✅ Eventos a cada avanço de nível
- ✅ Log completo do processo

---

🌐 API REST
----------

[](#-api-rest)

Endpoints prontos para apps mobile:

```
GET    /api/approvals              # Listar com filtros
GET    /api/approvals/{id}         # Detalhes
POST   /api/approvals/{id}/approve # Aprovar
POST   /api/approvals/{id}/reject  # Rejeitar
```

### Exemplo de Uso

[](#exemplo-de-uso)

```
// Listar aprovações pendentes
const response = await fetch('/api/approvals?status=pending', {
  headers: { 'Authorization': `Bearer ${token}` }
});

// Aprovar
await fetch(`/api/approvals/${id}/approve`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ approver_id: userId })
});
```

**📖 [Documentação Completa da API](./API.md)**

---

🔍 Query Scopes
--------------

[](#-query-scopes)

11 scopes poderosos para consultas:

```
use bitoliveira\Approval\Models\Approval;

// Por status
Approval::pending()->get();
Approval::approved()->get();
Approval::rejected()->get();

// Por tipo/modelo
Approval::forType(Employee::class)->get();
Approval::forModel($employee)->get();

// Por ação
Approval::action('update_field')->get();

// Por usuário
Approval::requestedBy(auth()->id())->get();
Approval::approvedBy(auth()->id())->get();

// Por nível
Approval::atLevel(2)->get();

// Combinar e paginar
Approval::pending()
    ->forType(Employee::class)
    ->requestedBy(auth()->id())
    ->recent()
    ->paginate(15);
```

---

📢 Eventos
---------

[](#-eventos-1)

4 eventos para integração:

```
use bitoliveira\Approval\Events\{
    ApprovalRequested,
    ApprovalApproved,
    ApprovalRejected,
    ApprovalLevelAdvanced
};

// Quando aprovação é criada
Event::listen(ApprovalRequested::class, function ($event) {
    $approval = $event->approval;
    // Notificar aprovadores
});

// Quando é finalmente aprovada
Event::listen(ApprovalApproved::class, function ($event) {
    $approval = $event->approval;
    $approverId = $event->approverId;
    // Notificar solicitante
});

// Quando é rejeitada
Event::listen(ApprovalRejected::class, function ($event) {
    // Log da rejeição
});

// Quando avança de nível
Event::listen(ApprovalLevelAdvanced::class, function ($event) {
    $previousLevel = $event->previousLevel;
    $newLevel = $event->newLevel;
    // Notificar próximos aprovadores
});
```

---

🛡️ Segurança
------------

[](#️-segurança-1)

### Exceções Customizadas

[](#exceções-customizadas)

```
use bitoliveira\Approval\Exceptions\{
    InvalidApprovalStatusException,    // 422
    DuplicateApprovalException,        // 422
    UnauthorizedApproverException,     // 403
    ApproverMismatchException          // 403
};

try {
    $service->approve($approval, approverId: auth()->id());
} catch (DuplicateApprovalException $e) {
    return response()->json(['error' => $e->getMessage()], 422);
}
```

### Validações Automáticas

[](#validações-automáticas)

- ✅ `approver_id` deve corresponder ao usuário autenticado
- ✅ Usuário deve ter role necessária para o nível
- ✅ Não pode aprovar a mesma solicitação duas vezes
- ✅ Não pode modificar aprovações já processadas

---

🗑️ Soft Deletes
---------------

[](#️-soft-deletes)

Preserve histórico mesmo após exclusão:

```
// Deletar suavemente
$approval->delete();

// Incluir deletados em queries
Approval::withTrashed()->find(1);
Approval::onlyTrashed()->get();

// Restaurar
$approval->restore();

// Deletar permanentemente
$approval->forceDelete();
```

---

📊 Testes
--------

[](#-testes)

**55 testes** cobrindo 100% das funcionalidades:

```
composer test
```

Cobertura de testes:

- ✅ 7 testes de exceções
- ✅ 7 testes de validação API
- ✅ 6 testes de API Resources
- ✅ 5 testes de query scopes
- ✅ 7 testes de soft deletes
- ✅ 5 testes de estratégias
- ✅ 8 testes de integração completa
- ✅ 5 testes de eventos
- ✅ E mais...

**Total: 275 assertions passando** ✅

---

📚 Documentação
--------------

[](#-documentação)

DocumentoDescrição[QUICKSTART.md](./QUICKSTART.md)Guia rápido de 5 minutos[USAGE.md](./USAGE.md)Documentação completa de uso[API.md](./API.md)Documentação da API REST[SECURITY.md](./SECURITY.md)Política de segurança---

🤝 Configuração
--------------

[](#-configuração)

Arquivo `config/approval.php`:

```
return [
    'users_model' => "\\App\\Models\\User",
    'roles_model' => "\\Spatie\\Permission\\Models\\Role",
    'enabled' => true,
    'default_strategy' => 'single',

    'api' => [
        'prefix' => 'approvals',
        'middleware' => ['api', 'auth:sanctum'],
    ],
];
```

---

💡 Exemplos de Uso Real
----------------------

[](#-exemplos-de-uso-real)

### Dashboard de Aprovações

[](#dashboard-de-aprovações)

```
public function dashboard()
{
    return view('approvals.dashboard', [
        'pending' => Approval::pending()
            ->whereJsonContains('data->approvers', auth()->id())
            ->recent()
            ->paginate(10),

        'myRequests' => Approval::requestedBy(auth()->id())
            ->recent()
            ->paginate(10),
    ]);
}
```

### Integração Mobile (React Native)

[](#integração-mobile-react-native)

```
const approvalService = {
  async getPending(token) {
    const res = await fetch('/api/approvals?status=pending', {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    return res.json();
  },

  async approve(id, userId, token) {
    return fetch(`/api/approvals/${id}/approve`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ approver_id: userId })
    });
  }
};
```

---

🎓 Requisitos
------------

[](#-requisitos)

- PHP 8.2+
- Laravel 11.x ou 12.x
- MySQL, PostgreSQL, ou SQLite

---

🤝 Contribuir
------------

[](#-contribuir)

Contribuições são bem-vindas! Por favor:

1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request

---

📝 Changelog
-----------

[](#-changelog)

### v0.1.0 (Atual)

[](#v010-atual)

**Funcionalidades:**

- ✅ Sistema completo de aprovações
- ✅ Três estratégias (single, majority, unanimous)
- ✅ Aprovações multi-nível com roles
- ✅ API REST completa
- ✅ 11 Query Scopes
- ✅ 4 Eventos
- ✅ Soft Deletes
- ✅ Exceções customizadas
- ✅ Form Requests e Resources
- ✅ 55 testes (100% cobertura)

---

🐛 Problemas e Suporte
---------------------

[](#-problemas-e-suporte)

- **Issues:**
- **Segurança:** Veja [SECURITY.md](./SECURITY.md)

---

📄 Licença
---------

[](#-licença)

Este projeto está sob a licença MIT. Veja [LICENSE](./LICENSE) para mais detalhes.

---

👤 Autor
-------

[](#-autor)

**Bruno Oliveira**

- Email:
- GitHub: [@bitoliveira](https://github.com/bitoliveira)

---

⭐ Apoie o Projeto
-----------------

[](#-apoie-o-projeto)

Se este package foi útil para você, considere dar uma ⭐ no GitHub!

---

**Desenvolvido com ❤️ para a comunidade Laravel**

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance93

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~80 days

Total

4

Last Release

36d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f37c6abefd215204886bb93e28b893c7b5615abe955bd02b42056a5e17373b73?d=identicon)[bitoliveira](/maintainers/bitoliveira)

---

Top Contributors

[![bitoliveira](https://avatars.githubusercontent.com/u/5708833?v=4)](https://github.com/bitoliveira "bitoliveira (31 commits)")

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/bitoliveira-laravel-info-approval/health.svg)

```
[![Health](https://phpackages.com/badges/bitoliveira-laravel-info-approval/health.svg)](https://phpackages.com/packages/bitoliveira-laravel-info-approval)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k14.1M122](/packages/laravel-pulse)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9742.3M121](/packages/roots-acorn)[spatie/laravel-settings

Store your application settings

1.5k6.8M139](/packages/spatie-laravel-settings)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1232.2k16](/packages/fleetbase-core-api)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)