README

A powerful, secure PHP workflow engine that parses ReactFlow JSON diagrams and executes them as dynamic workflows. Perfect for automating complex business processes in Laravel applications.

🚀 Features

Core Capabilities

✅ ReactFlow JSON Parsing - Import workflows directly from React Flow designer
✅ 15+ Pre-built Nodes - Email, SMS, HTTP, CRUD, conditions, loops, and more
✅ Comprehensive Validation - Cycle detection, connectivity checks, schema validation
✅ Safe Expression Evaluation - Secure variable substitution without code injection risks
✅ Error Handling & Recovery - Error nodes, fallback paths, graceful degradation

Security & Reliability

✅ Input Sanitization - Automatic sanitization for emails, URLs, and user input
✅ SQL Injection Protection - Prepared statements for all database operations
✅ XSS Prevention - HTML content sanitization and escaping
✅ Transaction Support - ACID compliance for critical workflows
✅ Saga Pattern - Compensating transactions for distributed operations
✅ Timeout Protection - Prevents infinite loops and runaway executions
✅ Rate Limiting - Built-in rate limiting utilities
✅ Retry Logic - Exponential backoff for failed operations

Observability

✅ Comprehensive Logging - PSR-3 logger integration for all operations
✅ Execution Tracking - Detailed logging of workflow execution
✅ Error Context - Rich context information in error messages
✅ Audit Trail - Track who executed what and when

Developer Experience

✅ Easy Integration - Simple Laravel service provider
✅ Well Documented - Comprehensive guides and examples
✅ Type Hints - Full PHP 8 type support
✅ Extensible - Custom processors and strategies
✅ PHP 8.0+ - Modern PHP with backward compatibility
✅ Multi-Laravel - Works with Laravel 10-13

📦 Installation

composer require yahlox/processor

Requirements

PHP 8.0+
Laravel 10+
JSON extension
cURL extension

🎯 Quick Start

use Yahlox\Parser\ReactFlowParser;
use Yahlox\Engine\WorkflowValidator;
use Yahlox\Engine\WorkflowExecutor;
use Yahlox\Engine\ExpressionEvaluator;
use Yahlox\Registry\NodeProcessorRegistry;
use Yahlox\Domain\ExecutionContext;

// 1. Parse workflow from ReactFlow
$parser = new ReactFlowParser(strictValidation: true);
$workflow = $parser->parse($jsonPayload);

// 2. Validate workflow
$validator = new WorkflowValidator();
$validator->validate($workflow);

// 3. Create executor
$registry = new NodeProcessorRegistry();
$executor = new WorkflowExecutor(
    registry: $registry,
    validator: $validator,
    expressionEvaluator: new ExpressionEvaluator(),
    timeoutSeconds: 300
);

// 4. Set up context
$context = new ExecutionContext();
$context->set('user_email', 'user@example.com');
$context->set('order_id', 12345);

// 5. Execute workflow
try {
    $executor->execute($workflow, $context);
    echo "Success!";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

📚 Documentation

Complete User Guide - Detailed documentation with examples
Security Guide - Security best practices and features
Migration Guide - Upgrading from v1.x to v2.x
Node Catalog - All available node types

🏗️ Workflow Structure

A workflow consists of nodes (operations) and edges (connections):

{
  "nodes": [
    { "id": "start", "type": "start", "data": {} },
    { "id": "email", "type": "sendEmail", "data": {
      "to": "{user_email}",
      "subject": "Welcome",
      "body": "Hello {name}!"
    } },
    { "id": "end", "type": "end", "data": {} }
  ],
  "edges": [
    { "source": "start", "target": "email" },
    { "source": "email", "target": "end" }
  ]
}

🔧 Node Types

Type	Purpose	Example
`start`	Workflow entry point	Begin execution
`end`	Workflow exit point	Complete execution
`condition`	Branching logic	If amount > 1000
`switch`	Multiple branches	Switch on status
`loop`	Iterate collection	Process each item
`createRecord`	Insert database record	Create user
`readRecord`	Fetch records	Get order
`updateRecord`	Modify records	Update status
`deleteRecord`	Remove records	Delete user
`sendEmail`	Send emails	Email notification
`sendSms`	Send SMS	SMS alert
`sendNotification`	In-app notifications	Notify user
`httpRequest`	HTTP API calls	Call webhook
`delay`	Pause execution	Wait 5 seconds
`error`	Error handler	Handle failures
`custom`	Custom logic	Run custom code

🔐 Security Highlights

1. Safe Variable Substitution

// NOT vulnerable to injection
$evaluator->evaluate("{email} at {company}", $context);
// Even if {email} contains PHP code, it's treated as a string

2. Input Validation

use Yahlox\Utils\InputSanitizer;

$email = InputSanitizer::sanitize($value, 'email');  // Validates email format
$url = InputSanitizer::sanitize($value, 'url');      // Validates URL format

3. SQL Injection Protection

{
  "type": "createRecord",
  "data": {
    "fields": {
      "name": "{user_input}",  // Automatically parameterized
      "email": "{email_input}"
    }
  }
}

4. XSS Prevention

{
  "type": "sendEmail",
  "data": {
    "body": "<p>User data: {user_data}</p>",
    "htmlContent": true  // Automatically sanitized
  }
}

5. Timeout Protection

$executor = new WorkflowExecutor(
    // ... other params
    timeoutSeconds: 300  // Max 5 minutes
);

6. Workflow Validation

All workflows are validated:

✅ Exactly one start node
✅ At least one end node
✅ No cycles (must be DAG)
✅ All nodes reachable
✅ Valid node types only

📊 Advanced Features

Transaction Support

{
  "type": "createRecord",
  "data": {
    "transaction": true,
    "connection": "default"
  }
}

Retry Logic

use Yahlox\Utils\RetryPolicy;

$policy = new RetryPolicy(
    maxAttempts: 3,
    initialDelayMs: 100,
    backoffMultiplier: 2.0
);
$result = $policy->execute($operation);

Rate Limiting

use Yahlox\Utils\RateLimiter;

$limiter = new RateLimiter();
if (!$limiter->isAllowed('email_sends', 100, 3600)) {
    throw new RateLimitException('Too many emails');
}

Conditional Routing

{
  "edges": [{
    "source": "check",
    "target": "approve",
    "data": {
      "condition": "{amount} > 1000 && {status} == 'active'"
    }
  }]
}

Error Handling

{
  "type": "error",
  "data": {
    "message": "Processing failed",
    "log": true,
    "stopExecution": false,
    "storeAs": "error_info"
  }
}

🧪 Testing

# Run tests
composer test

# With coverage
composer test:coverage

# Static analysis
composer analyze

# Code quality checks
composer rector

📝 Configuration

PHPStan

Static analysis is configured in phpstan.neon at level 8 (maximum strictness).

PHP CS Fixer

Code style is PSR-12 with strict rules. Run:

composer fix

GitHub Actions

CI/CD pipeline runs on push and PR:

Tests on PHP 8.0-8.3
PHPStan analysis
Code style checks
Security scanning

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE file for details.

🆘 Support

🙏 Acknowledgments

Built with PHP 8 best practices
Inspired by ReactFlow and modern workflow engines
Security-first design approach

📋 Changelog

See MIGRATION.md for detailed changelog and upgrade information.

Made with ❤️ by the Yahlox team

yahlox / processor

Maintainers

Package info

Statistics

Security