PHPackages                             dbflowlabs/core - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. dbflowlabs/core

ActiveLibrary[Database & ORM](/categories/database)

dbflowlabs/core
===============

Model-first workflow engine core for Laravel applications.

0.1.0-alpha.1(today)001MITPHPPHP ^8.3CI passing

Since Jun 26Pushed todayCompare

[ Source](https://github.com/dbflow-labs/dbflow-core)[ Packagist](https://packagist.org/packages/dbflowlabs/core)[ Docs](https://github.com/dbflow-labs/dbflow-core)[ RSS](/packages/dbflowlabs-core/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (7)Versions (2)Used By (1)

DBFlow Core
===========

[](#dbflow-core)

[![Tests](https://github.com/dbflow-labs/dbflow-core/actions/workflows/tests.yml/badge.svg)](https://github.com/dbflow-labs/dbflow-core/actions)[![Latest Release](https://camo.githubusercontent.com/8389bbf792e74d74caf93b46237834f94272d323ce788da6926af895a0f38c31/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6462666c6f772d6c6162732f6462666c6f772d636f72653f696e636c7564655f70726572656c6561736573)](https://github.com/dbflow-labs/dbflow-core/releases)[![License: MIT](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP](https://camo.githubusercontent.com/f1518df04294c8236c2b7fe12f116357d0dfb9a13d5f1f3003f545e198cafed0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e33253230253743253230382e342d3737376262342e737667)](composer.json)[![Laravel](https://camo.githubusercontent.com/354f6734d1b97e7b34c93c5345e248f4ecded77f257b73e903d88d426118b1b7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d31332e782d6666326432302e737667)](composer.json)

**Model-first workflow runtime for Laravel applications.**

DBFlow Core lets you add approval workflows, tasks, transitions, rejection flows, and audit logs to any Eloquent model without building a heavy BPM system from scratch.

It is the open-source runtime foundation of the DBFlow ecosystem. Host-specific business adapters, Filament UI packages, and the visual workflow Builder are distributed separately.

Warning

DBFlow Core is currently in alpha. Public APIs and database schema details may change before v1.0.0. Pin exact tags for production experiments.

Contents
--------

[](#contents)

- [Package Overview](#package-overview)
- [What Core Provides](#what-core-provides)
- [Requirements](#requirements)
- [Installation](#installation)
- [Laravel Integration](#laravel-integration)
- [Configuration](#configuration)
- [Minimal Usage](#minimal-usage)
- [Package Boundaries](#package-boundaries)
- [DBFlow Ecosystem](#dbflow-ecosystem)
- [Development](#development)
- [Versioning](#versioning)
- [Support](#support)
- [License](#license)

Package Overview
----------------

[](#package-overview)

ItemValue**Package name**`dbflowlabs/core`**Namespace**`DbflowLabs\Core`**License**[MIT](LICENSE)**Repository**[github.com/dbflow-labs/dbflow-core](https://github.com/dbflow-labs/dbflow-core)**Default branch**`main`**Stability**`Alpha (v0.1.x)`**Author**Baron Wang **Laravel compatibility**`13.x`**PHP requirements**`8.3`, `8.4`What Core Provides
------------------

[](#what-core-provides)

DBFlow Core provides the runtime foundation required for deterministic, schema-driven workflow execution:

- **Workflow definitions** — code-first and array-hydrated workflow schema management.
- **Topology validation** — validation for nodes, transitions, and directed workflow routing.
- **State machine persistence** — workflow instances, task states, assignments, and transition records.
- **Task runtime** — task creation, assignment handling, approval actions, rejection actions, and cancellation.
- **Approval modes** — runtime support for common approval strategies.
- **Transition handling** — controlled movement between workflow nodes.
- **Append-only audit logs** — historical workflow activity records for traceability.
- **Extension points** — assignee resolvers, workflow hooks, condition handling, and action handlers.

Note

Core focuses entirely on the workflow runtime engine. It contains no frontend assets, Filament resources, visual canvas, or host-specific business models.

Requirements
------------

[](#requirements)

- PHP `^8.3`
- Laravel `13.x` / Illuminate `^13.0` components
- SQLite, MySQL, or PostgreSQL
- A host user model, usually `App\Models\User`
- A `users` table, or equivalent host table, for actor and assignee references

Warning

**Alpha compatibility note:** Actor and assignee database columns currently use unsigned `bigint` foreign keys mapping to `users.id`. Applications using UUID or ULID primary keys for users should plan a compatibility migration or customize their mappings before production deployment.

Installation
------------

[](#installation)

### Packagist Installation

[](#packagist-installation)

When the package is available on Packagist:

```
composer require dbflowlabs/core
```

### Local Path Repository

[](#local-path-repository)

For local development, add a Composer path repository inside your host application's `composer.json`:

```
{
  "repositories": [
    {
      "type": "path",
      "url": "../dbflow-core",
      "options": {
        "symlink": true
      }
    }
  ],
  "minimum-stability": "dev",
  "prefer-stable": true,
  "require": {
    "dbflowlabs/core": "*@dev"
  }
}
```

Then install the package:

```
composer require dbflowlabs/core:*@dev
```

Releases are tagged on GitHub, for example:

```
v0.1.0-alpha.1

```

Laravel Integration
-------------------

[](#laravel-integration)

### Service Provider

[](#service-provider)

The core service provider is registered automatically via Laravel package discovery:

```
DbflowLabs\Core\Providers\DBFlowServiceProvider::class
```

### Publish Configuration

[](#publish-configuration)

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

This publishes:

```
config/dbflow.php

```

Publishing the configuration file is optional, but recommended when the host application needs to customize authentication, user resolution, or runtime feature flags.

### Publish Migrations

[](#publish-migrations)

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

DBFlow Core creates only `dbflow_*` tables, preserving schema separation from host application tables.

During local package development, migrations may also be loaded directly through Laravel's `loadMigrationsFrom()` behavior.

Configuration
-------------

[](#configuration)

Example `config/dbflow.php`:

```
return [
    'enabled' => env('DBFLOW_ENABLED', true),

    'auth' => [
        'model' => env('DBFLOW_AUTH_MODEL', 'App\\Models\\User'),
        'guard' => env('DBFLOW_AUTH_GUARD', 'web'),
        'resolver' => DbflowLabs\Core\Support\ConfigUserResolver::class,
    ],

    'visual_builder_enabled' => env('DBFLOW_VISUAL_BUILDER_ENABLED', false),
];
```

Set the host user model explicitly:

```
DBFLOW_AUTH_MODEL=App\Models\User
```

`ConfigUserResolver` supports integer and string primary keys at runtime.

Note

`DBFLOW_ENABLED` does not fully disable service provider registration yet during the alpha cycle.

Minimal Usage
-------------

[](#minimal-usage)

### 1. Register Runtime Definitions

[](#1-register-runtime-definitions)

Register workflow definitions, assignee resolvers, and hooks during application boot. A host service provider is usually the best place for this.

```
use DbflowLabs\Core\DBFlow;
use DbflowLabs\Core\Services\AssigneeResolverRegistry;
use DbflowLabs\Core\Services\WorkflowDefinitionRegistry;
use DbflowLabs\Core\Services\WorkflowHooksRegistry;

DBFlow::registerDefinitionProvider(
    app(WorkflowDefinitionRegistry::class),
    $myDefinitionProvider,
);

DBFlow::registerAssigneeResolver(
    app(AssigneeResolverRegistry::class),
    'finance_team',
    $myAssigneeResolver,
);

DBFlow::registerWorkflowHooks(
    app(WorkflowHooksRegistry::class),
    'refund_approval',
    MyRefundHooks::class,
);
```

### 2. Start a Workflow

[](#2-start-a-workflow)

Start a workflow for an Eloquent model:

```
use DbflowLabs\Core\DBFlow;

$instance = DBFlow::start(
    'refund_approval',
    $refundRequest,
    auth()->user(),
);
```

### 3. Approve a Task

[](#3-approve-a-task)

Approve a workflow task:

```
DBFlow::approve(
    $task,
    auth()->user(),
    'Approved.',
);
```

Package Boundaries
------------------

[](#package-boundaries)

DBFlow Core is intentionally small and runtime-focused.

The following are outside this package:

- Host business adapters, such as ERP-specific approval logic
- Filament resources, panels, widgets, and actions
- Visual workflow Builder UI
- Commercial Builder features
- Premium action handlers
- Enterprise white-label extensions

Unresolved premium action types raise `PremiumFeatureMissingException`.

Premium or host-specific action handlers can be registered through `ActionManager`, or provided by separate extension packages.

DBFlow Ecosystem
----------------

[](#dbflow-ecosystem)

DBFlow is designed as a layered ecosystem:

PackageRoleLicense`dbflowlabs/core`Runtime engineMIT`dbflowlabs/filament`Standard Filament UI integrationMIT / open-source`dbflowlabs/filament-pro`Visual workflow Builder and advanced UI featuresCommercialCore runs the workflow. Filament packages provide user interfaces. Host applications provide business adapters.

Development
-----------

[](#development)

Install dependencies:

```
composer install
```

Validate the package metadata:

```
composer validate --strict --no-check-lock
```

Run the test suite:

```
composer test
```

The CI pipeline validates the package against PHP 8.3 and 8.4 with PHPUnit and architecture compliance checks.

Versioning
----------

[](#versioning)

DBFlow Core is currently in active alpha development.

Until a stable `1.0.0` release is reached, public APIs and schema definitions may change as the runtime contract stabilizes.

Recommended production usage during alpha:

- Pin exact tags, such as `v0.1.0-alpha.1`
- Review release notes before upgrading
- Test workflow definitions and runtime transitions in a staging environment
- Avoid relying on undocumented internal classes

Support
-------

[](#support)

For architecture alignment or integration questions, open a GitHub Issue or contact:

- **Email:**
- **Website:** [dbflow.dev](https://dbflow.dev)

License
-------

[](#license)

DBFlow Core is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/295546756?v=4)[baron-dbflow](/maintainers/baron-dbflow)[@baron-dbflow](https://github.com/baron-dbflow)

---

Top Contributors

[![baron-dbflow](https://avatars.githubusercontent.com/u/295546756?v=4)](https://github.com/baron-dbflow "baron-dbflow (3 commits)")

---

Tags

approval-systemapproval-workflowaudit-logbusiness-workfloweloquentlaravelopen-corephpstate-machineworkflowworkflow-engine

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/dbflowlabs-core/health.svg)

```
[![Health](https://phpackages.com/badges/dbflowlabs-core/health.svg)](https://phpackages.com/packages/dbflowlabs-core)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[laravel/ai

The official AI SDK for Laravel.

9782.1M162](/packages/laravel-ai)[spatie/laravel-health

Monitor the health of a Laravel application

87411.3M153](/packages/spatie-laravel-health)[watson/validating

Eloquent model validating trait.

9733.4M53](/packages/watson-validating)[clickbar/laravel-magellan

This package provides functionality for working with the postgis extension in Laravel.

438834.4k1](/packages/clickbar-laravel-magellan)[reedware/laravel-relation-joins

Adds the ability to join on a relationship by name.

2121.2M16](/packages/reedware-laravel-relation-joins)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)