Skip to content

larafly — Firefly Framework for PHP

larafly

LaraFly is the PHP edition of the Firefly Framework — Spring Boot's cohesion, native to Laravel 13. It layers dependency injection with stereotypes, conditional auto-configuration, hexagonal ports & adapters, CQRS, event-driven architecture, first-party security including both halves of OAuth2, and a project CLI directly onto Laravel's own runtime. Nothing is forked or wrapped: a LaraFly app is, in every respect a Laravel developer would recognize, still a Laravel app — it just boots like a Spring Boot one.

The whole framework ships as one Composer library, fireflyframework/larafly, containing all 30 components, wired together by a single zero-reflection boot pipeline: a component scan compiles to a cached manifest once, and every request after that runs against plain PHP arrays — no runtime reflection on the hot path.

Start here

Install Installation Requirements, the bundled firefly new installer, and using the local template from a framework source checkout.

First run Getting Started Boot the skeleton, read the #[Controller]/#[RestController]/#[Service] slice it generated, and — if you are starting from an app you already have — pull the whole family in with one composer require.

Build something Tutorial · Tutorial (Español) A hand-built, 12-step walkthrough from firefly new to a #[Repository]/#[Valid]/CQRS/#[EventListener] feature slice, with a curl'd expected output at every step.

Understand it Architecture The hexagonal design, the phased boot pipeline, and where the compiled manifests come from.

Coming from Laravel Laravel Comparison Concept mapping for developers who already know Laravel: what stays, what is added, and what a stereotype replaces.

Quickstart

composer global require fireflyframework/larafly
firefly new my-app
cd my-app
php artisan firefly:cache   # compile the zero-reflection boot manifests
php artisan serve

See Installation for requirements and manual setup, and Getting Started for a walkthrough of the generated app.

Why LaraFly?

  • Attribute-driven DI & auto-configuration — #[Service], #[Repository], #[Configuration] classes are discovered by a compiled scan; enable a capability and its defaults wire themselves up, your own beans always win.
  • Hexagonal by construction — every subsystem exposes a port and one or more adapters, with architectural direction enforced by Deptrac, not convention alone.
  • Declarative transactions & CQRS — #[Transactional] demarcates boundaries at scan time; one generated proxy per bean runs the whole advice chain, security before transaction (Advice order 100 against 1000), so a refusal is thrown before a transaction is ever opened. A CommandBus/QueryBus mediator dispatches commands and queries, with domain events bridged onto the event-transport bus after commit.
  • Event-driven, with real brokers — an in-memory default plus RabbitMQ, Postgres LISTEN/NOTIFY, and Kafka adapters behind one EventPublisher port.
  • Secure by default — a session-persisted SecurityContext, form login on the framework's own page, HTTP Basic, remember-me, logout, deny-by-default HttpSecurity URL rules, and method security (#[PreAuthorize], #[PostAuthorize], #[PreFilter], #[PostFilter]) enforced on any stereotyped bean through that same shared interceptor chain.
  • Both halves of OAuth2 — sign in with an external provider (OIDC login with provider presets, discovery, PKCE, id-token validation, RP-initiated logout, client credentials and Http::oauth2Client()), or be the provider (an authorization server with registered clients, /oauth2/authorize with PKCE and a consent page, /oauth2/token with three grants, introspection, revocation, /userinfo, JWKS and both .well-known documents).
  • Traced and logged like a service, not a script — a Tracer/Span port with an OpenTelemetry adapter, a W3C traceparent continued at the server filter and carried on through the Http client, both CQRS buses and the in-memory and queue event buses, and structured logging in json, ecs or logstash carrying the same ids.
  • Production-ready out of the box — an Actuator surface (health/info/beans) and a Prometheus/Micrometer-style metrics core, both secured by the same config as everything else, plus a server-rendered admin dashboard over them with a drawn bean graph, and an opt-in, off-by-default data browser over your own repositories, with filtering, full CRUD, relations you can walk and a drawn entity map.
  • An API document that cannot drift — firefly/openapi generates OpenAPI 3.1 from the same compiled manifests the dispatcher and the validator read, and serves the official Swagger UI from your own origin — no annotation dialect, no npm, no CDN.
  • A first-party test kit — a boot harness, recording doubles for every port, and #[WebSlice]/#[DataSlice] test slices, dogfooded across the framework's own suites — which include a Pest 4 + Playwright suite driving real Chromium over the skeleton's own pages; that one is the framework's, and Contributing has what it covers and how to run it.

The modules

Every capability above ships in the root library; configuration selects optional features. The module index lays all 33 guides out by concern, with a line on each saying what it is for, and the same grouping is the site's Modules tab.

Group Guides
Foundation Error Handling · Dependency Injection · Configuration · Application Context · Auto-Configuration · Validation
Web & API Web Layer · Web Filters · OpenAPI
Resilience & Scheduling Resilience · Scheduling
Data & Domain Domain (DDD) · Data & Repositories · Relational Data · Transactions
Eventing & Messaging EDA · EDA Brokers · Messaging
CQRS Command/Query
Security Security · OAuth2 Client · OAuth2 Authorization Server
Operations Actuator · Observability · Tracing · Logging · Admin Dashboard · Bean Graph · Data Browser · Feature Flags
Testing Testing · Integration Testing
Tooling Installer

See it running

Want to see it all working together? The Lumen sample is a runnable digital-wallet & ledger vertical slice exercising #[Transactional], CQRS, domain events over EDA, method security, and a REST layer with RFC-7807 problem-details. The guided, book-style larafly by example book — 16 chapters plus appendices, bilingual (English + Spanish), building this exact sample — is available as PDF and EPUB downloads in English and Spanish.

Apache-2.0 © Firefly Software Solutions Inc.