LaraFly Documentation
Everything you need to build production-grade applications with LaraFly — Spring Boot's cohesion, native to Laravel 13.
| Guide |
Description |
| Introduction |
What LaraFly is, the pitch, and a map of the docs |
| Installation |
Requirements, composer create-project firefly/skeleton, and manual install |
| Getting Started |
Boot the firefly/skeleton template, write your first #[RestController]/#[Service], run firefly:cache |
| Architecture |
The hexagonal design, the boot pipeline, and how the Deptrac layers fit together |
| Tutorial |
A hand-built, 12-step walkthrough — from composer create-project to a #[Repository]/#[Valid]/CQRS/#[EventListener] feature slice |
| Lumen Sample |
A runnable digital-wallet & ledger sample exercising #[Transactional], CQRS, domain events over EDA, method security, and a REST layer with RFC-7807 problem-details |
Every module guide lives under modules/, in the ten groups mkdocs.yml's navigation and the
site's own Modules landing page use. All 32 are listed here, and neither the list nor the
number is maintained on trust: tests/ModuleDocumentationTest.php fails the build if a guide is missing
from the navigation, from the table below, from the root README.md's table, from docs/index.md or from
the landing page, and tests/SiteNavigationTest.php reads that number off docs/modules/*.md itself, so a
thirty-third guide turns this page red rather than quietly making it wrong.
| Guide |
Description |
| Error Handling |
firefly/kernel's product-agnostic exception hierarchy and HTTP status mapping |
| Dependency Injection |
firefly/container — attributes, component scan → compiled manifest, container resolution |
| Configuration |
firefly/config — profiles, typed config accessor, #[ConfigProperties], #[Value] |
| Application Context |
firefly/context — the FireflyKernel boot pipeline, conditions, lifecycle callbacks |
| Auto-Configuration & Starters |
firefly/autoconfigure — install a package, get sensible defaults, your own beans win |
| Validation |
firefly/validation — constraint attributes behind #[Valid], and the Spring-shaped problem document a failure renders |
| Guide |
Description |
| Web Layer |
firefly/web — #[RestController]/#[Controller] routing, parameter binding, JSON + HTML negotiation, RFC-7807 error rendering |
| Web Filters |
An ordered WebFilter chain bridged onto Laravel's own middleware pipeline |
| OpenAPI |
firefly/openapi — an OpenAPI 3.1 document generated from the compiled manifests, firefly:openapi, and the official Swagger UI served from your own origin |
| Guide |
Description |
| Resilience |
firefly/resilience — Retry, CircuitBreaker, RateLimiter, Bulkhead, TimeLimiter, Fallback |
| Scheduling |
firefly/scheduling — #[Scheduled] on Laravel's own scheduler, with distributed-lock guard |
| Guide |
Description |
| Domain (DDD) |
firefly/domain — Entity, ValueObject, AggregateRoot, DomainEvent; zero reflection |
| Data & Repositories |
firefly/data — CRUD/paging ports, derived queries, #[Query], query by example, Specifications, the DataAccessException family |
| Relational Data |
EloquentRepository — the Eloquent-backed base every repository extends |
| Transactions |
#[Transactional] — declarative transaction demarcation over manual DB::beginTransaction() |
| Guide |
Description |
| Event-Driven Architecture |
firefly/eda — broker-backed EventPublisher, envelopes, retry/DLQ, in-memory + queue adapters |
| EDA Brokers |
Real broker adapters behind the EventPublisher port — RabbitMQ, Postgres LISTEN/NOTIFY, Kafka |
| Messaging |
firefly/messaging — the lower-level raw-bytes MessageBrokerPort, #[MessageListener] |
| Guide |
Description |
| CQRS (Command/Query) |
firefly/cqrs — the CommandBus/QueryBus mediator and the domain→integration-event bridge |
| Guide |
Description |
| Security |
firefly/security — Spring-Security-6-shaped principal model, session-persisted context, form login, HTTP Basic, JWT, deny-by-default authZ and method security |
| OAuth2 Client |
firefly/security-oauth2-client — Spring's oauth2Login()/oauth2Client(): provider registrations, OIDC login with PKCE, and an authorized-client manager |
| OAuth2 Authorization Server |
firefly/security-oauth2-server — an OAuth 2.1 / OIDC provider inside your application: codes, tokens, JWKS, introspection, revocation, consent |
| Guide |
Description |
| Actuator |
firefly/actuator — health/info/beans endpoints, the Spring-Boot-Actuator analogue |
| Observability |
firefly/observability — the MeterRegistry, Prometheus/Micrometer-JSON exposition, CQRS metrics |
| Tracing |
The OpenTelemetry-shaped Tracer/Span port, W3C traceparent propagation across HTTP, CQRS and EDA |
| Logging |
Correlation, request, trace and span ids on every record, and JSON/ECS/Logstash structured output |
| Admin Dashboard |
firefly/admin — the browser dashboard over the actuator; reads its endpoints in-process, so its own URL is the security boundary |
| Bean Graph |
The dashboard's drawn dependency graph — components, #[Bean] products and #[ConfigProperties] DTOs as nodes, interface-resolved edges, longest-path layering, cycle reporting |
| Data Browser |
A Django-style database browser over CrudRepository beans — off by default, writes behind a second gate, with filtering, paging, relations you can walk, and an entity map |
| Guide |
Description |
| Testing |
firefly/testing — the boot harness, recording doubles, web/data test-slice builders |
| Integration Testing |
Opt-in tests against real backends (Postgres, Kafka), excluded from the default gate |
| Guide |
Description |
| Installer |
firefly/installer — the firefly new global scaffolding tool, zero runtime dependencies |
| Document |
Description |
| Modules |
The grouped index of all 32 module guides, and how a package wires itself |
| CLI Reference |
Every firefly:* command and make:firefly-* generator, including the four contributed by capability packages |
| Laravel Comparison |
Side-by-side concept mapping for developers coming from plain Laravel |
| Versioning |
CalVer (YY.MM.Patch), no version field, how Packagist derives releases from tags |
| Contributing |
Monorepo layout, local setup, the gate, the documentation guard, conventions |
| Publishing |
The release/split runbook — one CalVer tag, one mirror per shippable unit |
- New to LaraFly? Start with Installation, then Getting Started.
- Coming from plain Laravel? Read the Laravel Comparison.
- Want to see it running end-to-end? Explore the Lumen Sample — a full digital-wallet
vertical slice.
- Building a web service? See the Web Layer Guide and Web Filters.
- Understanding the data layer? Start with Data & Repositories, then
Relational Data and Transactions.
- Need messaging or events? See Event-Driven Architecture, EDA Brokers,
and Messaging.
- Writing commands/queries? See CQRS.
- Securing an app? See Security, then OAuth2 Client
to sign users in with a provider and OAuth2 Authorization Server to be
one yourself.
- Shipping to production? See Actuator, Observability,
Tracing, Logging and Resilience — then
Admin Dashboard for the browser view over all of it, and read its
access model before enabling it outside
app.debug.
- Publishing an API? See OpenAPI — the spec is generated from the same manifests the
dispatcher and validator use, so it cannot drift.
- Writing tests? See Testing and Integration Testing.
- Releasing a version? See Versioning and Publishing, and check the
CHANGELOG.md at the repo root.
- Want to contribute? See Contributing.
The guided, book-style LaraFly by Example — bilingual (English + Spanish), rendered
to PDF + EPUB, its chapter list held in book/book.yaml and book/book.es.yaml — is available now, alongside
the step-by-step Tutorial.
Apache-2.0 © Firefly Software Solutions Inc.
