Skip to content

Configuration

Jump to bottom
Jean-Marc Strauven edited this page Aug 6, 2025 · 1 revision

⚙️ Configuration

← Artisan Commands | Home

Complete configuration reference for Laravel Flowpipe, covering all settings and customization options.

📋 Configuration File

Laravel Flowpipe uses config/flowpipe.php for all configuration. Publish it with:

php artisan vendor:publish --provider="Grazulex\LaravelFlowpipe\LaravelFlowpipeServiceProvider"

🗂️ File Paths Configuration

Flow Definitions Path

/*
|--------------------------------------------------------------------------
| Flow Definitions Path
|--------------------------------------------------------------------------
|
| Directory where your YAML flow definitions are stored.
| Relative to your Laravel application root.
|
*/
'definitions_path' => env('FLOWPIPE_DEFINITIONS_PATH', 'flows'),

Usage Examples:

// Default: flows/
'definitions_path' => 'flows',

// Organized by environment
'definitions_path' => 'workflows/' . app()->environment(),

// Multiple paths (searched in order)
'definitions_path' => [
    'flows/custom',
    'flows/default',
    'vendor/company/flows'
],

Groups Path

/*
|--------------------------------------------------------------------------
| Group Definitions Path  
|--------------------------------------------------------------------------
|
| Directory where your reusable step groups are stored.
|
*/
'groups_path' => env('FLOWPIPE_GROUPS_PATH', 'groups'),

Step Namespace

/*
|--------------------------------------------------------------------------
| Default Step Namespace
|--------------------------------------------------------------------------
|
| Default namespace for step classes when using simple class names
| in YAML files. Supports multiple namespaces.
|
*/
'step_namespace' => env('FLOWPIPE_STEP_NAMESPACE', 'App\\Flowpipe\\Steps'),

// Or multiple namespaces (searched in order)
'step_namespace' => [
    'App\\Flowpipe\\Steps',
    'App\\Workflows\\Steps', 
    'Vendor\\Package\\Steps',
],

🔍 Tracing Configuration

Basic Tracing

/*
|--------------------------------------------------------------------------
| Tracing Configuration
|--------------------------------------------------------------------------
|
| Configure execution tracing and debugging features.
|
*/
'tracing' => [
    'enabled' => env('FLOWPIPE_TRACING_ENABLED', true),
    'tracer' => env('FLOWPIPE_TRACER', 'default'),
    'store_traces' => env('FLOWPIPE_STORE_TRACES', true),
    'trace_storage_days' => env('FLOWPIPE_TRACE_STORAGE_DAYS', 30),
],

Advanced Tracing

'tracing' => [
    'enabled' => true,
    'tracer' => 'custom',
    
    // Custom tracer configuration
    'tracers' => [
        'default' => [
            'driver' => 'database',
            'table' => 'flowpipe_traces',
        ],
        'file' => [
            'driver' => 'file',
            'path' => storage_path('logs/flowpipe-traces'),
            'max_files' => 100,
        ],
        'custom' => [
            'driver' => 'custom',
            'class' => App\Flowpipe\Tracers\CustomTracer::class,
        ],
    ],
    
    // What to trace
    'trace_levels' => [
        'flow_start' => true,
        'flow_end' => true,
        'step_start' => true,
        'step_end' => true,
        'step_error' => true,
        'payload_changes' => env('FLOWPIPE_TRACE_PAYLOAD', false),
        'performance_metrics' => true,
    ],
    
    // Performance settings
    'sampling_rate' => env('FLOWPIPE_TRACE_SAMPLING', 1.0), // 0.0 to 1.0
    'max_trace_size' => env('FLOWPIPE_MAX_TRACE_SIZE', 1048576), // 1MB
],

🔄 Queue Configuration

Basic Queue Settings

/*
|--------------------------------------------------------------------------
| Queue Configuration
|--------------------------------------------------------------------------
|
| Configure queue integration for asynchronous flow execution.
|
*/
'queue' => [
    'connection' => env('FLOWPIPE_QUEUE_CONNECTION', 'default'),
    'queue' => env('FLOWPIPE_QUEUE_NAME', 'flowpipe'),
    'timeout' => env('FLOWPIPE_QUEUE_TIMEOUT', 3600),
    'tries' => env('FLOWPIPE_QUEUE_TRIES', 3),
    'backoff' => env('FLOWPIPE_QUEUE_BACKOFF', '60,300,900'),
],

