🎉 Laravel-Statecraft v1.0 is out!

[Grazulex]

🎉 Laravel-Statecraft v1.0 is out!

After weeks of design, refinement, and testing, I’m proud to announce the official release of Laravel-Statecraft v1.0 🧩 — a powerful, elegant, and testable state machine engine for Laravel applications.

---

🧠 What is Laravel-Statecraft?

Laravel-Statecraft helps you model complex workflows and transitions in your Eloquent models, using declarative YAML definitions or PHP classes.
It gives you full control over guards, actions, events, and even transition history — all with clean syntax and full testability.

---

✨ Key Features

✅ Declarative Workflows — Define transitions in YAML
🛡️ Guard Logic — Support for complex AND / OR / NOT expressions
⚙️ Actions — Trigger lifecycle actions on transition
🔄 Auto Methods — Use $model->canApprove() or $model->approve()
🧪 Built-in Testing — Easily assert transitions with StateMachineTester
🔔 Event System — Listen for Transitioning and Transitioned events
📜 Optional History Tracking — Record every state change
🧩 Dynamic Resolution — Guards and actions resolved via the Laravel container
📊 Export Formats — JSON, Mermaid, and Markdown
🛠 Powerful CLI Tools — Artisan commands to create, validate, export and inspect workflows
🧰 Customizable — Configurable paths, events, naming conventions, etc.

---

🧾 Example YAML Workflow

state_machine:
  name: OrderWorkflow
  model: App\Models\Order
  states: [draft, pending, approved, rejected]
  initial: draft
  transitions:
    - from: draft
      to: pending
      guard: canSubmit
      action: notifyReviewer
    - from: pending
      to: approved
      guard:
        and:
          - IsManager
          - HasMinimumAmount
    - from: pending
      to: rejected
      action: refundCustomer

---

🧩 Guard Expressions

Statecraft allows logical guard expressions (AND / OR / NOT) for business rules like:

guard:
  and:
    - IsManager
    - or:
        - IsVIP
        - IsUrgent

---

🧪 Testing Made Easy

use Grazulex\LaravelStatecraft\Testing\StateMachineTester;

StateMachineTester::assertTransitionAllowed($order, 'approved');
StateMachineTester::assertTransitionBlocked($order, 'rejected');
StateMachineTester::assertCanExecuteMethod($order, 'approve');

---

🔧 Artisan Commands

Generate and manage everything via CLI:

php artisan statecraft:make order-workflow
php artisan statecraft:generate database/state_machines/order-workflow.yaml
php artisan statecraft:list
php artisan statecraft:export order-workflow mermaid

---

📚 Learn More

Check out the full documentation to explore:

• Guard Expressions
• Event Listeners
• History Tracking
• Export formats
• Test Utilities
• Configuration tips

---

💡 Get Started

Install the package:

composer require grazulex/laravel-statecraft

Optionally publish config and migrations:

php artisan vendor:publish --tag=statecraft-config
php artisan vendor:publish --tag=statecraft-migrations
php artisan migrate

---

❤️ About

Laravel-Statecraft is part of the Grazulex Tools ecosystem:
→ Laravel-Arc (DTOs)
→ Laravel-Flowpipe (Composable Pipelines)
→ Laravel-Statecraft (State Machines)

Crafted for clean, modular, and testable Laravel applications.

---

🧙 Author: Jean‑Marc Strauven / @Grazulex
✍️ Blog: Open Source My Friend

---

Let me know what you build with Laravel-Statecraft — and feel free to share feedback, ideas, or feature requests below! 🗨️