-
-
Notifications
You must be signed in to change notification settings - Fork 0
YAML Flow Structure
Jean-Marc Strauven edited this page Aug 6, 2025
·
1 revision
β Understanding YAML Flows | Home | PHP Steps β
Complete reference for Laravel Flowpipe YAML flow syntax and structure.
# =============================================================================
# FLOW METADATA
# =============================================================================
flow: string # Required: Unique flow identifier
description: string # Required: Human-readable description
version: string # Optional: Flow version (e.g., "1.0", "2.1")
tags: [string, ...] # Optional: Categories/labels
timeout: integer # Optional: Max execution time in seconds
author: string # Optional: Flow author
created_at: string # Optional: Creation date
updated_at: string # Optional: Last update date
# =============================================================================
# INITIAL DATA
# =============================================================================
send: # Optional: Initial payload data
key: value # Any valid YAML data structure
nested:
data: value
arrays:
- item1
- item2
# =============================================================================
# WORKFLOW STEPS
# =============================================================================
steps: # Required: Array of steps
- type: action|closure|group|nested|foreach
name: string # Optional: Step identifier
description: string # Optional: Step description
class: string # For action steps: PHP class name
action: string # For closure steps: closure identifier
config: {} # Optional: Step-specific configuration
timeout: integer # Optional: Step timeout in seconds
on_error: stop|continue|retry # Optional: Error handling behavior
retry_attempts: integer # Optional: Number of retry attempts
when: condition # Optional: Conditional execution
Execute PHP classes implementing FlowStep
:
- type: action
name: validate-input # Optional: Step identifier
class: App\Steps\ValidateStep # Required: Fully qualified class name
description: Validate user input data
config: # Optional: Passed to step constructor
rules:
- required
- email
timeout: 30
timeout: 60 # Optional: Step-specific timeout
on_error: stop # Optional: stop|continue|retry
retry_attempts: 3 # Optional: Number of retries
when: # Optional: Conditional execution
field: validation_enabled
operator: equals
value: true
Execute predefined PHP closures:
- type: closure
name: transform-data
action: uppercase_name # Closure identifier
description: Convert name to uppercase
config: # Passed to closure
case: upper
when:
field: transform_enabled
operator: equals
value: true
Execute reusable step collections:
- type: group
name: user-validation # Group name (references groups/user-validation.yaml)
description: Validate user data
config: # Passed to all group steps
strict_mode: true
when:
field: validation_required
operator: equals
value: true
Create inline sub-workflows:
- type: nested
name: payment-processing
description: Process payment securely
timeout: 120 # Timeout for entire nested flow
steps: # Inline step definitions
- type: action
class: ValidatePaymentStep
- type: action
class: ProcessPaymentStep
config:
gateway: stripe
on_error: stop # Error handling for nested flow
Iterate over arrays:
- type: foreach
name: process-items
array: items # Field name containing array
description: Process each item individually
timeout: 300 # Total timeout for all iterations
steps: # Steps executed for each item
- type: action
class: ValidateItemStep
- type: action
class: ProcessItemStep
on_error: continue # continue|stop (what to do if one item fails)
when:
field: status # Field to check in payload
operator: equals # Comparison operator
value: active # Value to compare against
# Equality
operator: equals # field == value
operator: not_equals # field != value
# Comparison
operator: greater_than # field > value
operator: less_than # field < value
operator: greater_than_or_equal # field >= value
operator: less_than_or_equal # field <= value
# String operations
operator: contains # string contains substring
operator: not_contains # string does not contain substring
operator: starts_with # string starts with value
operator: ends_with # string ends with value
# Array operations
operator: in # value in array
operator: not_in # value not in array
# Existence
operator: exists # field exists in payload
operator: not_exists # field does not exist in payload
# Type checking
operator: is_null # field is null
operator: is_not_null # field is not null
operator: is_empty # field is empty ([], "", null, 0)
operator: is_not_empty # field is not empty
# Multiple conditions (AND)
when:
all:
- field: status
operator: equals
value: active
- field: verified
operator: equals
value: true
# Multiple conditions (OR)
when:
any:
- field: role
operator: equals
value: admin
- field: role
operator: equals
value: moderator
# Nested conditions
when:
all:
- field: user_type
operator: equals
value: premium
- any:
- field: country
operator: equals
value: US
- field: country
operator: equals
value: CA
steps:
- condition:
field: payment_required
operator: equals
value: true
then: # Steps executed if condition is true
- type: action
class: ProcessPaymentStep
- type: action
class: SendReceiptStep
else: # Steps executed if condition is false
- type: action
class: MarkAsFreeStep
- type: action
class: SendConfirmationStep
flow: my-flow
description: Example flow
timeout: 300 # Global timeout for entire flow
parallel: true # Enable parallel execution where possible
trace: true # Enable detailed tracing
queue: # Queue configuration
connection: redis
queue: workflows
delay: 60 # Delay in seconds
- type: action
class: ApiCallStep
config: # Passed to step constructor/handle method
endpoint: https://api.example.com
method: POST
timeout: 30
headers:
Authorization: Bearer token
Content-Type: application/json
retry:
attempts: 3
delay: 1000 # Milliseconds
backoff: exponential # linear|exponential
- type: action
class: ApiCallStep
on_error: retry # stop|continue|retry
retry_attempts: 3
retry_delay: 1000 # Milliseconds between retries
retry_backoff: exponential # linear|exponential
fallback: # Fallback step if all retries fail
type: action
class: UseCachedDataStep
flow: my-flow
description: Example with error handling
on_error: compensate # stop|continue|compensate
compensation: # Steps to run if flow fails
- type: action
class: RollbackChangesStep
- type: action
class: NotifyAdminStep
steps:
- type: parallel
name: concurrent-operations
description: Run steps in parallel
steps:
- type: action
class: SendEmailStep
- type: action
class: UpdateCacheStep
- type: action
class: LogEventStep
wait_for: all # all|any|number (e.g., 2)
timeout: 60 # Timeout for parallel execution
- type: dynamic
name: generate-steps
generator: generate_user_steps # PHP method that returns step array
config:
template: user_processing
count: "{{ user_count }}" # Template variable
send:
user_id: 123
environment: production
steps:
- type: action
class: ApiCallStep
config:
endpoint: "https://{{ environment }}.api.example.com/users/{{ user_id }}"
timeout: "{{ timeout | default: 30 }}"
# This is a full-line comment
flow: my-flow # This is an inline comment
# Multi-line comments
# can span multiple lines
# for detailed explanations
description: |
This is a multi-line description
that preserves line breaks and
can contain detailed documentation.
flow: ecommerce-order-processing
description: |
Complete e-commerce order processing workflow.
This flow handles:
1. Order validation and inventory checks
2. Payment processing with retry logic
3. Fulfillment and shipping
4. Customer notifications
Expected payload structure:
- order_id: string
- items: array of {sku, quantity, price}
- customer: {id, email, address}
- payment_method: string
version: "2.1"
author: "Development Team"
tags: [ecommerce, orders, payment, fulfillment]
# Initial test data for development
send:
order_id: "ORD-12345"
# ... rest of test data
# Use kebab-case for names
- type: action
name: validate-user-input
class: ValidateUserInputStep
# Use descriptive, action-oriented names
- type: action
name: send-welcome-email
class: SendWelcomeEmailStep
steps:
# Group validation steps
- type: group
name: input-validation
# Group business logic steps
- type: group
name: order-processing
# Group notification steps
- type: group
name: notifications
- type: action
class: CriticalOperationStep
on_error: retry
retry_attempts: 3
retry_backoff: exponential
fallback:
type: action
class: SafeFallbackStep
flow: complex-workflow
description: |
Detailed description of what this workflow does,
when it should be used, and any important considerations.
steps:
- type: action
name: critical-step
class: CriticalStep
description: |
This step performs a critical operation that:
- Must not fail in production
- Has a 30-second timeout
- Requires admin permissions
- PHP Steps - Create custom step classes
- Step Groups - Organize reusable components
- Error Handling - Advanced error strategies
- Conditions & Branching - Complex conditional logic
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