PHPackages dev-bumba/laraflow - 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. [Framework](/categories/framework) 4. / 5. dev-bumba/laraflow ActiveLibrary[Framework](/categories/framework) dev-bumba/laraflow ================== An active temporal orchestration and declarative workflow engine for Laravel. v1.4.0(1mo ago)05MITPHPPHP ^8.2 Since May 26Pushed 1mo agoCompare [ Source](https://github.com/Carlos-Bumba-Dev/laraflow)[ Packagist](https://packagist.org/packages/dev-bumba/laraflow)[ RSS](/packages/dev-bumba-laraflow/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (7)Versions (4)Used By (0) LaraFlow 🌊 ========== [](#laraflow-) [![Latest Stable Version](https://camo.githubusercontent.com/34e695c6016bc2a934a96bed696e29b2f2ab562a7134d65a55d00653cd506bea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e302e302d626c75652e737667)](https://github.com/Carlos-Bumba-Dev/laraflow)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE.md)[![Laravel Core](https://camo.githubusercontent.com/ab7425c202a279a02a00281dd7b79daabfb82c3454a83e9843fe38eb3869efd4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d31302e7825323025324625323031312e782d7265642e737667)](https://laravel.com)![Engine Type](https://camo.githubusercontent.com/d913d2d464c5aeda7325b4165207d2eaad3bfd9d4e8054abf902ae811fdc3ad3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6172636869746563747572652d456e7465727072697365253230253246253230414349442d6f72616e67652e737667) O **LaraFlow** é um motor robusto de orquestração de processos e máquinas de estado (*State Machines*) de alta performance para o ecossistema Laravel. Construído sob as fundações do `spatie/laravel-model-states`, ele estende o framework para fornecer **consistência transacional estrita (ACID)**, trilha de auditoria imutável, gerenciamento automatizado de SLA e arquitetura orientada a eventos (EDA). Foi projetado especificamente para sistemas corporativos críticos — Fintechs, Insurtechs, Banca e Compliance — onde concorrência de dados (*Race Conditions*), quebra de regras operacionais e falta de rastreabilidade representam risco financeiro direto. --- Índice ------ [](#índice) - [Diferenciais de Engenharia & Arquitetura](#%EF%B8%8F-diferenciais-de-engenharia--arquitetura) - [Estrutura do Pacote](#-estrutura-do-pacote) - [Instalação](#-instala%C3%A7%C3%A3o) - [Configuração Básica](#%EF%B8%8F-configura%C3%A7%C3%A3o-b%C3%A1sica-configlaraflowphp) - [Como Usar](#-como-usar) - [Automação Ativa de SLA](#-automa%C3%A7%C3%A3o-ativa-de-sla-workflowcheck-slas) - [Cinto de Utilidades CLI](#-cinto-de-utilidades-cli-devsecops) - [Gerador de Scaffolding](#-gerador-de-scaffolding-makeworkflow) - [Licença](#-licen%C3%A7a) --- 🏗️ Diferenciais de Engenharia & Arquitetura ----------------------------------------------- [](#️-diferenciais-de-engenharia--arquitetura) O LaraFlow separa o ciclo de vida de uma mudança de estado em **três fases isoladas e sequenciais**, otimizando conexões de banco e garantindo isolamento de escopo: **Fase 1 — Validação Estática (Fora da Transação)**Checa permissões (`roles`/`permissions`), pré-requisitos relacionais e regras de negócio complexas (`Guards`). Se falhar, o banco de dados permanece intacto, poupando conexões ativas. **Fase 2 — Bloco Atômico Transacional (Dentro do Lock)**Aplica **Pessimistic Locking (`lockForUpdate`)** diretamente na linha do registro e executa um *Double-Check* de estado. Se outra requisição alterou o registro em paralelo, a operação sofre rollback e aborta, eliminando cliques duplos e execuções duplicadas. **Fase 3 — Efeitos Colaterais Pós-Commit (Event-Driven)**Anuncia as mudanças ao sistema (`WorkflowTransitioned`) apenas após o sucesso absoluto do commit no banco, isolando e protegendo a aplicação contra falhas em APIs ou filas de terceiros. --- 📂 Estrutura do Pacote --------------------- [](#-estrutura-do-pacote) ``` src/ ├── Console/ # Cinto de utilidades CLI de Sustentação e DevOps ├── Contracts/ # Interfaces de Contrato (HasSla, HasEarlyWarning) ├── Events/ # Eventos nativos desacoplados (EDA) ├── Models/ # Modelo imutável de histórico de auditoria ├── Traits/ # Trait de injeção de comportamento nos Eloquent Models ├── Transitions/ # O coração atômico do motor (GenericTransition) └── WorkflowServiceProvider.php ``` --- ⚡ Instalação ------------ [](#-instalação) Instale o pacote via Composer (se o repositório for privado, adicione a referência no seu `composer.json`): ``` composer require carlos-bumba-dev/laraflow ``` Publique o arquivo de configuração corporativo: ``` php artisan vendor:publish --tag=laraflow-config ``` Execute as migrations para subir as tabelas imutáveis de auditoria e controle de extensões: ``` php artisan migrate ``` --- ⚙️ Configuração Básica (`config/laraflow.php`) ---------------------------------------------- [](#️-configuração-básica-configlaraflowphp) Centralize os modelos Eloquent que o motor deve monitorar ativamente em background: ``` return [ 'monitored_models' => [ App\Models\Reclamacao::class, App\Models\PropostaCredito::class, ], 'concurrency' => [ 'timeout_seconds' => 10, ], 'compliance' => [ 'system_user_id' => 1, // Fallback para transições via CLI/Cron ], ]; ``` --- 🚀 Como Usar ----------- [](#-como-usar) ### 1. Prepare o seu Model Eloquent [](#1-prepare-o-seu-model-eloquent) Adicione a trait `HasStateHistory` e faça o mapeamento do status usando o Spatie States apontando para a nossa `GenericTransition`: ``` use LaraFlow\Traits\HasStateHistory; use Spatie\ModelStates\HasStates; class Reclamacao extends Model { use HasStates, HasStateHistory; protected function registerStates(): void { $this->addState('status', ReclamacaoStatus::class) ->transitionTo(Rececionada::class, GenericTransition::class); } } ``` ### 2. Disparando uma Transição com Contexto (Payload) [](#2-disparando-uma-transição-com-contexto-payload) Passe permissões, dependências, guards de negócio e metadados contextuais (ex: o parecer do analista) direto na chamada: ``` $reclamacao->status->transitionTo(Rececionada::class, [ 'roles' => ['analista-compliance'], 'payload' => [ 'complaint_id' => $reclamacao->id, 'user_id' => auth()->id(), 'parecer' => 'Análise concluída com base nos termos regulatórios vigentes.', ] ]); ``` --- 🤖 Automação Ativa de SLA (`workflow:check-slas`) ------------------------------------------------ [](#-automação-ativa-de-sla-workflowcheck-slas) Se os seus estados implementarem as interfaces `HasSla` ou `HasEarlyWarning`, o LaraFlow transforma-se em um **agente ativo de infraestrutura (self-healing)**. Configure o comando no `app/Console/Kernel.php` para rodar a cada minuto: ``` $schedule->command('workflow:check-slas')->everyMinute(); ``` **🟡 Zona Amarela (Early Warning):** Se o processo se aproximar do estouro, ele move o registro preventivamente para uma fila de prioridade. **🔴 Zona Vermelha (Transição Compulsória):** Se o prazo morrer, ele remove o registro da mesa do analista e joga para um status de fallback de contingência, disparando o evento `SlaBreached`. --- 🧰 Cinto de Utilidades CLI (DevSecOps) ------------------------------------- [](#-cinto-de-utilidades-cli-devsecops) O LaraFlow fornece comandos avançados para a equipe de sustentação intervir no ambiente de produção com **total rastreabilidade**. **Investigação Forense** — Veja a trilha imutável de um registro diretamente no terminal: ``` php artisan laraflow:audit "App\Models\Reclamacao" 1042 ``` **Intervenção de Emergência (Chave Mestra)** — Destrave um processo ignorando guards (ex: API de parceiro fora do ar), exigindo justificativa obrigatória para a auditoria: ``` php artisan laraflow:force "App\Models\Reclamacao" 1042 "App\States\Rececionada" --reason="Chamado técnico #9021" ``` **Radar de Gargalos** — Identifique quais departamentos estão retendo processos e estourando os indicadores da empresa: ``` php artisan laraflow:bottlenecks "App\Models\Reclamacao" ``` **Living Documentation** — Gere diagramas Mermaid atualizados em tempo real com base no código-fonte atual para documentar esteiras de CI/CD: ``` php artisan laraflow:visualize "App\States\ReclamacaoStatus" ``` --- 🛠️ Gerador de Scaffolding (`make:workflow`) ------------------------------------------- [](#️-gerador-de-scaffolding-makeworkflow) O LaraFlow inclui um comando Artisan para gerar em segundos toda a estrutura de pastas e arquivos necessária para um novo fluxo — estados, guards e actions — a partir de stubs pré-configurados. ``` php artisan make:workflow Complaint ``` O comando cria automaticamente a seguinte estrutura dentro do seu projeto: ``` app/States/Complaint/ ├── ComplaintStatus.php # Classe principal da Máquina de Estados ├── Guards/ │ └── ValidarComplaint.php # Guard de validação de regras de negócio └── Actions/ └── ExecutarAcaoComplaint.php # Action de efeito colateral pós-transição ``` Os arquivos gerados são populados com os stubs localizados em `src/stubs/`, que servem como ponto de partida funcional e já seguem as convenções do LaraFlow. --- 📄 Licença --------- [](#-licença) O LaraFlow é um software open-source licenciado sob a [MIT License](LICENSE.md). Criado com foco em resiliência por **Carlos Bumba**. ### Health Score 39 — LowBetter than 84% of packages Maintenance88 Actively maintained with recent releases Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity48 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 ~0 days Total 3 Last Release 59d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/278383351?v=4)[Carlos Bumba](/maintainers/Carlos-Bumba-Dev)[@Carlos-Bumba-Dev](https://github.com/Carlos-Bumba-Dev) --- Top Contributors [![Carlos-Bumba-Dev](https://avatars.githubusercontent.com/u/278383351?v=4)](https://github.com/Carlos-Bumba-Dev "Carlos-Bumba-Dev (18 commits)") --- Tags laravelworkflowworkflow enginestate-machinelaraflowbumba ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/dev-bumba-laraflow/health.svg) ``` [![Health](https://phpackages.com/badges/dev-bumba-laraflow/health.svg)](https://phpackages.com/packages/dev-bumba-laraflow) ``` ### Alternatives [laravel/ai The official AI SDK for Laravel. 1.0k3.2M246](/packages/laravel-ai)[laravel/cashier Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services. 2.5k30.2M151](/packages/laravel-cashier)[laravel/sail Docker files for running a basic Laravel application. 1.9k205.7M1.3k](/packages/laravel-sail)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k15.1M136](/packages/laravel-pulse)[psalm/plugin-laravel Psalm plugin for Laravel 3345.3M347](/packages/psalm-plugin-laravel)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 77922.3M186](/packages/laravel-mcp) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)