README

A powerful automation system for Laravel applications, built with modern PHP 8.4+ and Laravel 12+ features.

🚀 Features

Modern PHP 8.4+: Final classes, strict types, return types, readonly properties
Laravel 12+: Latest Laravel features and best practices
Repository Pattern: Clean separation of data access logic
Action-Based Controllers: Single responsibility actions for better maintainability
Multiple Trigger Types: Manual, Schedule, Webhook, Event
Rich Action Library: HTTP requests, emails, database queries, file operations, queue jobs, custom code
Web Interface: Beautiful dashboard for managing workflows
API Endpoints: Full REST API for integration
Security Features: Webhook signature verification, IP whitelisting, rate limiting
Monitoring: Execution history, statistics, and logging

📋 Requirements

PHP 8.4+
Laravel 12+
MySQL/PostgreSQL/SQLite

🛠 Installation

Install the package:

composer require laravelplus/automations

Publish the configuration:

php artisan vendor:publish --tag=automations-config

Run migrations:

php artisan migrate

Add to your .env:

AUTOMATIONS_ENABLED=true
AUTOMATIONS_QUEUE=default

🏗 Architecture

Repository Pattern

// Interface
interface WorkflowRepositoryInterface
{
    public function findById(int $id): ?Workflow;
    public function create(array $data): Workflow;
    public function update(Workflow $workflow, array $data): Workflow;
    // ...
}

// Implementation
final class WorkflowRepository implements WorkflowRepositoryInterface
{
    // Implementation with modern PHP features
}

Action-Based Controllers

final readonly class CreateWorkflowAction
{
    public function __construct(
        private WorkflowRepositoryInterface $workflowRepository
    ) {}

    public function __invoke(Request $request): JsonResponse|RedirectResponse
    {
        // Single responsibility action
    }
}

Modern Models

final class Workflow extends Model
{
    use HasFactory, SoftDeletes;

    protected $casts = [
        'status' => WorkflowStatus::class,
        'trigger_type' => TriggerType::class,
    ];

    public function isReadyForExecution(): bool
    {
        return $this->status === WorkflowStatus::ACTIVE &&
            ($this->next_execution_at === null || $this->next_execution_at <= now());
    }
}

🎯 Usage

Creating Workflows

use LaravelPlus\Automations\Facades\Automation;

// Create a workflow
$workflow = Workflow::create([
    'name' => 'Daily Report',
    'trigger_type' => TriggerType::SCHEDULE,
    'trigger_config' => ['cron_expression' => '0 9 * * *'],
    'definition' => [
        'nodes' => [
            [
                'id' => 'trigger',
                'type' => 'trigger',
                'data' => ['type' => 'schedule']
            ],
            [
                'id' => 'http_request',
                'type' => 'http_request',
                'data' => [
                    'url' => 'https://api.example.com/data',
                    'method' => 'GET'
                ]
            ],
            [
                'id' => 'email',
                'type' => 'email',
                'data' => [
                    'to' => 'admin@example.com',
                    'subject' => 'Daily Report',
                    'body' => '{{http_request.response}}'
                ]
            ]
        ],
        'connections' => [
            ['from' => 'trigger', 'to' => 'http_request'],
            ['from' => 'http_request', 'to' => 'email']
        ]
    ],
    'status' => WorkflowStatus::ACTIVE,
]);

Executing Workflows

// Manual execution
$execution = Automation::executeWorkflow($workflow, ['custom_data' => 'value']);

// Via API
POST /api/automations/workflows/{workflow}/execute
{
    "input_data": {
        "user_id": 123,
        "custom_field": "value"
    }
}

Webhook Triggers

// Create webhook-enabled workflow
$workflow = Workflow::create([
    'name' => 'Webhook Handler',
    'trigger_type' => TriggerType::WEBHOOK,
    'webhook_config' => [
        'name' => 'Order Created',
        'method' => 'POST',
        'require_signature' => true,
        'allowed_ips' => ['192.168.1.1']
    ],
    // ... workflow definition
]);

// Webhook endpoint: POST /api/automations/webhook/{endpoint}

🔧 Configuration

// config/automations.php
return [
    'enabled' => env('AUTOMATIONS_ENABLED', true),
    'queue' => env('AUTOMATIONS_QUEUE', 'default'),
    'timeout' => env('AUTOMATIONS_TIMEOUT', 300),
    'max_retries' => env('AUTOMATIONS_MAX_RETRIES', 3),
    'cleanup_days' => env('AUTOMATIONS_CLEANUP_DAYS', 30),
];

🎛 Console Commands

# Run scheduled workflows
php artisan automations:run-scheduled

# Dry run to see what would execute
php artisan automations:run-scheduled --dry-run

# List workflows
php artisan automations:list

# List with filters
php artisan automations:list --status=active --type=schedule --format=json

🌐 Web Interface

Visit /automations to access the dashboard:

Dashboard: Overview with statistics
Workflows: Create, edit, and manage workflows
Executions: Monitor execution history
Webhooks: Manage webhook endpoints

🔌 API Endpoints

Workflows

GET    /api/automations/workflows
POST   /api/automations/workflows
GET    /api/automations/workflows/{id}
PUT    /api/automations/workflows/{id}
DELETE /api/automations/workflows/{id}
POST   /api/automations/workflows/{id}/execute
POST   /api/automations/workflows/{id}/activate
POST   /api/automations/workflows/{id}/deactivate

Executions

GET    /api/automations/executions
GET    /api/automations/executions/{id}
POST   /api/automations/executions/{id}/retry
POST   /api/automations/executions/{id}/cancel

Webhooks

POST   /api/automations/webhook/{endpoint}
GET    /api/automations/webhook/{endpoint}

🛡 Security

Webhook Signatures: HMAC-SHA256 signature verification
IP Whitelisting: Restrict webhook access by IP
Rate Limiting: Prevent abuse with configurable limits
Input Validation: Comprehensive validation for all inputs
Sandboxed Code: Safe execution of custom code

📊 Monitoring

Execution History: Complete audit trail
Statistics: Success rates, execution times
Logging: Detailed logs for debugging
Error Handling: Graceful error recovery

🧪 Testing

# Run tests
composer test

# Run with coverage
composer test -- --coverage

📝 License

This package is open-sourced software licensed under the MIT license.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📚 Documentation

For detailed documentation, visit docs.laravelplus.com/automations.

laravelplus / automations

Maintainers

Details