pixielity/laravel-workflow

Workflow engine for Laravel applications with state management and transitions

dev-main 2026-02-09 14:03 UTC

Requires

• php: ^8.5
• laravel-workflow/laravel-workflow: *
• pixielity/laravel-support: *

Requires (Dev)

• mockery/mockery: ^1.6
• orchestra/testbench: ^10.0
• phpunit/phpunit: ^11.0

MIT

• Pixielity Team

• workflow
• laravel
• state-machine
• transitions
• pixielity

README

This directory contains standard reference implementations and documentation for creating workflows and steps.

📚 Documentation

Start here to understand the patterns:

1. WORKFLOW_PATTERNS.md - Quick reference guide with golden rules and checklists
2. YIELD_PATTERN_EXPLAINED.md - Deep dive into yield vs yield from with visual diagrams
3. Workflows/README.md - Comprehensive documentation with templates

🎯 Reference Implementation

Workflows/CreatePolicy/ - Complete working example demonstrating all patterns:

• CreatePolicyWorkflow.php - Main workflow orchestration
• Steps/ValidatePolicyDataStep.php - Validation step (no retries)
• Steps/CreatePolicyStep.php - Database operation step (with retries)
• Steps/NotifyPolicyCreatedStep.php - Notification step (with retries)

🚀 Quick Start

Creating a New Workflow

1. Create workflow folder: Workflows/MyWorkflow/
2. Create workflow class extending Workflow
3. Create Steps/ subfolder for workflow-specific steps
4. Follow the patterns in CreatePolicy/ example

Creating a New Step

1. Extend Step base class
2. Use typed parameters in execute() method
3. Implement before() hook for validation
4. Set $name, $enableLogging, $maxRetries properties
5. Return structured data (array or DTO)

📖 Key Patterns

Yield Usage

// In main execute() - use `yield from` for helper methods
public function execute(): Generator
{
    yield from $this->validate();
    $data = yield from $this->create();
}

// In helper methods - use `yield` for steps
protected function validate(): Generator
{
    $result = yield $this->step(ValidateStep::class, $dto);
}

Argument Mapping

// Step with typed parameters
public function execute(MyDto $dto, MyService $service): array
{
    // Auto-mapped to $this->args->dto and $this->args->service
}

// Access in hooks
protected function before(): void
{
    /** @phpstan-ignore-next-line property.notFound */
    $dto = $this->args->dto;
}

Response Types

// Workflows return WorkflowResponse
return WorkflowResponse::success(['data' => $result]);

// Steps return structured data
return ['success' => true, 'data' => $result];

🎓 Learning Path

1. Start: Read WORKFLOW_PATTERNS.md for quick overview
2. Understand: Read YIELD_PATTERN_EXPLAINED.md to understand yield usage
3. Study: Review Workflows/CreatePolicy/ reference implementation
4. Reference: Use Workflows/README.md as detailed reference
5. Build: Create your own workflow following the patterns

✅ Checklist

Before creating a workflow, ensure you understand:

• [ ] When to use yield vs yield from
• [ ] How arguments are auto-mapped to $this->args
• [ ] How to return WorkflowResponse from workflows
• [ ] How to use WorkflowStatus enum
• [ ] How to implement before() hook in steps
• [ ] How to set retry configuration per step
• [ ] How to access step arguments via DataObject

🔍 Common Issues

Issue	Solution
"Generator object instead of result"	Use yield from for helper methods, not yield
"Step not executing"	Use yield for steps, not yield from
"Can't access $this->args->property"	Add @phpstan-ignore-next-line property.notFound
"Arguments not mapped"	Ensure parameter names match what you access in $this->args

📁 Directory Structure

examples/
├── README.md                          # This file
├── WORKFLOW_PATTERNS.md               # Quick reference
├── YIELD_PATTERN_EXPLAINED.md         # Yield pattern deep dive
└── Workflows/
    ├── README.md                      # Detailed documentation
    └── CreatePolicy/                  # Reference implementation
        ├── CreatePolicyWorkflow.php
        └── Steps/
            ├── ValidatePolicyDataStep.php
            ├── CreatePolicyStep.php
            └── NotifyPolicyCreatedStep.php

🤝 Contributing

When adding new examples:

1. Follow the established patterns
2. Add comprehensive docblocks
3. Include pattern notes in comments
4. Update this README if adding new concepts
5. Ensure code passes diagnostics

📞 Support

If you're unsure about a pattern:

1. Check WORKFLOW_PATTERNS.md quick reference
2. Review CreatePolicy/ example
3. Read YIELD_PATTERN_EXPLAINED.md for yield questions
4. Consult Workflows/README.md for detailed docs