Advanced Queue Configuration

'queue' => [
    'default_connection' => 'redis',
    'default_queue' => 'flowpipe',
    
    // Queue mapping by flow type
    'queue_mapping' => [
        'user-*' => 'user-flows',
        'order-*' => 'order-processing',
        'report-*' => 'reports',
        '*-heavy' => 'heavy-processing',
    ],
    
    // Connection-specific settings
    'connections' => [
        'redis' => [
            'timeout' => 3600,
            'tries' => 3,
            'backoff' => [60, 300, 900],
        ],
        'database' => [
            'timeout' => 1800,
            'tries' => 5,
            'backoff' => [30, 60, 180, 300, 600],
        ],
    ],
    
    // Priority queues
    'priorities' => [
        'critical' => 10,
        'high' => 5,
        'normal' => 0,
        'low' => -5,
        'bulk' => -10,
    ],
],

🚨 Error Handling Configuration

Global Error Settings

/*
|--------------------------------------------------------------------------
| Error Handling
|--------------------------------------------------------------------------
|
| Configure global error handling behavior.
|
*/
'error_handling' => [
    'default_strategy' => env('FLOWPIPE_ERROR_STRATEGY', 'stop'),
    'max_retries' => env('FLOWPIPE_MAX_RETRIES', 3),
    'retry_delay' => env('FLOWPIPE_RETRY_DELAY', 1000),
    'retry_backoff' => env('FLOWPIPE_RETRY_BACKOFF', 'exponential'),
    'enable_compensation' => env('FLOWPIPE_ENABLE_COMPENSATION', true),
],

Custom Error Handlers

'error_handling' => [
    // Custom error handlers by exception type
    'handlers' => [
        \Illuminate\Validation\ValidationException::class => [
            'strategy' => 'stop',
            'handler' => App\Flowpipe\ErrorHandlers\ValidationErrorHandler::class,
        ],
        \Illuminate\Http\Client\RequestException::class => [
            'strategy' => 'retry',
            'max_retries' => 5,
            'backoff' => 'exponential',
            'handler' => App\Flowpipe\ErrorHandlers\HttpErrorHandler::class,
        ],
        \Exception::class => [
            'strategy' => 'fallback',
            'handler' => App\Flowpipe\ErrorHandlers\GenericErrorHandler::class,
        ],
    ],
    
    // Circuit breaker configuration
    'circuit_breaker' => [
        'enabled' => true,
        'failure_threshold' => 5,
        'timeout' => 60000, // 60 seconds
        'half_open_timeout' => 30000, // 30 seconds
    ],
],

🔒 Security Configuration

Input Validation

/*
|--------------------------------------------------------------------------
| Security Settings
|--------------------------------------------------------------------------
|
| Configure security-related settings.
|
*/
'security' => [
    // Payload validation
    'validate_payload' => env('FLOWPIPE_VALIDATE_PAYLOAD', true),
    'max_payload_size' => env('FLOWPIPE_MAX_PAYLOAD_SIZE', 1048576), // 1MB
    'allowed_payload_types' => ['array', 'string', 'integer', 'float', 'boolean'],
    
    // Step execution security
    'allowed_step_namespaces' => [
        'App\\Flowpipe\\Steps',
        'App\\Workflows\\Steps',
        // Add trusted namespaces only
    ],
    
    // Dangerous functions/classes restrictions
    'restricted_functions' => [
        'exec', 'shell_exec', 'system', 'passthru',
        'file_get_contents', 'file_put_contents',
        'eval', 'assert',
    ],
],

Rate Limiting

'security' => [
    'rate_limiting' => [
        'enabled' => true,
        'max_flows_per_minute' => 60,
        'max_flows_per_hour' => 1000,
        'throttle_key' => 'ip', // ip, user, custom
    ],
],

📊 Performance Configuration

Caching

