Source: https://fireflyframework.org/frameworks/php/
Language: en

larafly, the PHP framework by Firefly

# 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.

[Read the documentation](https://fireflyframework.github.io/fireflyframework-php/) [View the source](https://github.com/fireflyframework/fireflyframework-php)

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

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.

[`firefly:cache` manifests and proxies](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/cli/src/Cache/ManifestCacheWriter.php#L42-L61)

[See the implementation](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/context/src/Boot/FireflyKernel.php#L53-L103)

### 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.

[Versioned appends that refuse a stale version](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/eventsourcing/src/Store/DatabaseEventStore.php#L81-L147) [Snapshot restore and replay](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/eventsourcing/src/Aggregate/EventSourcedRepository.php#L50-L67) [Fenced projection checkpoints](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/eventsourcing/src/Projection/DatabaseCheckpointStore.php#L63-L85) [Event sourcing module guide](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/docs/modules/eventsourcing.md)

[See the implementation](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/data/src/Repository/EloquentRepository.php#L117-L145)

### 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.

[No-op defaults the modules replace](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/cqrs/src/CqrsAutoConfiguration.php#L100-L146) [Query cache and its event invalidation](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/cqrs/src/CqrsAutoConfiguration.php#L120-L178)

[See the implementation](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/cqrs/src/Command/DefaultCommandBus.php#L45-L69)

### 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.

[Same-transaction outbox hook](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/eda-database/src/Outbox/OutboxPreCommitHook.php#L44-L61) [Webhook signature validators](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/webhooks/src/Signature/SignatureValidatorFactory.php#L11-L29) [HMAC-signed callback deliveries](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/callbacks/src/Delivery/CallbackSigner.php#L7-L34)

[See the implementation](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/data/src/Domain/DomainEventDispatcher.php#L29-L52)

### 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.

[Bus authorizers and the security-context auditor](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/security/src/SecurityAutoConfiguration.php#L217-L262) [JWKS from the authorization server](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/security-oauth2-server/src/OAuth2ServerAutoConfiguration.php#L99-L111) [A fresh invocation per retry](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/resilience/src/Method/ResilienceMethodInterceptor.php#L64-L113)

[See the implementation](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/cli/src/Cache/ManifestCacheWriter.php#L100-L114)

### 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.

[The tick that resumes due workflows](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/orchestration/src/Recovery/OrchestrationTickTask.php#L9-L24) [Memory, cache, and database execution stores](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/orchestration/src/OrchestrationAutoConfiguration.php#L107-L120) [Orchestration documentation](https://fireflyframework.github.io/fireflyframework-php/modules/orchestration/)

[See the implementation](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/orchestration/src/Saga/Attributes/SagaStep.php#L9-L41)

### 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.

[Actuator exposure and health details](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/actuator/src/ActuatorAutoConfiguration.php#L37-L63) [Database and MySQL scheduling locks](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/scheduling-database/src/SchedulingDatabaseAutoConfiguration.php#L15-L49)

[See the implementation](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/observability/src/ObservabilityAutoConfiguration.php#L172-L234)

### 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.

[Test principals across layers](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/testing/src/FireflyTestCase.php#L37-L52)

[See the implementation](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/feature-flags/src/FeatureFlagsAutoConfiguration.php#L84-L117)

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.

[Compiled policy order](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/cli/src/Cache/ManifestCacheWriter.php#L100-L114) [Retries re-enter the transaction](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/resilience/src/Method/ResilienceMethodInterceptor.php#L79-L89)

Capabilities

## Pick the modules your service needs.

larafly / Conceptual architecture

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

1. [01Attribute-driven components](https://fireflyframework.org/frameworks/php/#php-capability-0)
2. [02HTTP controllers on Laravel](https://fireflyframework.org/frameworks/php/#php-capability-1)
3. [03Eloquent repositories](https://fireflyframework.org/frameworks/php/#php-capability-2)
4. [04Commands and queries](https://fireflyframework.org/frameworks/php/#php-capability-3)
5. [05A transactional outbox](https://fireflyframework.org/frameworks/php/#php-capability-4)
6. [06Method security](https://fireflyframework.org/frameworks/php/#php-capability-5)

Amber: Firefly modules · Ivory lines: APIs · Amber 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](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/container/src/Scanner/ComponentScanner.php#L34-L47)

### 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](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/web/src/Dispatch/RouteWiringPass.php#L32-L44)

### 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](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/data/src/Repository/EloquentRepository.php#L125-L145)

### 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](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/cqrs/src/Command/DefaultCommandBus.php#L45-L69)

### 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](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/eda-database/src/Outbox/Claim/OutboxClaimStrategies.php#L34-L51)

### 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](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/security/src/Access/Method/MethodSecurityInterceptor.php#L28-L41)

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

```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;
    }
}
```

[View the full file](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/samples/lumen/src/Application/Query/GetBalanceHandler.php#L14-L25)

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

```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;
    }
}
```

[View the full file](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/samples/lumen/src/Application/Command/OpenWalletHandler.php#L24-L38)

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.

[Read the documentation](https://fireflyframework.github.io/fireflyframework-php/) [View the v26.10.3 release](https://github.com/fireflyframework/fireflyframework-php/releases/tag/v26.10.3)

### For Laravel 13 applications

Require `fireflyframework/larafly` with Composer.

[View the Packagist package](https://packagist.org/packages/fireflyframework/larafly)

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](https://github.com/fireflyframework/fireflyframework-php/tree/v26.10.3/book/src)
- [English PDF](https://github.com/fireflyframework/fireflyframework-php/releases/download/v26.10.3/larafly-by-example.pdf)
- [English EPUB](https://github.com/fireflyframework/fireflyframework-php/releases/download/v26.10.3/larafly-by-example.epub)
- [Spanish PDF](https://github.com/fireflyframework/fireflyframework-php/releases/download/v26.10.3/larafly-by-example-es.pdf)
- [Spanish EPUB](https://github.com/fireflyframework/fireflyframework-php/releases/download/v26.10.3/larafly-by-example-es.epub)

October 2026 edition

Related

## Two module guides beside the wallet sample.

### Lumen wallet service

The book’s sample application, with its HTTP, domain, and persistence tests.

[View the source](https://github.com/fireflyframework/fireflyframework-php/tree/a18a968d7b29f59e80c724b103160e121fda24ee/samples/lumen)

### Domain modeling

The plain PHP base classes for entities, value objects, aggregates, and domain events.

[Read the guide](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/docs/modules/domain.md)

### Events and broker adapters

The RabbitMQ, PostgreSQL, and Kafka adapters, each switched on through `firefly.eda.provider`.

[Read the guide](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/docs/modules/eda-brokers.md)

Sources behind this page

- [PHP and Laravel compatibility](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/composer.json#L2-L28)
- [Compiled container integration](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/container/tests/IntegrationTest.php#L17-L47)
- [Wallet REST tests](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/samples/lumen/tests/Web/WalletRestTest.php#L18-L32)
- [Outbox transaction test](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/eda-database/tests/CapstoneDatabaseOutboxTest.php#L46-L63)
- [Method-security tests](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/security/tests/Access/Method/MethodSecurityInterceptorTest.php#L70-L111)
- [CI on PHP 8.3–8.5 and five databases](https://github.com/fireflyframework/fireflyframework-php/actions/runs/38487942324)
- [Security package](https://github.com/fireflyframework/fireflyframework-php/tree/a18a968d7b29f59e80c724b103160e121fda24ee/packages/security)
- [Driver error translation](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/data/src/Exception/DriverErrorTable.php#L66-L79)
- [Database outbox wiring](https://github.com/fireflyframework/fireflyframework-php/blob/b35abf3e274b38e7911bc82f4f2fbe56b863e45b/packages/eda-database/src/DatabaseOutboxAutoConfiguration.php#L28-L111)
- [Published Composer package metadata](https://repo.packagist.org/p2/fireflyframework/larafly.json)
- [Native Laravel transactions](https://laravel.com/framework/docs/13.x/database#database-transactions)
- [EDA provider default: memory](https://github.com/fireflyframework/fireflyframework-php/blob/a18a968d7b29f59e80c724b103160e121fda24ee/packages/eda/src/EdaAutoConfiguration.php#L34-L46)

Next step

## Try larafly on the Lumen wallet sample.

[Read the documentation](https://fireflyframework.github.io/fireflyframework-php/) [Open the sample](https://github.com/fireflyframework/fireflyframework-php/tree/a18a968d7b29f59e80c724b103160e121fda24ee/samples/lumen)
