The structure Laravel leaves to you, declared in PHP attributes.

larafly adds command handlers, repositories, and a transactional outbox to a Laravel service. Its packages bring sagas, workflows, event sourcing, brokers, webhooks, and method security.

  1. 01 Application composition
  2. 02 Domain and repositories
  3. 03 Commands and queries
  4. 04 Event-driven integration
  5. 05 Identity and method policies
  6. 06 Business coordination
  7. 07 Operations and telemetry
  8. 08 Rollout and testing
PHP 8.3+ · Laravel 13 · Eloquent · Composer
Scroll to explore

Native stack and framework

What larafly adds to Laravel and Eloquent.

Laravel routes and validates, and Eloquent persists. larafly’s cache command compiles your attributes into manifests and proxies for deployment.

Application composition

A cached boot and a development boot apply one advice plan, through proxies from the runtime’s generator.

With Laravel and Eloquent alone, your team builds
Discovery and boot conventions across Laravel service providers, the container, and deployment caches.
larafly provides
Ordered boot passes, conditional definitions, and firefly:cache manifests with generated proxies.
How it works

FireflyKernel runs its boot passes in pipeline order, once per phase. firefly:cache writes the manifests and a proxy class for each planned class.

Generated policies need proxyable classes and methods, which can’t be final.

See the implementation

Domain and repositories

A repository runs explicit or derived queries, and an event-sourced aggregate keeps its history in an event store.

With Laravel and Eloquent alone, your team builds
Repository conventions around Eloquent, and event history with versions and snapshots.
larafly provides
EloquentRepository with derived and explicit queries, and an event store with snapshots, projections, and upcasters.
How it works

EloquentRepository derives a query from a method’s name. The event store rejects appends from a stale version.

With the database checkpoint store, a restarted projection resumes where it stopped.

See the implementation

Commands and queries

Security and telemetry reach every handler through the bus, whatever entry point sent the command.

With Laravel and Eloquent alone, your team builds
Laravel validation, gates, container calls, and events around a handler.
larafly provides
A command bus with validation, authorization, and metrics, plus query caching that events invalidate.
How it works

CqrsAutoConfiguration starts the bus with a no-op tracer and query cache. A bridge passes command events to a bound event publisher.

Enable the security and observability modules to replace the bus’s allow-all and no-op defaults.

See the implementation

Event-driven integration

Code publishes and listens through one API, and firefly.eda.provider picks memory, a queue, the database outbox, RabbitMQ, or Kafka.

With Laravel and Eloquent alone, your team builds
Broker envelopes, webhook verification, and callback delivery, on top of Laravel events and queues.
larafly provides
An outbox on any Laravel database, Kafka and RabbitMQ adapters, verified webhooks, and signed callbacks.
How it works

DomainEventDispatcher hands tracked events to a pre-commit hook. The hook writes them to the outbox inside the transaction, and consumers claim rows by lease.

Events stay in memory until you choose a provider. Brokers need their own infrastructure.

See the implementation

Identity and method policies

The signed-in principal reaches command authorization, method security, and auditing, and each method’s policies apply in a fixed order.

With Laravel and Eloquent alone, your team builds
Auth checks, auditing, and method wrappers in a fixed order, fed from Laravel authentication and policies.
larafly provides
Bus authorizers, a data auditor, method security, and compiled advice for resilience and transactions.
How it works

With firefly.security.enabled, the security module registers bus authorizers and a security-context auditor. Generated proxies apply method policies outermost first, and each retry opens a fresh transaction.

Security is off by default. Your team supplies the permission rules, credentials, and keys.

Retry only operations that are safe to repeat. A time limit can’t interrupt blocking PHP work.

See the implementation

Business coordination

When a saga step fails, the saga compensates the completed steps, and workflows pause for signals and timers.

With Laravel and Eloquent alone, your team builds
Step ordering, compensation, and timers, built into your own jobs and listeners.
larafly provides
Saga, try-confirm-cancel, and durable workflow engines, with a recovery service that finds stale executions.
How it works

Saga steps declare dependencies and compensations, and a policy decides how compensation runs. Signals resume a waiting workflow, and a scheduled tick fires its timers.

Execution state is in memory by default; a database store, or a persistent cache, survives restarts.

See the implementation

Operations and telemetry

Metrics and traces cover handlers, attributed methods, and event delivery.

With Laravel and Eloquent alone, your team builds
Logging, tracing, and metrics code in each handler, service method, and event delivery path.
larafly provides
Metrics and tracing adapters, guarded actuator endpoints, and scheduling locks.
How it works

The observability module turns on metrics for the bus and for methods marked #[Timed] or #[Observed]. Once tracing is enabled, TracerEdaTracing carries W3C trace context through events.

Health details are denied by default. Choose who may read them and which endpoints to expose.

See the implementation

Rollout and testing

Feature flags evaluate with context from your contributor beans, and tests exercise the real security policies.