/*
|--------------------------------------------------------------------------
| Performance Settings
|--------------------------------------------------------------------------
|
| Configure caching and performance optimizations.
|
*/
'performance' => [
    'cache' => [
        'enabled' => env('FLOWPIPE_CACHE_ENABLED', true),
        'driver' => env('FLOWPIPE_CACHE_DRIVER', 'redis'),
        'ttl' => env('FLOWPIPE_CACHE_TTL', 3600),
        'prefix' => env('FLOWPIPE_CACHE_PREFIX', 'flowpipe'),
    ],
    
    // Flow definition caching
    'definition_cache' => [
        'enabled' => true,
        'ttl' => 86400, // 24 hours
        'auto_refresh' => true,
    ],
    
    // Step class caching
    'step_cache' => [
        'enabled' => true,
        'ttl' => 3600, // 1 hour
    ],
],

Memory Management

'performance' => [
    'memory' => [
        'max_payload_size' => '10M',
        'memory_limit' => '256M',
        'gc_enabled' => true,
        'gc_probability' => 1,
        'gc_divisor' => 100,
    ],
    
    // Parallel execution
    'parallel' => [
        'enabled' => true,
        'max_workers' => env('FLOWPIPE_MAX_WORKERS', 4),
        'worker_timeout' => 300,
    ],
],

🔧 Development Configuration

Debug Settings

/*
|--------------------------------------------------------------------------
| Development Settings
|--------------------------------------------------------------------------
|
| Settings for development and debugging.
|
*/
'development' => [
    'debug_mode' => env('FLOWPIPE_DEBUG', env('APP_DEBUG', false)),
    'log_level' => env('FLOWPIPE_LOG_LEVEL', 'info'),
    'profiling_enabled' => env('FLOWPIPE_PROFILING', false),
    
    // Hot reloading
    'hot_reload' => [
        'enabled' => env('FLOWPIPE_HOT_RELOAD', false),
        'watch_paths' => [
            'flows/',
            'groups/',
            'app/Flowpipe/',
        ],
    ],
    
    // Testing helpers
    'testing' => [
        'fake_external_apis' => env('FLOWPIPE_FAKE_APIS', false),
        'mock_email_sending' => env('FLOWPIPE_MOCK_EMAIL', false),
        'store_test_traces' => true,
    ],
],

🌍 Environment-Specific Configuration

Production Settings

// config/flowpipe.php
'environments' => [
    'production' => [
        'tracing' => [
            'enabled' => true,
            'sampling_rate' => 0.1, // 10% sampling
            'trace_payload' => false,
        ],
        'queue' => [
            'connection' => 'redis',
            'timeout' => 7200,
            'tries' => 5,
        ],
        'security' => [
            'validate_payload' => true,
            'rate_limiting' => [
                'enabled' => true,
                'max_flows_per_minute' => 100,
            ],
        ],
    ],
    
    'staging' => [
        'tracing' => [
            'enabled' => true,
            'sampling_rate' => 0.5, // 50% sampling
            'trace_payload' => true,
        ],
        'development' => [
            'debug_mode' => true,
            'profiling_enabled' => true,
        ],
    ],
    
    'local' => [
        'tracing' => [
            'enabled' => true,
            'sampling_rate' => 1.0, // 100% sampling
            'trace_payload' => true,
        ],
        'development' => [
            'debug_mode' => true,
            'hot_reload' => ['enabled' => true],
        ],
    ],
],

📧 Notification Configuration

Email Notifications

/*
|--------------------------------------------------------------------------
| Notification Settings
|--------------------------------------------------------------------------
|
| Configure notification channels and settings.
|
*/
'notifications' => [
    'channels' => [
        'email' => [
            'enabled' => true,
            'driver' => 'mail',
            'from' => [
                'address' => env('MAIL_FROM_ADDRESS'),
                'name' => env('MAIL_FROM_NAME'),
            ],
        ],
        'slack' => [
            'enabled' => env('FLOWPIPE_SLACK_ENABLED', false),
            'webhook_url' => env('FLOWPIPE_SLACK_WEBHOOK'),
            'channel' => env('FLOWPIPE_SLACK_CHANNEL', '#alerts'),
        ],
    ],
    
    // When to send notifications
    'triggers' => [
        'flow_failed' => ['email', 'slack'],
        'flow_completed' => [],
        'step_failed' => ['email'],
        'performance_degraded' => ['slack'],
    ],
    
    // Notification recipients
    'recipients' => [
        'developers' => [
            '[email protected]',
            '[email protected]',
        ],
        'operations' => [
            '[email protected]',
        ],
    ],
],

