Installation

Alpha notice: DBFlow packages are in active alpha development. dbflowlabs/core and dbflowlabs/filament are available on Packagist (pin tags such as 0.1.0-alpha.1). Path repositories and private VCS sources remain supported for local package development.

Requirements

DBFlow Filament (the Standard UI layer) additionally requires Filament 5.6+.

If you only need the workflow runtime without a Filament admin panel, you can use DBFlow Core on its own.

Quick install

The fastest path to a running workflow runtime:

composer require dbflowlabs/core

php artisan vendor:publish --tag=dbflow-migrations

php artisan migrate

Pin a specific release in production:

composer require dbflowlabs/core:0.1.0-alpha.1

Attach to your model

Add the HasWorkflow trait to any Eloquent model you want to run workflows on:

use DbflowLabs\Core\Traits\HasWorkflow;

class Refund extends Model
{
    use HasWorkflow;
}

For transition conditions and richer host integration, your model may also implement Workflowable and WorkflowContextInterface. See Eloquent Models when you need variables or business keys.

Next: Build Your First Workflow →

Configure Core (config/dbflow.php)

Publish config when you need to customize auth, binding mode, or feature flags:

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

Published config keys:

Database tables

After php artisan migrate, DBFlow creates:

• dbflow_workflows — registered workflow definitions (draft and published metadata)
• dbflow_workflow_versions — versioned JSON definitions
• dbflow_workflow_instances — per-subject workflow runs (includes active_key for concurrency)
• dbflow_workflow_tasks — pending approval tasks
• dbflow_workflow_task_assignments — per-user task assignments
• dbflow_workflow_logs — full history of workflow events

No manual service provider registration is needed — DBFlow Core uses Laravel package auto-discovery (DbflowLabs\Core\Providers\DBFlowServiceProvider).

Advanced host integration

Before calling DBFlow::start() in production, complete Advanced Host Integration:

1. Register WorkflowDefinitionProvider classes in a host service provider
2. Register AssigneeResolver keys when definitions use callback or permission assignees
3. Run SyncWorkflowDefinitions (custom Artisan command or deploy hook)
4. Add start / inbox / business guards in your application (Core has no UI)

This step is intentionally separate from the quick install above. Follow Build Your First Workflow first, then wire production integration.

Install DBFlow Filament (optional)

If you are using Filament 5 and want the Standard UI pages:

composer require "dbflowlabs/filament:0.1.0-alpha.1@alpha" "dbflowlabs/core:^0.1.0-alpha.1@alpha"

Use @alpha when your project minimum-stability is stable (the Laravel default). dbflowlabs/core is also installed as a dependency if not already present.

Publish Filament config before exposing the panel in shared environments:

php artisan vendor:publish --tag=dbflow-filament-config

Set permission_checker_class to a host implementation. The package default (AllowAllPermissionChecker) allows every authenticated user to access workflow pages and approve tasks.

Register the package pages and resources in your Filament panel provider (the package does not auto-register during boot()):

use DbflowLabs\Filament\Support\DBFlowFilamentPanel;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    $panel = $panel
        ->id('admin')
        // ... your existing panel configuration
    ;

    if ($this->shouldRegisterDbflow()) {
        return DBFlowFilamentPanel::register($panel);
    }

    return $panel;
}

Gate registration on both config('dbflow.enabled') and config('dbflow-filament.enabled') (plus any host pilot flag). DBFlowFilamentPanel does not read dbflow.enabled by itself.

This adds:

• My Tasks (MyWorkflowTasks) — /admin/dbflow/my-workflow-tasks by default
• Workflow Instances list and detail pages (WorkflowInstances, ViewWorkflowInstance)
• Workflow definitions resource (WorkflowResource) — /admin/workflows (Filament resource slug, not under dbflow prefix)
• Timeline rendering via WorkflowInstanceTimelinePresenter

After code-first SyncWorkflowDefinitions, the definition edit form only appears when a draft exists. See Filament UI → Code-synced workflows.

Publish optional views or translations:

php artisan vendor:publish --tag=dbflow-filament-views
php artisan vendor:publish --tag=dbflow-filament-translations

Install DBFlow Filament Pro (optional, Early Access)

Pro is a commercial add-on in Early Access. It depends on both Core and Standard Filament packages. DBFlow Pro Early Access is available at $129/year — purchases are processed by Creem.

Private Composer package access will be provided to active Pro customers. Some delivery steps may be manual during Early Access. After you receive credentials:

composer require dbflowlabs/filament-pro

After install, publish Pro config and register canvas assets:

php artisan vendor:publish --tag=dbflow-filament-pro-config
php artisan filament:assets

Pro registers ProCanvasField through the Standard workflow_definition_editor_resolver hook. Visual authoring capabilities are still evolving during alpha.

Configure a license key (Pro only)

Core runtime usage during alpha does not require a license key in your application .env. For Pro features, set your license key after you are issued preview or paid access:

DBFLOW_LICENSE_KEY=DBFLOW-PRO-XXXXXXXXXXXXXXXX

Issued licenses can be managed through the Customer Portal.

Verify the installation

Run migrations and confirm the workflow tables exist:

php artisan migrate --force

If your host project defines a test script in composer.json (for example "test": "phpunit"), you can run it after installing DBFlow:

composer test

DBFlow packages ship their own PHPUnit suites; run those from the package directory when you need package-level coverage.

There is no php artisan dbflow:health command in the current alpha packages.

Local and staging environments

Hosts matching localhost, 127.0.0.1, *.test, and *.local are never counted as production domain seats. You can develop and test locally without consuming any license entitlement.

Next step

Build Your First Approval Workflow →

Then, when you are ready for production: Advanced Host Integration →