ancongui · Oct 7, 2026 · Oct 2, 2026 · Oct 2, 2026 · Oct 2, 2026 · Oct 2, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,29 @@ All notable changes to LaraFly are documented here. This project uses CalVer (`Y
 
 ## [Unreleased]
 
+## [26.10.1] - 2026-10-06
+
+### Added
+
+- **Feature flags (`firefly/feature-flags`):** in-process flagd evaluation on OpenFeature, with shared
+  cross-framework validation, evaluation and percentage-bucket conformance vectors. Definitions come from
+  config (including shorthand), a watched JSON/YAML file, an HTTP sync endpoint or a writable database store
+  with audit history and optimistic concurrency; PHP-FPM workers share refresh state through the cache.
+- **Feature flag gates:** `#[FeatureFlag]` on beans and controllers, the `feature-flag` route middleware,
+  `@featureflag` / `@featurevariant` in Blade, and the `FeatureFlags` facade. Missing or erroring flags use
+  the caller's default, which is closed unless explicitly enabled; source refresh failures retain the last
+  good definitions. Bean gates support fallbacks and compile through `firefly:cache`.
+- **Feature flag management:** the `flags` actuator endpoint, admin **Feature flags** page,
+  `php artisan firefly:flags`, `featureflags` health component, `feature_flag_evaluations_total`, change and
+  optional exposure events, bearer-token flagd sync server, and `withFeatureFlags()` test overrides.
+  The guide and both book editions include a tested Lumen rollout example.
+- **Actuator:** `EndpointRequest::$rawBody` carries the original JSON request text beside its parsed body.
+
+### Changed
+
+- **Runtime dependencies:** added `open-feature/sdk: ^2.3` and moved `symfony/yaml: ^7.4|^8.0`
+  from development to runtime requirements for JSON/YAML feature-flag sources.
+
 ### Fixed
 
 - **Release workflow:** the publication job waits for the tag on Composer's metadata endpoint

diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@
   <a href="docs/installation.md#requirements"><img src="https://img.shields.io/badge/php-8.3%2B-blue?logo=php&logoColor=white" alt="PHP 8.3+"></a>
   <a href="docs/laravel-comparison.md"><img src="https://img.shields.io/badge/Laravel-13-FF2D20?logo=laravel&logoColor=white" alt="Laravel 13"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License: Apache 2.0"></a>
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-26.09.11-brightgreen" alt="Version: 26.09.11"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-26.10.1-brightgreen" alt="Version: 26.10.1"></a>
   <a href="docs/contributing.md#conventions"><img src="https://img.shields.io/badge/PHPStan-max-8A2BE2" alt="PHPStan: max"></a>
   <a href="pint.json"><img src="https://img.shields.io/badge/code%20style-Pint-F55247" alt="Code Style: Pint"></a>
 </p>
@@ -71,10 +71,11 @@ event-driven, actuator-observed microservice, chapter by chapter — every listi
 **[Download the book in English or Spanish, as PDF or EPUB](https://fireflyframework.github.io/fireflyframework-php/book/).**
 The published editions include the single-package installation and bundled installer.
 
-The book is **structurally complete and bilingual (English + Spanish)**: a quick start, **fifteen chapters**
+The book is **structurally complete and bilingual (English + Spanish)**: a quick start, **sixteen chapters**
 across four parts — Foundations (DI, config, HTTP), Modelling & Persisting the Domain (repositories, DDD),
 Coordinating & Securing the App (CQRS, EDA + transactional outbox, `#[Transactional]`, security, OAuth2 and
-OpenID Connect), and Observability, Testing & Delivery (actuator, testing, the CLI + zero-reflection cache)
+OpenID Connect), and Observability, Testing & Delivery (actuator, testing, the CLI + zero-reflection cache,
+feature flags)
 — plus a Laravel→LaraFly cheat-sheet and a glossary. The two editions are line-for-line the same book: every
 chapter file has the same sections, in the same order, at the same line numbers, and every `php` listing and
 every `source:`-marked excerpt in the Spanish edition is the English one character for character — the only
@@ -157,7 +158,7 @@ LaraFly is not a fork of Laravel and does not hide it — every package layers c
 `Illuminate\Container`, Eloquent, the HTTP kernel, and the queue/cache/scheduler, so everything you already
 know about Laravel keeps working underneath.
 
-Three capabilities in that list are recent enough — and far enough from what teams assume a PHP framework
+Four capabilities in that list are recent enough — and far enough from what teams assume a PHP framework
 will have — that they are worth naming outright:
 
 - **Both halves of OAuth2, as two packages you install.**
@@ -188,6 +189,10 @@ will have — that they are worth naming outright:
   becomes a `DuplicateKeyException` carrying a 409 and a fixed sentence, with the driver's message — which
   has the statement and its bindings interpolated into it — left on `previous`, for the log and never for
   the wire.
+- **Feature flags shared with PyFly.** [`firefly/feature-flags`](docs/modules/feature-flags.md) evaluates
+  [flagd](https://flagd.dev) definitions in-process on OpenFeature with the same semantics and percentage buckets
+  as PyFly. Gate a bean method or route with `#[FeatureFlag]` and a view with `@featureflag`; change flags at runtime
+  from the admin dashboard, `/actuator/flags` or `php artisan firefly:flags`, with an audit trail.
 
 ### Who is LaraFly for?
 
@@ -1061,7 +1066,7 @@ Full flag reference and generated-file contents: [CLI](docs/cli.md).
 
 One published library, `fireflyframework/larafly`, contains the components under `packages/*` and the bundled
 application skeleton. Its `replace` entries satisfy component requirements at the framework's version;
-component names remain useful module boundaries, with their own test suites. The 32
+component names remain useful module boundaries, with their own test suites. The 33
 [module guides](docs/modules/) below group them by concern:
 
 | Group | Module | Package(s) |
@@ -1095,6 +1100,7 @@ component names remain useful module boundaries, with their own test suites. The
 | Operations | [Admin Dashboard](docs/modules/admin.md) — the browser dashboard over the actuator, read in-process | `firefly/admin` |
 | Operations | [Bean Graph](docs/modules/bean-graph.md) — the dashboard's drawn dependency graph, with cycle reporting | `firefly/admin` |
 | Operations | [Data Browser](docs/modules/data-browser.md) — the dashboard's database browser over `CrudRepository` beans, off by default | `firefly/admin` |
+| Operations | [Feature Flags](docs/modules/feature-flags.md) — flagd flags on OpenFeature, gates, layered sources, a writable store and audit trail | `firefly/feature-flags` |
 | Testing | [Testing](docs/modules/testing.md) — `FireflyTestCase`, recording doubles, Pest expectations | `firefly/testing` |
 | Testing | [Integration Testing](docs/modules/integration-testing.md) — `@group integration`, testcontainers | `firefly/testing` |
 | Tooling | [Installer](docs/modules/installer.md) — the global `firefly new` scaffolding tool | `firefly/installer` |
@@ -1116,7 +1122,7 @@ Start at the **[documentation table of contents](docs/README.md)** — it groups
 - [Laravel ↔ Spring Boot Comparison](docs/laravel-comparison.md) — concept-by-concept mapping for both audiences.
 - [Versioning](docs/versioning.md) · [Contributing](docs/contributing.md) · [Publishing](docs/publishing.md).
 - Every [module guide](#modules) above.
-- [*LaraFly by Example*](book/README.md) — the complete bilingual book (15 chapters + appendices, PDF + EPUB).
+- [*LaraFly by Example*](book/README.md) — the complete bilingual book (16 chapters + appendices, PDF + EPUB).
 - [`samples/lumen/`](samples/lumen/) — the wallet-and-ledger sample this README's showcases are drawn from;
   run its own test suite with `vendor/bin/pest samples/lumen/tests`.
 
@@ -1138,9 +1144,10 @@ still ahead, accurately:
   round-trip test (RabbitMQ, Postgres, Kafka) gated behind Docker + a live connection string — these run
   on demand, not in the default `vendor/bin/pest`/CI pass; wiring a scheduled/opt-in CI lane for them is
   still open.
-- **More actuator endpoints.** Fifteen ship today — `/health`, `/info`, `/env`, `/beans`, `/conditions`,
+- **More actuator endpoints.** Sixteen ship today — `/health`, `/info`, `/env`, `/beans`, `/conditions`,
   `/mappings`, `/loggers`, `/scheduledtasks`, `/caches`, `/configprops`, `/metrics`, `/prometheus`,
-  `/process`, `/httpexchanges`, and `/oauth2clients` when the authorization server is installed — and
+  `/process`, `/httpexchanges`, `/oauth2clients` when the authorization server is installed, and `/flags`
+  when feature flags are enabled — and
   `firefly.management.server.port` moves the whole surface onto a second listener, with `ManagementPortGuard`
   making the actuator refuse the application port and `php artisan firefly:management:serve` running that
   second listener in development. Spring Boot's `/refresh`, `/threaddump` and `/shutdown` are still not
@@ -1155,7 +1162,7 @@ still ahead, accurately:
   today via a plain `#[EventListener]`; a dedicated `firefly/eventsourcing`-style package for event
   sourcing/snapshots/projections is future work, as it is in PyFly.
 - **Documentation.** The end-to-end [tutorial](docs/tutorial.md) (EN + ES), the *LaraFly by Example*
-  [book](book/README.md) (15 chapters + appendices, EN + ES, PDF + EPUB), and a
+  [book](book/README.md) (16 chapters + appendices, EN + ES, PDF + EPUB), and a
   [docs table of contents](docs/README.md) all shipped with the documentation-parity milestone.
   Deeper guides (more recipes, more diagrams) continue to grow from here.
 

diff --git a/book/README.md b/book/README.md
@@ -111,7 +111,7 @@ book/
   src/                         # EN manuscript (Markdown)
     00-front/                   # title/copyright/dedication/preface/conventions
     00-quickstart.md             # "Build Lumen step by step" quick start
-    01..13-*.md                  # the fifteen chapters, 4A and 10A included (Parts I-IV)
+    01..13a-*.md                 # the sixteen chapters, 4A, 10A and 13A included (Parts I-IV)
     90-appendix-a-laravel.md      # Laravel -> LaraFly cheat-sheet
     94-glossary.md                # glossary
   src-es/                        # ES manuscript, same structure/filenames
@@ -137,7 +137,7 @@ book/
 ## Manuscript status
 
 The manuscript is **structurally complete** in both languages: a five-file front
-matter, a "Build Lumen step by step" quick start, fifteen chapters across four
+matter, a "Build Lumen step by step" quick start, sixteen chapters across four
 parts —
 
 - **Part I — Foundations**: Why LaraFly, Dependency Injection & Auto-Configuration,
@@ -148,7 +148,7 @@ parts —
   Architecture & the Transactional Outbox, Transactions & the `#[Transactional]`
   proxy, Security, OAuth2 and OpenID Connect
 - **Part IV — Observability, Testing & Delivery**: Observability/Actuator,
-  Testing, the CLI & the Zero-Reflection Cache
+  Testing, the CLI & the Zero-Reflection Cache, Feature Flags
 
 — plus **Appendix A** (Laravel → LaraFly cheat-sheet) and a **Glossary**. Every
 chapter walks the real `samples/lumen` project. Every fenced ` ```php ` listing

diff --git a/book/book.es.yaml b/book/book.es.yaml
@@ -76,6 +76,7 @@ parts:
       - {id: ch11, file: 11-observability-actuator.md, num: 11, title: "Observabilidad: Salud, Métricas y el Actuator"}
       - {id: ch12, file: 12-testing.md, num: 12, title: "Probar Aplicaciones LaraFly"}
       - {id: ch13, file: 13-cli-cache.md, num: 13, title: "La CLI y la Caché Sin Reflexión"}
+      - {id: ch13a, file: 13a-feature-flags.md, num: "13A", title: "Feature Flags entre LaraFly y PyFly"}
   - title: "Apéndices"
     chapters:
       - {id: appa, file: 90-appendix-a-laravel.md, num: "A", title: "Hoja de Referencia Laravel → LaraFly"}

diff --git a/book/book.yaml b/book/book.yaml
@@ -74,6 +74,7 @@ parts:
       - {id: ch11, file: 11-observability-actuator.md, num: 11, title: "Observability: Health, Metrics, and the Actuator"}
       - {id: ch12, file: 12-testing.md, num: 12, title: "Testing LaraFly Applications"}
       - {id: ch13, file: 13-cli-cache.md, num: 13, title: "The CLI and the Zero-Reflection Cache"}
+      - {id: ch13a, file: 13a-feature-flags.md, num: "13A", title: "Feature Flags Across LaraFly and PyFly"}
   - title: "Appendices"
     chapters:
       - {id: appa, file: 90-appendix-a-laravel.md, num: "A", title: "Laravel → LaraFly Cheat-Sheet"}

diff --git a/book/build/build.py b/book/build/build.py
@@ -51,8 +51,8 @@ def _items_from_manifest(cfg: dict, man: Path, *, contents_label: str) -> list[d
     # 1) front matter
     for fm in cfg.get("front", []):
         p = man / fm["file"]
-        if not p.exists():
-            continue
+        if not p.is_file():
+            raise FileNotFoundError(f"Configured manuscript file is missing: {p}")
         items.append({
             "kind": "front",
             "id": fm["id"],
@@ -66,7 +66,11 @@ def _items_from_manifest(cfg: dict, man: Path, *, contents_label: str) -> list[d
     for part in cfg.get("parts", []):
         ptitle_full = part["title"]
         eyebrow, ptitle = _split_part(ptitle_full)
-        chapters = [ch for ch in part["chapters"] if (man / ch["file"]).exists()]
+        chapters = part["chapters"]
+        for ch in chapters:
+            p = man / ch["file"]
+            if not p.is_file():
+                raise FileNotFoundError(f"Configured manuscript file is missing: {p}")
         if not chapters:
             continue
         # stable divider id from the eyebrow, e.g. "Part I" -> "part-i"

diff --git a/book/src-es/00-front/00-preface.md b/book/src-es/00-front/00-preface.md
@@ -18,6 +18,8 @@ Cada capítulo hace avanzar **Lumen**, un servicio de monedero digital y libro m
 
 El recorrido empieza con suavidad. El **Inicio rápido** te lleva desde el instalador incluido `firefly new` hasta un endpoint en ejecución y consultable con curl, previendo en miniatura los estereotipos, el contenedor y la ruta de arranque compilada antes de que ningún capítulo te pida razonar sobre ellos. El **Capítulo 1** da un paso atrás y argumenta el enfoque completo — qué problema resuelve LaraFly y sobre qué pilares se sostiene. El **Capítulo 2** abre la sala de máquinas: el contenedor de inyección de dependencias, los atributos de estereotipo y el escaneo de componentes que compila tus clases anotadas en un manifiesto de arranque en caché, sin reflexión. Las partes posteriores de este libro — que llegarán en los capítulos siguientes — construyen hacia afuera desde esa base hacia la configuración, HTTP, la persistencia, el modelado de dominio, CQRS, la arquitectura orientada a eventos, la seguridad y la observabilidad, siempre a través de la misma base de código de `Lumen`, siempre con código que puedes ejecutar.
 
+El Capítulo 13A cierra el recorrido de producción con feature flags: Lumen mantiene apagada una vista de la wallet, selecciona una cohorte compartida y prueba la ruta y el ciclo del override contra el framework real.
+
 Cuando hayas terminado de trabajar todo el libro, tendrás un modelo mental de cada capa de un servicio LaraFly de producción, y una aplicación real y probada que lo demuestre.
 
 ### Cómo usar este libro

diff --git a/book/src-es/03-configuration.md b/book/src-es/03-configuration.md
@@ -373,6 +373,8 @@ Todo lo que ha mostrado este capítulo lee, en algún punto, a través de `env()
 
 ---
 
+El Capítulo 13A aplica estas reglas de configuración a `firefly.feature-flags.enabled`, los documentos de banderas por capas y los tokens de sincronización; deja las banderas en `config/firefly.php` y los secretos en el entorno.
+
 ## Lo que aprendiste {.recap}
 
 | Concepto | Qué hace |

diff --git a/book/src-es/04-first-http-api.md b/book/src-es/04-first-http-api.md
@@ -621,6 +621,8 @@ En el arranque, `RouteWiringPass` registra una **ruta nativa de Laravel** por ca
 
 ---
 
+El Capítulo 13A añade `#[FeatureFlag]` a una acción de controlador: su middleware rechaza la ruta apagada antes de vincular el cuerpo y no revela la clave en la respuesta de problema.
+
 ## Lo que construiste {.recap}
 
 La Parte I está completa. Lumen ahora **arranca** (Capítulo 1), está **conectado** (la inyección por constructor del Capítulo 2 sin código de cableado), está **configurado** (los ajustes tipados y conscientes de perfil del Capítulo 3), y **sirve** — una API REST validada en `/api/v1/wallets` con:

diff --git a/book/src-es/09-transactions.md b/book/src-es/09-transactions.md
@@ -556,6 +556,8 @@ La segunda prueba es la que importa. `Wallet::withdraw()` sobre el origen corri
 
 ---
 
+El Capítulo 13A utiliza la misma frontera transaccional para las escrituras versionadas del almacén de banderas y sus filas de auditoría, incluidas las reglas de commit y rollback del llamador.
+
 ## Lo que aprendiste {.recap}
 
 | Concepto | Qué hace |

diff --git a/book/src-es/11-observability-actuator.md b/book/src-es/11-observability-actuator.md
@@ -1102,6 +1102,8 @@ Es un *interruptor de funcionalidad*, no un endpoint de configuración remota: l
 
 ---
 
+El Capítulo 13A amplía esta superficie con el endpoint `flags`, la salud de las fuentes, las métricas de evaluación y los eventos de exposición opcionales; las vistas previas de gestión no emiten métricas ni exposiciones.
+
 ## Lo que aprendiste {.recap}
 
 | Concepto | Qué hace |

diff --git a/book/src-es/12-testing.md b/book/src-es/12-testing.md
@@ -531,6 +531,8 @@ abstract class LumenTestCase extends FireflyDatabaseTestCase
             CqrsWiringProvider::class,
             EdaServiceProvider::class,
             EdaWiringProvider::class,
+            FeatureFlagsServiceProvider::class,
+            FeatureFlagsWiringProvider::class,
             SecurityServiceProvider::class,
             SecurityWiringProvider::class,
             ActuatorServiceProvider::class,
@@ -756,6 +758,8 @@ Lee dos veces la última frase, porque es la razón por la que este método exis
 
 ---
 
+El Capítulo 13A prueba el `WalletRollout` incluido en Lumen con `withFeatureFlags()`, vectores de selección compartidos y una ruta protegida; después limpia los overrides para comprobar que vuelve el comportamiento anterior.
+
 ## Lo que aprendiste {.recap}
 
 | Concepto | Qué hace |

diff --git a/book/src-es/13-cli-cache.md b/book/src-es/13-cli-cache.md
@@ -185,6 +185,7 @@ final class ManifestCacheWriter
     {
         return new ProxyPlanner([
             new ObservabilityAdviceSource,
+            new FeatureFlagAdviceSource,
             new MethodSecurityAdviceSource,
             new ResilienceAdviceSource,
             new TransactionalAdviceSource,
@@ -514,6 +515,8 @@ Cada aplicación que `firefly new` andamia es por tanto, desde el primerísimo `
 
 ---
 
+El Capítulo 13A presenta `firefly:flags` para inspeccionar y cambiar banderas en ejecución; sus puertas de método también entran en el plan de proxy compilado en vez de reflejarse en cada petición.
+
 ## Lo que aprendiste {.recap}
 
 | Concepto | Qué hace |
-Original file line number
+Diff line change
@@ Expand Up @@
     ---
+    El Capítulo 13A aplica estas reglas de configuración a `firefly.feature-flags.enabled`, los documentos de banderas por capas y los tokens de sincronización; deja las banderas en `config/firefly.php` y los secretos en el entorno.
     ## Lo que aprendiste {.recap}
     | Concepto | Qué hace |
@@ Expand Down @@