🔗 Integration Configuration

External Services

/*
|--------------------------------------------------------------------------
| External Integrations
|--------------------------------------------------------------------------
|
| Configure external service integrations.
|
*/
'integrations' => [
    'monitoring' => [
        'sentry' => [
            'enabled' => env('SENTRY_LARAVEL_DSN') !== null,
            'trace_flows' => true,
            'capture_step_errors' => true,
        ],
        'datadog' => [
            'enabled' => env('DATADOG_API_KEY') !== null,
            'metrics_prefix' => 'flowpipe.',
            'trace_sampling_rate' => 0.1,
        ],
    ],
    
    'storage' => [
        's3' => [
            'enabled' => env('FLOWPIPE_S3_ENABLED', false),
            'bucket' => env('FLOWPIPE_S3_BUCKET'),
            'region' => env('FLOWPIPE_S3_REGION'),
        ],
    ],
],

📄 Complete Configuration Example

Here's a comprehensive production-ready configuration:

<?php

return [
    'definitions_path' => env('FLOWPIPE_DEFINITIONS_PATH', 'flows'),
    'groups_path' => env('FLOWPIPE_GROUPS_PATH', 'groups'),
    'step_namespace' => [
        'App\\Flowpipe\\Steps',
        'App\\Workflows\\Steps',
    ],

    'tracing' => [
        'enabled' => env('FLOWPIPE_TRACING_ENABLED', true),
        'tracer' => env('FLOWPIPE_TRACER', 'database'),
        'sampling_rate' => env('FLOWPIPE_TRACE_SAMPLING', app()->isProduction() ? 0.1 : 1.0),
        'store_traces' => true,
        'trace_storage_days' => 30,
    ],

    'queue' => [
        'connection' => env('FLOWPIPE_QUEUE_CONNECTION', 'redis'),
        'queue' => env('FLOWPIPE_QUEUE_NAME', 'flowpipe'),
        'timeout' => env('FLOWPIPE_QUEUE_TIMEOUT', 3600),
        'tries' => env('FLOWPIPE_QUEUE_TRIES', 3),
        'backoff' => [60, 300, 900],
    ],

    'error_handling' => [
        'default_strategy' => 'stop',
        'max_retries' => 3,
        'retry_delay' => 1000,
        'retry_backoff' => 'exponential',
        'enable_compensation' => true,
    ],

    'security' => [
        'validate_payload' => true,
        'max_payload_size' => 1048576,
        'allowed_step_namespaces' => [
            'App\\Flowpipe\\Steps',
            'App\\Workflows\\Steps',
        ],
        'rate_limiting' => [
            'enabled' => app()->isProduction(),
            'max_flows_per_minute' => 100,
        ],
    ],

    'performance' => [
        'cache' => [
            'enabled' => true,
            'driver' => 'redis',
            'ttl' => 3600,
        ],
        'memory' => [
            'max_payload_size' => '10M',
            'memory_limit' => '256M',
        ],
    ],

    'development' => [
        'debug_mode' => env('APP_DEBUG', false),
        'hot_reload' => [
            'enabled' => app()->isLocal(),
        ],
    ],
];

🎯 What's Next?

📚 Laravel Flowpipe Wiki

Laravel Flowpipe - YAML-driven workflow engine for Laravel

GitHub: Laravel Flowpipe Repository | Support: GitHub Issues

Quick Navigation: Home • Installation • Configuration • Commands • Examples

🔧 Developed by Grazulex

🚀 Laravel Flowpipe

🏠 Home

🏁 Getting Started

📚 Core Concepts

🚀 Advanced Features

🛠️ Tools & Configuration

📖 Examples

🔗 GitHub Repository

Clone this wiki locally