With Laravel and Eloquent alone, your team builds
Flag tooling, evaluation context, and test helpers made to agree with your security setup.
larafly provides
OpenFeature flags with context contributors and metrics. FireflyTestCase signs principals in for tests.
How it works

FeatureFlagsAutoConfiguration builds evaluation context from contributor beans and adds a metrics hook. FireflyTestCase signs a principal in before filters, proxies, and bus authorizers run.

Feature flags stay off until you enable them. The built-in provider is the default.

See the implementation
Already in the native stack
Laravel provides dependency injection, validation, authorization, transactions, queues, and events. Pennant adds feature flags, and Eloquent persists your models.
Your team still owns
Business rules and compensating actions, validation and authorization policies, Eloquent models and migrations, event contracts, idempotent consumers, and worker operations.

Policy order

Your service method runs inside the policies it declares.

The generated proxy applies them outermost first, and your handler holds no wrapper code.

From a method call to its business operation

  1. firefly:cache compiles the method’s advice plan into a generated proxy.
  2. Metrics time the call.
  3. A feature flag decides whether the behavior is available.
  4. Method security checks the caller.
  5. Resilience policies retry or isolate the call.
  6. Each attempt enters its own transaction.
  7. Your handler runs the business operation.

Capabilities

Pick the modules your service needs.

larafly / Conceptual architectureYour components sit on Laravel: controllers at the edge, the optional outbox beside the repositories, and method security as a control.

Amber: Firefly modulesIvory lines: APIsAmber lines: events

Attribute-driven components

PHP attributes declare your components and their dependencies. ComponentScanner finds them in your PSR-4 namespaces, and a compiled manifest registers them in the container.

See the source

HTTP controllers on Laravel

At boot, larafly registers each attributed controller method as a Laravel route. Laravel’s router still matches the request and calls it.

See the source

Eloquent repositories

Repositories extend Eloquent with derived queries and explicit SQL on your Laravel database connection. Driver errors reach your code as translated persistence exceptions.

See the source

Commands and queries

The command bus sets a correlation id, then validates and authorizes each command before calling its handler. Metrics and tracing attach through the observability module.

See the source

A transactional outbox

Domain events enter the outbox in the aggregate’s transaction, on any Laravel database. Each server gets a safe claim strategy, and dead letters are replayable.

See the source

Method security

With security enabled, attributes such as #[PreAuthorize] guard service methods. Pre-rules run before the call, and post-rules check its result.

See the source

Code

The Lumen wallet reads a balance through GetBalanceHandler.

GetBalanceHandler gets its repository through the constructor and returns a wallet’s balance in minor units, or null when the wallet doesn’t exist.

Trace a wallet’s command and query

  1. Receive the request

    WalletController validates the request body and sends an OpenWallet command through the command bus.

  2. Apply the business operation

    OpenWalletHandler creates the wallet and saves it through the repository, inside its #[Transactional] boundary.

  3. Read the balance

    The query bus routes GetBalance to its handler. The REST tests open a wallet, deposit, and read the balance.

GetBalanceHandler.php
#[QueryHandler]
final class GetBalanceHandler
{
    public function __construct(private readonly WalletRepository $wallets) {}

    public function handle(GetBalance $query): ?int
    {
        $wallet = $this->wallets->findById($query->walletId);

        return $wallet?->balanceMoney()->minorUnits;
    }
}

A command handler with its transaction boundary

OpenWalletHandler saves the wallet inside its #[Transactional] boundary. With firefly.eda.provider=database, its tracked events reach the outbox before commit. The sample publishes to memory by default.

OpenWalletHandler.php
#[CommandHandler]
class OpenWalletHandler
{
    public function __construct(private readonly WalletRepository $wallets) {}

    #[Transactional]
    public function handle(OpenWallet $command): string
    {
        $id = 'wlt-'.bin2hex(random_bytes(8));
        $wallet = Wallet::open($id, $command->ownerId, $command->currency);
        $this->wallets->save($wallet);

        return $id;
    }
}

Releases and setup

Add larafly with Composer and follow the book.

Configure the namespaces larafly scans, and run firefly:cache before each deployment. The outbox needs firefly.eda.provider=database, its migration, and a firefly:eda:consume worker. The postgres provider adds LISTEN/NOTIFY wake-ups on PostgreSQL.

larafly v26.10.3 is on Packagist, and CI tests it on PHP 8.3, 8.4, and 8.5. Integration tests run on PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite.

Invoke transactional handlers through the managed container, which applies their generated proxies. Delivery is at least once, so consumers must tolerate redelivery.

Front cover of larafly by example

larafly by example

Business architecture and application policy on Laravel

The book builds the Lumen wallet service: CQRS, security, the outbox, orchestration, webhooks, and event sourcing.

Read the manuscript

October 2026 edition

Next step

Try larafly on the Lumen wallet sample.