Configuration Options

Publish the configuration file with:

php artisan vendor:publish --tag="filament-flow-config"

This creates config/filament-flow.php.

Global Settings

// Enable or disable the plugin globally
'enabled' => true,

Multi-Tenancy Configuration

/**
 * The tenant model class for multi-tenancy support.
 * Set to null to disable multi-tenancy.
 *
 * Example: App\Models\Company::class, App\Models\Tenant::class
 */
'tenant_model' => null,

/**
 * The foreign key column name for tenant relationship.
 * This will be used in the workflows table.
 */
'tenant_foreign_key' => 'tenant_id',

Use Case: If your application has multiple tenants (e.g., companies, organizations), you can configure workflows per tenant. Each tenant can have their own workflow definitions in the database.

User Model Configuration

/**
 * The user model class for assignments and audit trail.
 * Defaults to Laravel's default user model.
 */
'user_model' => null, // Will fallback to config('auth.providers.users.model')

Use Case: Specify a custom user model if you're not using Laravel's default App\Models\User.

Cache

'cache' => [
    'enabled'    => true,
    'store'      => null,             // null = use the default Laravel cache store
    'ttl'        => 300,              // legacy TTL (prefer safety_ttl for event-driven invalidation)
    'safety_ttl' => 86400,            // 24h safety net — cache lives until invalidated by observers
    'prefix'     => 'filament-flow',  // cache key prefix
],

Option	Default	Description
enabled	true	Enable or disable all caching. Set to false during local development.
store	null	Cache store name from config/cache.php. null = default store.
ttl	300	Legacy TTL in seconds. Kept for backward compatibility.
safety_ttl	86400	Safety-net TTL (24 hours). Cache entries are invalidated by observers long before this expires.
prefix	filament-flow	Prefix prepended to all cache keys.

Store Support

Store	Tag Support	Invalidation
Redis (recommended)	Native Cache::tags()	Atomic, single operation
Memcached	Key-registry fallback	Iterates registry, forgets per key
File / Database	Key-registry fallback	Iterates registry, forgets per key

Redis is recommended for production because it supports native cache tags, enabling granular and atomic invalidation in a single call.

Transition History Notes

/**
 * Enable or disable logging of transition notes to history.
 */
'log_transition_notes' => true,

/**
 * Default form field name to use for transition notes.
 * If a transition form contains this field, its value is saved to history.
 * Set to null to disable automatic field detection.
 */
'transition_notes_field' => 'transition_notes',

When log_transition_notes is true, the value of the field named by transition_notes_field in a transition form is persisted to workflow_state_transitions.notes.

Form Builder Configuration

/**
 * Use the advanced FormBuilderHelper for building forms.
 * Set to false to use basic form building in HasWorkflowCreation trait.
 */
'use_form_builder_helper' => true,

Use Case: The FormBuilderHelper provides advanced form building capabilities for database-configured workflows. Set to false if you want simpler form generation.

State Access Control

'state_access' => [
    /**
     * Enable or disable state-based access control.
     * When disabled, all access checks return true.
     */
    'enabled' => true,

    /**
     * Automatically enforce access control on transitionTo() calls.
     * When enabled, unauthorized transitions throw UnauthorizedTransitionException.
     * When disabled, you must manually check canBeTransitionedBy() before calling transitionTo().
     */
    'enforce_on_transition' => true,

    /**
     * Default access rules when no state-specific rules are defined.
     * 'create' rules apply to the initial state and control who can create new records.
     */
    'defaults' => [
        'create' => ['@authenticated'],
        'view' => ['@authenticated'],
        'edit' => ['@authenticated'],
        'transition' => ['@authenticated'],
    ],

    /**
     * Roles that bypass all access checks (super admin).
     * Users with any of these roles have full access to all records.
     */
    'super_admin_roles' => ['super_admin'],

    /**
     * Custom role resolver class.
     * Must implement RoBYCoNTe\FilamentFlow\Contracts\RoleResolver.
     */
    'role_resolver' => null,

    /**
     * Custom permission resolver class.
     * Must implement RoBYCoNTe\FilamentFlow\Contracts\PermissionResolver.
     */
    'permission_resolver' => null,

    /**
     * Field name used to identify record ownership.
     * The @owner token checks if this field matches the user's ID.
     */
    'owner_field' => 'user_id',
],

Notifications

'notifications' => [
    /**
     * Enable or disable the notification system globally.
     */
    'enabled' => true,

    /**
     * Default notification channel when none is specified.
     */
    'default_channel' => 'database',

    /**
     * Queue connection for async notifications.
     */
    'queue_connection' => null,

    /**
     * Queue name for notification jobs.
     */
    'queue_name' => null,

    /**
     * Default delay in minutes for delayed notifications.
     */
    'default_delay_minutes' => 0,

    /**
     * Number of retry attempts for failed notification jobs.
     */
    'retry_attempts' => 3,

    /**
     * Backoff time in seconds between retry attempts.
     */
    'retry_backoff' => 60,

    /**
     * Enable logging of all notification dispatches.
     */
    'logging_enabled' => true,

    /**
     * Channel-specific configuration.
     */
    'channels' => [
        'database' => [
            'enabled' => true,
        ],
        'mail' => [
            'enabled' => true,
            'from_address' => null,
            'from_name' => null,
        ],
    ],

    /**
     * Default template rendering engine.
     */
    'default_template_engine' => 'plain',

    /**
     * Custom recipient resolver class.
     * Must implement RoBYCoNTe\FilamentFlow\Contracts\RecipientResolverInterface.
     * Set to null to use the default resolver.
     */
    'recipient_resolver' => null,
],

logging_enabled — When true, every notification dispatch attempt (sent, failed, or skipped) is recorded in workflow_notification_logs. Disable for high-volume workflows where audit logging is not required.

retry_attempts / retry_backoff — Configure job-level retries for failed async notification jobs. retry_backoff is in seconds.

channels — Enable or disable individual channels globally. Per-notification channels can still be toggled via workflow_notification_channels.is_active.

recipient_resolver — Provide a custom class to override how recipients are resolved. Useful when your user model or recipient logic differs from the defaults.

Scheduling

'scheduling' => [
    'enabled'   => env('FILAMENT_FLOW_SCHEDULING_ENABLED', true),
    'frequency' => 'everyFiveMinutes', // everyMinute, everyFiveMinutes, everyTenMinutes,
                                       // everyFifteenMinutes, everyThirtyMinutes, hourly, daily
],

Controls the workflow:process-schedules Artisan command that evaluates workflow_scheduled_checks. When enabled is true, the command is registered automatically in the Laravel scheduler at the configured frequency.

Set FILAMENT_FLOW_SCHEDULING_ENABLED=false in production environments where you prefer to run the command manually or via a dedicated queue worker.