Installation

Stable release: dbflowlabs/core and dbflowlabs/filament are 1.0 stable on Packagist. dbflowlabs/filament-pro (DBFlow Pro) is 1.0 stable on the private Composer repository at packages.dbflow.dev. Use ^1.0 constraints in production for all three packages.

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

After registering workflow definition providers, sync them:

php artisan dbflow:sync

Pin a specific release in production:

composer require dbflowlabs/core:^1.0

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:

Artisan commands

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 for Core — DBFlow Core uses Laravel package auto-discovery (DbflowLabs\Core\Providers\DBFlowServiceProvider). Filament Standard and DBFlow Pro have different registration rules — see the sections below.

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 php artisan dbflow:sync (or call SyncWorkflowDefinitions from a 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:^1.0 dbflowlabs/core:^1.0

Also listed on the Filament Plugin directory.

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()).

Always register inside panel() — for Standard and Pro:

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()) {
        $panel = DBFlowFilamentPanel::register($panel);
    }

    return $panel;
}

private function shouldRegisterDbflow(): bool
{
    return (bool) config('dbflow-filament.enabled', true)
        && (bool) config('dbflow.enabled', true);
}

Why panel() and not boot()? Filament registers panel routes while panel() runs. Calling DBFlowFilamentPanel::register() later from PanelProvider::boot() can attach pages to navigation without registering matching routes, which surfaces as RouteNotFoundException (for example filament.admin.pages.dbflow.my-workflow-tasks or filament.admin.resources.*.edit).

With DBFlow Pro installed — keep registration in panel() as above. Pro's service provider may override config('dbflow-filament.workflow_resource_class') during its own boot(), but that runs after panel() has already executed. Set the Pro resource class explicitly in your published config/dbflow-filament.php (or a host subclass):

use DbflowLabs\FilamentPro\Filament\Resources\WorkflowResource as ProWorkflowResource;

// config/dbflow-filament.php
'workflow_resource_class' => ProWorkflowResource::class,

If you subclass WorkflowResource for host-specific edit pages or draft seeding, point workflow_resource_class at your subclass instead. See Filament UI → Custom WorkflowResource.

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 php artisan dbflow:sync, 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 Pro (optional)

DBFlow Pro 1.0 is the stable commercial visual workflow builder. It depends on Core and Filament Standard at ^1.0. The launch offer is $99 for the first year, then $129/year after the first year — purchases use secure checkout through our payment provider.

After purchase, configure the private Composer repository and authenticate with credentials from the Customer Portal. Private Composer access and new downloads require an active DBFlow Pro license:

{
  "repositories": [{ "type": "composer", "url": "https://packages.dbflow.dev" }],
  "require": {
    "dbflowlabs/core": "^1.0",
    "dbflowlabs/filament": "^1.0",
    "dbflowlabs/filament-pro": "^1.0"
  },
  "minimum-stability": "stable",
  "prefer-stable": true
}

composer require dbflowlabs/filament-pro:^1.0

Register the Pro service provider

dbflowlabs/filament-pro ships DbflowLabs\FilamentPro\Providers\DBFlowFilamentProServiceProvider. It registers Pro canvas assets, swaps in the Pro-aware WorkflowResource, and wires ProCanvasWorkflowDefinitionEditorResolver through Filament Standard.

The source composer.json in the Pro package includes Laravel auto-discovery metadata:

"extra": {
  "laravel": {
    "providers": [
      "DbflowLabs\\FilamentPro\\Providers\\DBFlowFilamentProServiceProvider"
    ]
  }
}

After composer require, confirm the provider is loaded (for example with php artisan about, or by inspecting loaded providers in tinker). You should see DbflowLabs\FilamentPro\Providers\DBFlowFilamentProServiceProvider.

If it is missing, register it manually in bootstrap/providers.php before your Filament PanelProvider:

use DbflowLabs\FilamentPro\Providers\DBFlowFilamentProServiceProvider;

return [
    // ...
    DBFlowFilamentProServiceProvider::class,
    App\Providers\Filament\AdminPanelProvider::class,
];

Why manual registration happens: Some private Composer dist installs do not expose extra.laravel in the host project's composer.lock / installed-package metadata, so Laravel package discovery never picks up the Pro provider even though vendor/dbflowlabs/filament-pro/composer.json contains the extra block. Manual registration in bootstrap/providers.php is the supported host workaround until the dist metadata is fixed on packages.dbflow.dev.

Keep DBFlowFilamentPanel::register() inside panel() (see Install DBFlow Filament →) and set workflow_resource_class explicitly in config/dbflow-filament.php when Pro is installed.

Publish Pro config and register canvas assets

After install, publish Pro config and register canvas assets:

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

If vendor:publish --tag=dbflow-filament-pro-config reports no publishable resources, copy the default config manually:

cp vendor/dbflowlabs/filament-pro/config/dbflow-filament-pro.php config/dbflow-filament-pro.php

The provider still merges package defaults when the published file is absent; copying is only needed when you want host-specific overrides.

Pro registers ProCanvasField through the Standard workflow_definition_editor_resolver hook once DBFlowFilamentProServiceProvider is loaded.

Troubleshooting Pro install

Configure a license key (Pro only)

Core does not require a license key. For Pro features, set your license key after purchase:

DBFLOW_LICENSE_KEY=DBFLOW-PRO-XXXXXXXXXXXXXXXX

Issued licenses can be managed through the Customer Portal. Register one production domain there during the active license period.

If your DBFlow Pro license expires, you may continue using the last Pro version installed during the active license period. Existing production deployments and previously registered production domains continue to work, but private Composer access, new downloads, newly released Pro updates, email support, and production domain changes require renewal.

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 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 →