From 11c1f9b84b37edfd77c1a8de513441113ef7bc43 Mon Sep 17 00:00:00 2001 From: Andres Contreras Date: Sat, 26 Sep 2026 22:04:15 -0700 Subject: [PATCH] Align public installation guides with the bundled library --- book/src-es/00-quickstart.md | 14 +++++++------- book/src-es/02-dependency-injection.md | 2 +- book/src-es/03-configuration.md | 2 +- book/src-es/04a-openapi.md | 4 ++-- book/src-es/10a-oauth2.md | 2 +- book/src-es/11-observability-actuator.md | 6 +----- book/src-es/13-cli-cache.md | 8 ++++---- book/src/00-quickstart.md | 12 ++++++------ book/src/02-dependency-injection.md | 2 +- book/src/03-configuration.md | 2 +- book/src/04a-openapi.md | 4 ++-- book/src/10a-oauth2.md | 2 +- book/src/11-observability-actuator.md | 6 +----- book/src/13-cli-cache.md | 8 ++++---- docs/README.md | 4 ++-- docs/cli.md | 2 +- docs/getting-started.md | 5 +++-- docs/index.md | 15 ++++++++------- docs/modules/admin.md | 12 ++++-------- docs/modules/bean-graph.md | 4 +--- docs/modules/data-browser.md | 5 ++--- docs/modules/openapi.md | 13 +++---------- docs/modules/scheduling.md | 4 ++-- docs/tutorial.es.md | 9 +++++---- docs/tutorial.md | 9 +++++---- packages/admin/README.md | 4 ++-- packages/eda-postgres/README.md | 8 +++++++- packages/installer/README.md | 15 +++++++-------- skeleton/README.md | 5 +++-- 29 files changed, 88 insertions(+), 100 deletions(-) diff --git a/book/src-es/00-quickstart.md b/book/src-es/00-quickstart.md index 91b91b43..414baa2d 100644 --- a/book/src-es/00-quickstart.md +++ b/book/src-es/00-quickstart.md @@ -2,12 +2,12 @@ # Construye Lumen paso a paso {.chtitle} -Bienvenido. Antes de la inmersión profunda, este capítulo te lleva desde una *terminal vacía* hasta una aplicación LaraFly *en ejecución y consultable con curl* — instalada, compilada y servida — en bastante menos de diez minutos. Cada comando y cada listado de este capítulo son reales: es exactamente lo que genera `composer create-project firefly/skeleton`, sin modificar. +Bienvenido. Antes de la inmersión profunda, este capítulo te lleva desde una *terminal vacía* hasta una aplicación LaraFly *en ejecución y consultable con curl* — instalada, compilada y servida — en bastante menos de diez minutos. Cada comando y cada listado de este capítulo son reales: es exactamente lo que genera `firefly new`, sin modificar. Esto es un *recorrido*, no la inmersión profunda. El Capítulo 1 argumenta el enfoque completo; el Capítulo 2 abre la sala de máquinas y explica, en profundidad, todo lo que aquí solo mencionas de pasada — el contenedor, los estereotipos y el manifiesto de arranque compilado. El objetivo de este capítulo es el impulso inicial: al terminarlo tendrás un servicio real en ejecución, y una primera sensación informal de lo que significa "convención sobre configuración" en LaraFly. !!! note "Nota" - Todos los listados de este capítulo se copian literalmente de `skeleton/`, el andamiaje de proyecto que instala `composer create-project firefly/skeleton`, y de `samples/lumen`, la aplicación más completa de monedero digital y libro mayor que este libro construye a lo largo de los capítulos siguientes. + Todos los listados de este capítulo se copian literalmente de `skeleton/`, el andamiaje de proyecto que instala `firefly new`, y de `samples/lumen`, la aplicación más completa de monedero digital y libro mayor que este libro construye a lo largo de los capítulos siguientes. --- @@ -29,7 +29,7 @@ composer --version ## Paso 2 — Instalación -La forma más rápida de iniciar una nueva aplicación LaraFly es `composer create-project`, apuntando a la plantilla `firefly/skeleton`: +El instalador `firefly new` entrega a Composer la plantilla incluida en la biblioteca: ```bash composer global require fireflyframework/larafly @@ -50,12 +50,12 @@ cd my-app Para cuando ese comando termina, `.env` ya existe, se ha creado el archivo de base de datos SQLite, `APP_KEY` está configurada y — el paso que más importa para este libro — **`firefly:cache` ya ha compilado los manifiestos de tu aplicación**. Todavía no has escrito una sola línea de PHP, y la ruta de arranque sin reflexión sobre la que se construye todo este framework ya está en su sitio. -!!! tip "Un instalador global, si lo prefieres" +!!! tip "El instalador incluido" `composer global require fireflyframework/larafly` te da un comando `firefly` en tu `PATH`. `firefly new my-app` entrega a Composer la plantilla incluida en la biblioteca, y luego ejecuta `git init` y un commit inicial por ti — el equivalente en LaraFly de `laravel new`. ### Qué acabas de instalar -El `composer.json` del andamiaje requiere solo dos paquetes de Firefly directamente: +El `composer.json` del andamiaje requiere la biblioteca principal y declara un requisito del componente CLI que esa biblioteca satisface: ```json "require": { @@ -66,7 +66,7 @@ El `composer.json` del andamiaje requiere solo dos paquetes de Firefly directame } ``` -`firefly/cli` te da los comandos `artisan firefly:*` que usarás a lo largo de este libro. `fireflyframework/larafly` es el **biblioteca completa del framework**, que contiene toda la familia Firefly (contenedor, contexto, configuración, web, datos, cqrs, eda, seguridad, validación, resiliencia, programación, observabilidad, actuator y más) en una sola línea `require`, de modo que tu propio `composer.json` nunca tiene que enumerarlos uno a uno. +`firefly/cli` te da los comandos `artisan firefly:*` que usarás a lo largo de este libro. `fireflyframework/larafly` es la **biblioteca completa del framework**, que contiene toda la familia Firefly (contenedor, contexto, configuración, web, datos, cqrs, eda, seguridad, validación, resiliencia, programación, observabilidad, actuator y más) en una sola línea `require`, de modo que tu propio `composer.json` nunca tiene que enumerarlos uno a uno. !!! laravel "Paridad con Laravel" `firefly new` es el equivalente en LaraFly de `laravel new` — y `fireflyframework/larafly` es el equivalente de instalar el propio `laravel/framework`: una línea de dependencia que trae una pila completa y coherente en lugar de una colección de piezas versionadas de forma independiente. @@ -287,7 +287,7 @@ Pasaste de una terminal vacía a una aplicación LaraFly compilada, en ejecució | En este Inicio rápido... | Se profundiza en | |---|---| -| Instalaste con `composer create-project firefly/skeleton` | **Capítulo 1** — ¿Por qué LaraFly? | +| Instalaste con `firefly new` | **Capítulo 1** — ¿Por qué LaraFly? | | Viste cómo `#[Service]`, `#[ConfigProperties]` y `#[RestController]` registran beans sin conexión manual | **Capítulo 2** — Inyección de Dependencias y Auto-Configuración | | Ejecutaste `firefly:cache` y viste rutas servidas desde un manifiesto compilado, no desde `routes/web.php` | **Capítulo 2** — Inyección de Dependencias y Auto-Configuración | diff --git a/book/src-es/02-dependency-injection.md b/book/src-es/02-dependency-injection.md index ea675f67..0ef00a1a 100644 --- a/book/src-es/02-dependency-injection.md +++ b/book/src-es/02-dependency-injection.md @@ -370,7 +370,7 @@ php artisan firefly:cache firefly:cache — wrote 14 manifest(s) + 0 proxy(ies) to /path/to/my-app/bootstrap/cache/firefly ``` -Ya ejecutaste esto una vez, de forma indirecta — `composer create-project firefly/skeleton` lo llama por ti en su script `post-create-project-cmd`, que es la razón por la que la aplicación del Inicio rápido arrancó correctamente sin que ejecutaras el comando a mano ni una sola vez. De aquí en adelante, cada vez que añadas o cambies un `#[Service]`, `#[Repository]`, `#[Configuration]` o cualquier otro atributo de Firefly, vuelve a ejecutar `firefly:cache` para recompilar el manifiesto; `php artisan firefly:clear` elimina la caché compilada y vuelve a la ruta de escaneo de desarrollo (más lenta, basada en reflexión). +Ya ejecutaste esto una vez, de forma indirecta — `firefly new` lo llama por ti en su script `post-create-project-cmd`, que es la razón por la que la aplicación del Inicio rápido arrancó correctamente sin que ejecutaras el comando a mano ni una sola vez. De aquí en adelante, cada vez que añadas o cambies un `#[Service]`, `#[Repository]`, `#[Configuration]` o cualquier otro atributo de Firefly, vuelve a ejecutar `firefly:cache` para recompilar el manifiesto; `php artisan firefly:clear` elimina la caché compilada y vuelve a la ruta de escaneo de desarrollo (más lenta, basada en reflexión). !!! tip "Consejo: `firefly:cache` no es solo para contenedores" El mismo comando también compila los manifiestos de todos los demás pilares que presentó el Capítulo 1 — rutas, proxies transaccionales, manejadores de CQRS, escuchadores de eventos, reglas de seguridad y más. La inyección de dependencias es simplemente el primero y más fundamental de ellos; la misma idea de "reflexionar una vez, congelar en un manifiesto, arrancar desde la copia congelada" se repite para cada uno. diff --git a/book/src-es/03-configuration.md b/book/src-es/03-configuration.md index 3b9f7909..1a8fe3a6 100644 --- a/book/src-es/03-configuration.md +++ b/book/src-es/03-configuration.md @@ -13,7 +13,7 @@ Al terminar este capítulo sabrás cómo `Config` de LaraFly envuelve el propio LaraFly no sustituye el sistema de configuración de Laravel — se apoya en él. Cada archivo `config/*.php`, cada llamada a `env('...')`, cada variable de `.env` que ya conoces de una aplicación Laravel corriente funciona exactamente igual en una aplicación LaraFly. El trabajo de `firefly/config` es más concreto y acotado: te da un **accesor tipado y de fallo rápido** sobre ese mismo repositorio, una forma de **vincular un subárbol entero sobre un DTO**, y un **resolutor respaldado por configuración** para el atributo `#[Value]` que introdujo el Capítulo 2. -Ya viste el ejemplo más pequeño posible de esto en el Inicio rápido. `app/GreetingProperties.php`, generado por `composer create-project firefly/skeleton`, es un DTO `#[ConfigProperties]` real y distribuido: +Ya viste el ejemplo más pequeño posible de esto en el Inicio rápido. `app/GreetingProperties.php`, generado por `firefly new`, es un DTO `#[ConfigProperties]` real y distribuido: ```php diff --git a/book/src-es/04a-openapi.md b/book/src-es/04a-openapi.md index e813f422..b759e6d2 100644 --- a/book/src-es/04a-openapi.md +++ b/book/src-es/04a-openapi.md @@ -16,10 +16,10 @@ Todas las cadenas de herramientas OpenAPI en PHP anteriores a esta te piden escr `firefly/openapi` no tiene ese modo de fallo disponible, porque no tiene una segunda fuente. El Capítulo 4 terminó con el `RouteManifest`: la tabla compilada de cada `RouteDescriptor` desde la que sirve el dispatcher, que lleva el verbo, la ruta, el estado declarado, el nombre de ruta, la clase y el método del controlador, y el *plan de enlace* por parámetro. El Capítulo 4 también presentó el `ConstraintManifest`: la lista de reglas compilada que `BeanValidator` ejecuta sobre un cuerpo `#[Valid]`. Esos dos artefactos, más el `ErrorResponse` de `firefly/kernel`, son toda la entrada: ```bash -composer require firefly/openapi +composer require fireflyframework/larafly ``` -Esa es toda la instalación. Arranca la app y `GET /openapi.json` queda servido; `GET /openapi` renderiza una consola de referencia sobre él. No se anotó nada, y nada puede divergir, porque cada hecho del documento se lee del mismo artefacto compilado que lee el dispatcher. +La biblioteca principal incluye el componente OpenAPI; las aplicaciones generadas con LaraFly ya lo tienen. Arranca la app y `GET /openapi.json` queda servido; `GET /openapi` renderiza una consola de referencia sobre él. No se anotó nada, y nada puede divergir, porque cada hecho del documento se lee del mismo artefacto compilado que lee el dispatcher. --- diff --git a/book/src-es/10a-oauth2.md b/book/src-es/10a-oauth2.md index eec79437..4ecdd760 100644 --- a/book/src-es/10a-oauth2.md +++ b/book/src-es/10a-oauth2.md @@ -11,7 +11,7 @@ Al terminar este capítulo sabrás cuál de los dos paquetes OAuth2 tienes entre ## Dos paquetes, dos direcciones -El Capítulo 10 terminó con una cadena de filtros y con el aviso de que tres de sus números pertenecían a paquetes que aquel capítulo no instalaba. Aquí están. Ninguno de los dos paquetes depende del otro — cada uno se apoya en `firefly/security` y ninguno nombra al otro — e instalar uno nunca arrastra al otro: +La biblioteca principal incluye ambos componentes OAuth2. Cada uno se apoya en `firefly/security`; sus descriptores internos no dependen el uno del otro. La configuración activa cada rol de forma independiente. Estos requisitos opcionales de componentes se satisfacen mediante el `replace` de la biblioteca ya instalada: ```bash composer require firefly/security-oauth2-client # ser un relying party: identificar personas en un proveedor diff --git a/book/src-es/11-observability-actuator.md b/book/src-es/11-observability-actuator.md index 9989d6f7..e3415f14 100644 --- a/book/src-es/11-observability-actuator.md +++ b/book/src-es/11-observability-actuator.md @@ -851,11 +851,7 @@ Un nombre de canal que no existe bajo `logging.channels` se rechaza, y la razón ## El panel de administración: `firefly/admin` -Todo lo visto hasta aquí en este capítulo es JSON, y JSON es la forma correcta para un balanceador de carga, una sonda de Kubernetes y un scraper de Prometheus. No es la forma correcta para una persona a las 3 de la madrugada que quiere saber si este proceso compiló sus manifiestos, qué auto-configuración se echó atrás, y a qué resolvió realmente `firefly.data.*`. `firefly/admin` es el paquete para esa persona: un panel de administración renderizado en el servidor sobre esos mismos endpoints del actuator, en el espíritu de Spring Boot Admin. Llega con `firefly/firefly` como el resto de la familia, así que un proyecto del esqueleto ya lo tiene — y, igual que con `firefly/actuator`, tenerlo instalado no es lo mismo que tenerlo activado. Añádelo directamente solo si cogiste los paquetes por separado: - -```bash -composer require firefly/admin -``` +Todo lo visto hasta aquí en este capítulo es JSON, y JSON es la forma correcta para un balanceador de carga, una sonda de Kubernetes y un scraper de Prometheus. No es la forma correcta para una persona a las 3 de la madrugada que quiere saber si este proceso compiló sus manifiestos, qué auto-configuración se echó atrás, y a qué resolvió realmente `firefly.data.*`. `firefly/admin` es el paquete para esa persona: un panel de administración renderizado en el servidor sobre esos mismos endpoints del actuator, en el espíritu de Spring Boot Admin. Está incluido en `fireflyframework/larafly`, así que un proyecto del esqueleto ya lo tiene — y, igual que con `firefly/actuator`, tenerlo instalado no es lo mismo que tenerlo activado. No hace falta instalar otro paquete. Después abre `/firefly`. No hay paso de npm en la instalación ni CDN en tiempo de petición — las vistas son Blade puro con CSS en línea y tipografías del sistema, porque un paquete de Composer no puede dar por hecho que npm se ha ejecutado, y un panel que necesita la red es inútil precisamente en los entornos aislados donde más quieres mirar uno. diff --git a/book/src-es/13-cli-cache.md b/book/src-es/13-cli-cache.md index 78c37d3b..e6fc689f 100644 --- a/book/src-es/13-cli-cache.md +++ b/book/src-es/13-cli-cache.md @@ -444,7 +444,7 @@ Delega a los propios comandos de base de datos de Laravel: `migrate` (por defect ## De cero a en funcionamiento: `firefly/installer` y `firefly/skeleton` -`firefly/installer` trae el comando global `firefly new` — un pequeño binario de Symfony Console, no un andamiador en sí. Sale directamente por shell hacia `composer create-project firefly/skeleton`: +`firefly/installer` trae el comando global `firefly new` — un pequeño binario de Symfony Console, no un andamiador en sí. Invoca `composer create-project` con la plantilla incluida en `fireflyframework/larafly` como repositorio local de tipo path: ```php @@ -494,7 +494,7 @@ El `#[AsCommand]` de aquí es **de Symfony**, no de Firefly, y las líneas `use` Todo proceso externo pasa por la costura `ProcessRunner` — `composer`, `php artisan`, `git` —, que es lo que hace que el flujo entero sea afirmable sin red y sin un `composer create-project` real. -`firefly/skeleton` — una plantilla de aplicación Laravel 13 genuina, de nivel superior, precableada con la familia Firefly y un par `#[RestController]`/`#[Service]` de ejemplo — es lo que `composer create-project` realmente descarga. Su propio `composer.json` cierra el bucle hacia el que todo este capítulo ha estado construyendo: `firefly:cache` se ejecuta **automáticamente**, justo después de la instalación, sin ningún paso manual: +`firefly/skeleton` — una plantilla de aplicación Laravel 13 genuina, de nivel superior, precableada con la familia Firefly y un par `#[RestController]`/`#[Service]` de ejemplo — es lo que el instalador entrega a `composer create-project` desde su propia distribución. Su propio `composer.json` cierra el bucle hacia el que todo este capítulo ha estado construyendo: `firefly:cache` se ejecuta **automáticamente**, justo después de la instalación, sin ningún paso manual: ```json "scripts": { @@ -510,7 +510,7 @@ Todo proceso externo pasa por la costura `ProcessRunner` — `composer`, `php ar Cada aplicación que `firefly new` andamia es por tanto, desde el primerísimo `git commit`, ya boot-cacheada — una aplicación genuinamente sin reflexión en disco, no meramente un framework capaz de convertirse en una. El propio `bootstrap/cache/firefly/` está en `.gitignore` en el esqueleto (los manifiestos se generan frescos por instalación, no se commitean), que es exactamente lo que esperarías de un artefacto de compilación en lugar de código fuente. !!! laravel "Paridad con Laravel" - `composer create-project laravel/laravel` te da una app Laravel desnuda sin nada precableado; `firefly new` (o `composer create-project firefly/skeleton`) te da la misma app Laravel, más la familia Firefly ya requerida, más un par de estereotipos de ejemplo, más una caché de arranque ya calentada — el equivalente al "genera un proyecto de arranque funcional" de Spring Initializr, apuntado a `artisan` en lugar de a un formulario web. `make:firefly-*` refleja la propia familia `make:controller`/`make:model` de Laravel exactamente en espíritu — un `GeneratorCommand` de Artisan, un stub, un marcador de namespace — solo que un atributo de estereotipo más profundo. + `composer create-project laravel/laravel` te da una app Laravel desnuda sin nada precableado; `firefly new` te da la misma app Laravel, más la familia Firefly ya requerida, más un par de estereotipos de ejemplo, más una caché de arranque ya calentada — el equivalente al "genera un proyecto de arranque funcional" de Spring Initializr, apuntado a `artisan` en lugar de a un formulario web. `make:firefly-*` refleja la propia familia `make:controller`/`make:model` de Laravel exactamente en espíritu — un `GeneratorCommand` de Artisan, un stub, un marcador de namespace — solo que un atributo de estereotipo más profundo. --- @@ -524,7 +524,7 @@ Cada aplicación que `firefly new` andamia es por tanto, desde el primerísimo ` | `firefly:about` / `:routes` / `:health` / `:metrics` | Renderiza los endpoints de actuator del Capítulo 11 en el terminal, en-proceso, sin ida y vuelta HTTP | | `make:firefly-*` | Ocho generadores, uno por estereotipo — `GeneratorCommand` + un stub, exactamente como la propia familia `make:*` de Laravel | | `firefly:serve` / `firefly:db` | Pasarelas finas a `artisan serve`/`octane:start` y a los propios comandos de base de datos de Laravel | -| `firefly new` (`firefly/installer`) | Sale por shell hacia `composer create-project firefly/skeleton`; el esqueleto ejecuta `firefly:cache` automáticamente tras la instalación | +| `firefly new` (`firefly/installer`) | Entrega la plantilla incluida a `composer create-project`; el esqueleto ejecuta `firefly:cache` automáticamente tras la instalación | --- diff --git a/book/src/00-quickstart.md b/book/src/00-quickstart.md index 65cc842e..97478433 100644 --- a/book/src/00-quickstart.md +++ b/book/src/00-quickstart.md @@ -2,12 +2,12 @@ # Build Lumen Step by Step {.chtitle} -Welcome. Before the deep dive, this chapter takes you from an *empty terminal* to a *running, curl-able* LaraFly application — installed, compiled, and served — in well under ten minutes. Every command and every listing here is real: it is exactly what `composer create-project firefly/skeleton` generates, unmodified. +Welcome. Before the deep dive, this chapter takes you from an *empty terminal* to a *running, curl-able* LaraFly application — installed, compiled, and served — in well under ten minutes. Every command and every listing here is real: it is exactly what `firefly new` generates, unmodified. This is a *tour*, not the deep dive. Chapter 1 makes the case for the whole approach; Chapter 2 opens the engine room and explains, in depth, everything you meet here only in passing — the container, the stereotypes, and the compiled boot manifest. The goal of this chapter is momentum: by the end of it you will have a real service running, and a first, informal feel for what "convention over configuration" means in LaraFly. !!! note "Note" - Every listing in this chapter is copied verbatim from `skeleton/`, the project scaffold `composer create-project firefly/skeleton` installs, and from `samples/lumen`, the fuller digital-wallet-and-ledger application this book builds toward over the chapters that follow. + Every listing in this chapter is copied verbatim from `skeleton/`, the project scaffold `firefly new` installs, and from `samples/lumen`, the fuller digital-wallet-and-ledger application this book builds toward over the chapters that follow. --- @@ -29,7 +29,7 @@ composer --version ## Step 2 — Install -The fastest way to start a new LaraFly application is `composer create-project`, pointed at the `firefly/skeleton` template: +The bundled `firefly new` installer supplies the application template to Composer: ```bash composer global require fireflyframework/larafly @@ -50,12 +50,12 @@ cd my-app By the time that command returns, `.env` exists, a SQLite database file has been touched, `APP_KEY` is set, and — the step that matters most for this book — **`firefly:cache` has already compiled your application's manifests**. You have not written a single line of PHP yet, and the zero-reflection boot path this whole framework is built around is already in place. -!!! tip "A global installer, if you prefer it" +!!! tip "The bundled installer" `composer global require fireflyframework/larafly` gives you a `firefly` command on your `PATH`. `firefly new my-app` supplies the bundled skeleton to Composer, then runs `git init` and an initial commit for you — the LaraFly equivalent of `laravel new`. ### What you just installed -The skeleton's `composer.json` requires only two Firefly packages directly: +The skeleton's `composer.json` requires the root library and records a CLI component requirement satisfied by that library: ```json "require": { @@ -287,7 +287,7 @@ You went from an empty terminal to a compiled, running, curl-able LaraFly applic | In this Quick Start you… | Goes deep in | |---|---| -| Installed via `composer create-project firefly/skeleton` | **Chapter 1** — Why LaraFly? | +| Installed via `firefly new` | **Chapter 1** — Why LaraFly? | | Saw `#[Service]`, `#[ConfigProperties]`, and `#[RestController]` register beans with no manual wiring | **Chapter 2** — Dependency Injection & Auto-Configuration | | Ran `firefly:cache` and saw routes served from a compiled manifest, not `routes/web.php` | **Chapter 2** — Dependency Injection & Auto-Configuration | diff --git a/book/src/02-dependency-injection.md b/book/src/02-dependency-injection.md index dd1452ee..8f0103ba 100644 --- a/book/src/02-dependency-injection.md +++ b/book/src/02-dependency-injection.md @@ -370,7 +370,7 @@ php artisan firefly:cache firefly:cache — wrote 14 manifest(s) + 0 proxy(ies) to /path/to/my-app/bootstrap/cache/firefly ``` -You already ran this once, indirectly — `composer create-project firefly/skeleton` calls it for you in its `post-create-project-cmd` script, which is why the Quick Start's application booted correctly without you ever running the command by hand. From here on, any time you add or change a `#[Service]`, `#[Repository]`, `#[Configuration]`, or any other Firefly attribute, re-run `firefly:cache` to recompile the manifest; `php artisan firefly:clear` deletes the compiled cache and falls back to the slower, reflection-based development scan. +You already ran this once, indirectly — `firefly new` calls it for you in its `post-create-project-cmd` script, which is why the Quick Start's application booted correctly without you ever running the command by hand. From here on, any time you add or change a `#[Service]`, `#[Repository]`, `#[Configuration]`, or any other Firefly attribute, re-run `firefly:cache` to recompile the manifest; `php artisan firefly:clear` deletes the compiled cache and falls back to the slower, reflection-based development scan. !!! tip "Tip: `firefly:cache` is not just for containers" The same command also compiles the manifests for every other pillar Chapter 1 introduced — routes, transactional proxies, CQRS handlers, event listeners, security rules, and more. Dependency injection is simply the first and most foundational one; the same "reflect once, freeze into a manifest, boot from the frozen copy" idea repeats for every one of them. diff --git a/book/src/03-configuration.md b/book/src/03-configuration.md index 5ed9523d..e8ddcf27 100644 --- a/book/src/03-configuration.md +++ b/book/src/03-configuration.md @@ -13,7 +13,7 @@ By the end of this chapter you will know how LaraFly's `Config` wraps Laravel's LaraFly does not replace Laravel's configuration system — it rides on top of it. Every `config/*.php` file, every `env('...')` call, every `.env` variable you already know from a plain Laravel application works exactly the same way in a LaraFly one. `firefly/config`'s job is narrower and more specific: it gives you a **typed, fail-fast accessor** over that same repository, a way to **bind a whole subtree onto a DTO**, and a **config-backed resolver** for the `#[Value]` attribute Chapter 2 introduced. -You already met the smallest possible example of this in the Quick Start. `app/GreetingProperties.php`, generated by `composer create-project firefly/skeleton`, is a real, shipped `#[ConfigProperties]` DTO: +You already met the smallest possible example of this in the Quick Start. `app/GreetingProperties.php`, generated by `firefly new`, is a real, shipped `#[ConfigProperties]` DTO: ```php diff --git a/book/src/04a-openapi.md b/book/src/04a-openapi.md index dcfd41e7..e7e07d81 100644 --- a/book/src/04a-openapi.md +++ b/book/src/04a-openapi.md @@ -16,10 +16,10 @@ Every OpenAPI toolchain in PHP that predates this one asks you to write the docu `firefly/openapi` does not have that failure mode available to it, because it does not have a second source. Chapter 4 ended with `RouteManifest`: the compiled table of every `RouteDescriptor` the dispatcher serves from, carrying the verb, the path, the declared status, the route name, the controller class and method, and the per-parameter *binding plan*. Chapter 4 also introduced `ConstraintManifest`: the compiled rule list `BeanValidator` runs on a `#[Valid]` body. Those two artifacts, plus `firefly/kernel`'s `ErrorResponse`, are the entire input: ```bash -composer require firefly/openapi +composer require fireflyframework/larafly ``` -That is the whole installation. Boot the app and `GET /openapi.json` is served; `GET /openapi` renders a reference console over it. Nothing was annotated, and nothing can drift, because every fact in the document is read from the same compiled artifact the dispatcher reads. +The root library includes the OpenAPI component; generated LaraFly applications already have it. Boot the app and `GET /openapi.json` is served; `GET /openapi` renders a reference console over it. Nothing was annotated, and nothing can drift, because every fact in the document is read from the same compiled artifact the dispatcher reads. --- diff --git a/book/src/10a-oauth2.md b/book/src/10a-oauth2.md index f9502bdf..864f4afe 100644 --- a/book/src/10a-oauth2.md +++ b/book/src/10a-oauth2.md @@ -11,7 +11,7 @@ By the end of this chapter you will know which of the two OAuth2 packages you ar ## Two packages, two directions -Chapter 10 ended with a filter chain and a warning that three of its numbers belonged to packages that chapter did not install. Here they are. Neither package is a dependency of the other — each builds on `firefly/security` and neither names the other — and installing one never drags the other in: +The root library includes both OAuth2 components. Each builds on `firefly/security`; their internal dependency descriptors do not depend on one another. Configuration enables each role independently. These optional component requirements are satisfied by the already-installed library through `replace`: ```bash composer require firefly/security-oauth2-client # be a relying party: sign people in through a provider diff --git a/book/src/11-observability-actuator.md b/book/src/11-observability-actuator.md index b5e3b872..0acbb9bd 100644 --- a/book/src/11-observability-actuator.md +++ b/book/src/11-observability-actuator.md @@ -851,11 +851,7 @@ A channel name that does not exist under `logging.channels` is refused, and the ## The admin dashboard: `firefly/admin` -Everything so far in this chapter is JSON, and JSON is the right shape for a load balancer, a Kubernetes probe and a Prometheus scraper. It is not the right shape for a person at 3am who wants to know whether this process compiled its manifests, which auto-configuration backed off, and what `firefly.data.*` actually resolved to. `firefly/admin` is the package for that person: a server-rendered browser dashboard over the very same actuator endpoints, in the spirit of Spring Boot Admin. It arrives with `firefly/firefly` like the rest of the family, so a skeleton project already has it — and, as with `firefly/actuator`, having it installed is not the same as having it switched on. Add it directly only if you took the packages à la carte: - -```bash -composer require firefly/admin -``` +Everything so far in this chapter is JSON, and JSON is the right shape for a load balancer, a Kubernetes probe and a Prometheus scraper. It is not the right shape for a person at 3am who wants to know whether this process compiled its manifests, which auto-configuration backed off, and what `firefly.data.*` actually resolved to. `firefly/admin` is the package for that person: a server-rendered browser dashboard over the very same actuator endpoints, in the spirit of Spring Boot Admin. It is included in `fireflyframework/larafly`, so a skeleton project already has it — and, as with `firefly/actuator`, having it installed is not the same as having it switched on. No separate package is needed. Then open `/firefly`. There is no npm step at install time and no CDN at request time — the views are plain Blade with inline CSS and system fonts, because a Composer package cannot assume npm has run, and a dashboard that needs the network is useless in exactly the isolated environments where you most want to look at one. diff --git a/book/src/13-cli-cache.md b/book/src/13-cli-cache.md index a61de620..ed49446d 100644 --- a/book/src/13-cli-cache.md +++ b/book/src/13-cli-cache.md @@ -444,7 +444,7 @@ Delegates to Laravel's own database commands: `migrate` (default), `db:seed` (`f ## From zero to running: `firefly/installer` and `firefly/skeleton` -`firefly/installer` ships the global `firefly new` command — a small Symfony Console binary, not itself a scaffolder. It shells straight out to `composer create-project firefly/skeleton`: +`firefly/installer` ships the global `firefly new` command — a small Symfony Console binary, not itself a scaffolder. It invokes `composer create-project` with the template bundled in `fireflyframework/larafly` as a local path repository: ```php @@ -494,7 +494,7 @@ final class NewCommand extends Command Every external process goes through the `ProcessRunner` seam — `composer`, `php artisan`, `git` — which is what makes the whole flow assertable without a network or a real `composer create-project`. -`firefly/skeleton` — a genuine, top-level Laravel 13 application template pre-wired with the Firefly family and a sample `#[RestController]`/`#[Service]` pair — is what `composer create-project` actually pulls down. Its own `composer.json` closes the loop this whole chapter has been building toward: `firefly:cache` runs **automatically**, right after install, with no manual step: +`firefly/skeleton` — a genuine, top-level Laravel 13 application template pre-wired with the Firefly family and a sample `#[RestController]`/`#[Service]` pair — is what the installer supplies to `composer create-project` from its own distribution. Its own `composer.json` closes the loop this whole chapter has been building toward: `firefly:cache` runs **automatically**, right after install, with no manual step: ```json "scripts": { @@ -510,7 +510,7 @@ Every external process goes through the `ProcessRunner` seam — `composer`, `ph Every application `firefly new` scaffolds is therefore, from the very first `git commit`, already boot-cached — a genuinely zero-reflection application on disk, not merely a framework capable of becoming one. `bootstrap/cache/firefly/` itself is `.gitignore`d in the skeleton (the manifests are generated fresh per install, not committed), which is exactly what you would expect of a build artifact rather than source. !!! laravel "Laravel parity" - `composer create-project laravel/laravel` gives you a bare Laravel app with nothing pre-wired; `firefly new` (or `composer create-project firefly/skeleton`) gives you the same Laravel app, plus the Firefly family pre-required, plus a sample stereotype pair, plus a boot cache already warmed — the equivalent of Spring Initializr's "generate a working starter project," aimed at `artisan` rather than a web form. `make:firefly-*` mirrors Laravel's own `make:controller`/`make:model` family exactly in spirit — an Artisan `GeneratorCommand`, a stub, a namespace placeholder — just one stereotype attribute deeper. + `composer create-project laravel/laravel` gives you a bare Laravel app with nothing pre-wired; `firefly new` gives you the same Laravel app, plus the Firefly family pre-required, plus a sample stereotype pair, plus a boot cache already warmed — the equivalent of Spring Initializr's "generate a working starter project," aimed at `artisan` rather than a web form. `make:firefly-*` mirrors Laravel's own `make:controller`/`make:model` family exactly in spirit — an Artisan `GeneratorCommand`, a stub, a namespace placeholder — just one stereotype attribute deeper. --- @@ -524,7 +524,7 @@ Every application `firefly new` scaffolds is therefore, from the very first `git | `firefly:about` / `:routes` / `:health` / `:metrics` | Renders Chapter 11's actuator endpoints at the terminal, in-process, no HTTP round trip | | `make:firefly-*` | Eight generators, one per stereotype — `GeneratorCommand` + a stub, exactly like Laravel's own `make:*` family | | `firefly:serve` / `firefly:db` | Thin passthroughs to `artisan serve`/`octane:start` and Laravel's own database commands | -| `firefly new` (`firefly/installer`) | Shells out to `composer create-project firefly/skeleton`; the skeleton runs `firefly:cache` automatically post-install | +| `firefly new` (`firefly/installer`) | Supplies the bundled skeleton to `composer create-project`; the skeleton runs `firefly:cache` automatically post-install | --- diff --git a/docs/README.md b/docs/README.md index eaa96509..532bcea4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,10 +17,10 @@ | Guide | Description | |-------|-------------| | [Introduction](index.md) | What LaraFly is, the pitch, and a map of the docs | -| [Installation](installation.md) | Requirements, `composer create-project firefly/skeleton`, and manual install | +| [Installation](installation.md) | Requirements, the bundled `firefly new` installer, and manual install | | [Getting Started](getting-started.md) | Boot the `firefly/skeleton` template, write your first `#[RestController]`/`#[Service]`, run `firefly:cache` | | [Architecture](architecture.md) | The hexagonal design, the boot pipeline, and how the Deptrac layers fit together | -| [Tutorial](tutorial.md) | A hand-built, 12-step walkthrough — from `composer create-project` to a `#[Repository]`/`#[Valid]`/CQRS/`#[EventListener]` feature slice | +| [Tutorial](tutorial.md) | A hand-built, 12-step walkthrough — from `firefly new` to a `#[Repository]`/`#[Valid]`/CQRS/`#[EventListener]` feature slice | | [Lumen Sample](../samples/lumen/) | A runnable digital-wallet & ledger sample exercising `#[Transactional]`, CQRS, domain events over EDA, method security, and a REST layer with RFC-7807 problem-details | --- diff --git a/docs/cli.md b/docs/cli.md index 0a5eb64d..9241f7ad 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -87,7 +87,7 @@ the sole owner of the loading half of the contract. An app that skipped the comp `firefly/firefly` metapackage, which did not require the CLI — booted with no routes (404 on everything it owned) and, worse, with an empty method-security manifest: both enforcement sites read "no rule for this method" as ALLOW, so `#[PreAuthorize]`, `#[Secured]` and `#[RolesAllowed]` all failed **open**. `firefly/cli` is -now part of the `firefly/firefly` metapackage, and `firefly.security.method.strict` (default `false`) makes the +now included in the `fireflyframework/larafly` library, and `firefly.security.method.strict` (default `false`) makes the strict reading available to anyone who wants a build that ships without a compiled manifest to refuse to boot rather than run unprotected. diff --git a/docs/getting-started.md b/docs/getting-started.md index 1a063fd4..9659c536 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,7 +2,8 @@ ## Quickstart: `firefly/skeleton` -The fastest way to a booting, cached LaraFly app is the `firefly/skeleton` create-project template — a Laravel 13 +The fastest way to a booting, cached LaraFly app is the installer and `firefly/skeleton` template bundled in +`fireflyframework/larafly` — a Laravel 13 application pre-wired with the Firefly family, a `#[Controller]` welcome page, a sample `#[RestController]`/`#[Service]` pair, and `firefly:cache` already wired into `post-create-project-cmd`: @@ -14,7 +15,7 @@ php artisan firefly:cache php artisan firefly:serve ``` -`composer create-project` alone already ran `migrate` and `firefly:cache` for you (via +The installer invokes Composer on the bundled template, which already ran `migrate` and `firefly:cache` for you (via `post-create-project-cmd`), so the app boots reflection-free and its sample `POST /orders` persists from the first request; re-run `firefly:cache` whenever you add or change `#[Component]`/`#[RestController]`/`#[CommandHandler]`/etc. classes. `firefly:clear` drops back to the diff --git a/docs/index.md b/docs/index.md index a6580fc5..cfc95d05 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,8 +8,8 @@ CQRS, event-driven architecture, first-party security including both halves of O 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 is one monorepo of small, independently-installable Composer packages, wired together by -a single zero-reflection boot pipeline: a component scan compiles to a cached manifest once, and every +The whole framework ships as one Composer library, `fireflyframework/larafly`, containing all 29 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 @@ -19,7 +19,7 @@ request after that runs against plain PHP arrays — no runtime reflection on th
Install [Installation](installation.md) -Requirements, the `firefly new` quick install, and `composer create-project` on its own when you would rather not install a global binary. +Requirements, the bundled `firefly new` installer, and using the local template from a framework source checkout.
@@ -31,7 +31,7 @@ request after that runs against plain PHP arrays — no runtime reflection on th
Build something [Tutorial](tutorial.md) · [Tutorial (Español)](tutorial.es.md) -A hand-built, 12-step walkthrough from `composer create-project` to a `#[Repository]`/`#[Valid]`/CQRS/`#[EventListener]` feature slice, with a curl'd expected output at every step. +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.
@@ -51,7 +51,8 @@ request after that runs against plain PHP arrays — no runtime reflection on th ## Quickstart ```bash -composer create-project firefly/skeleton my-app +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 @@ -63,7 +64,7 @@ See [Installation](installation.md) for requirements and manual setup, and ## Why LaraFly? - **Attribute-driven DI & auto-configuration** — `#[Service]`, `#[Repository]`, `#[Configuration]` classes are - discovered by a compiled scan; install a capability package and its defaults wire themselves up, your own + 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. @@ -102,7 +103,7 @@ See [Installation](installation.md) for requirements and manual setup, and ## The modules -Every capability above ships as a package you install on its own. The [module index](modules.md) lays all 32 +Every capability above ships in the root library; configuration selects optional features. The [module index](modules.md) lays all 32 guides out by concern, with a line on each saying what it is for, and the same grouping is the site's **Modules** tab. diff --git a/docs/modules/admin.md b/docs/modules/admin.md index eb6a2bdb..f584b096 100644 --- a/docs/modules/admin.md +++ b/docs/modules/admin.md @@ -5,18 +5,14 @@ structural difference: it is not a separate monitoring application you deploy an Blade views *inside* the application it reports on, which is why it can read the endpoint registry directly, and why its access model matters as much as it does. -It arrives with the runtime family — `firefly/firefly` requires it, so a `composer create-project -firefly/skeleton` project already has it and `firefly new --with admin` only makes the dependency explicit in -your own `composer.json`. Add it directly if you took the packages à la carte: - -```bash -composer require firefly/admin -``` +It is included in `fireflyframework/larafly`, so every generated application already has it. +`firefly new --with=admin` records an explicit component requirement in your own `composer.json`; +the root library satisfies that requirement through `replace`. Then open `/firefly`. **Installed is not enabled**: `firefly.admin.enabled` defaults to `app.debug`, so the package being present costs a production deployment nothing. That default, not the absence of the package, is what stands between the dashboard and the internet — which is why the warning below matters more than the -install line above. +component requirement above. !!! warning "The access model is the whole security model" `firefly.admin.enabled` defaults to `app.debug`, because the dashboard bypasses the actuator's diff --git a/docs/modules/bean-graph.md b/docs/modules/bean-graph.md index 176238e1..c7aee80f 100644 --- a/docs/modules/bean-graph.md +++ b/docs/modules/bean-graph.md @@ -8,9 +8,7 @@ what each one is **wired to**, which is what you actually want when a `#[Conditi way you expected, when a cycle has hung a boot, or when you are trying to work out what a package you just installed attached itself to. -``` -composer require firefly/admin # already required by firefly/firefly; the graph is a page of the dashboard, not a package of its own -``` +The graph is a dashboard page included in `fireflyframework/larafly`; no separate package is needed. ## What counts as a node diff --git a/docs/modules/data-browser.md b/docs/modules/data-browser.md index 3aacec18..6d6eb8f6 100644 --- a/docs/modules/data-browser.md +++ b/docs/modules/data-browser.md @@ -10,9 +10,8 @@ It is **off by default, and it does not inherit the dashboard's default.** Read `firefly.admin.data.enabled` turns the browser on and `firefly.admin.data.writable` permits writes on top of it. Both default to **false** and neither is implied by `app.debug` or by `firefly.admin.enabled` — see [The two gates](#the-two-gates), which is the point of this page. -```bash -composer require firefly/admin # already required by firefly/firefly; the browser is a part of the dashboard, not a package of its own -``` + +The browser is part of the dashboard included in `fireflyframework/larafly`; no separate package is needed. `DataBrowser` is the single entry point, and `DataBrowser::forContainer($container)` assembles one from the application container in a line. Discovery, schema derivation, reads and the two writes all go through it, and diff --git a/docs/modules/openapi.md b/docs/modules/openapi.md index b6702242..9cd1d336 100644 --- a/docs/modules/openapi.md +++ b/docs/modules/openapi.md @@ -4,20 +4,13 @@ memory. There is no annotation dialect to learn and nothing to keep in sync by hand: `RouteManifest` supplies the paths, verbs, statuses, route names and the per-parameter binding plan; `ConstraintManifest` supplies the request-body schemas and their `required` lists; `firefly/kernel`'s `ErrorResponse` supplies the RFC 9457 error -component. Install the package and a LaraFly app has a spec — and therefore typed clients — for free. +component. It is included in the LaraFly library, so applications can generate a spec and typed clients. Because every fact in the document is read from the same compiled artifacts the dispatcher dispatches from and the validator validates with, **the spec cannot drift from the server**. -`firefly/firefly` requires it, so a skeleton project already serves `/openapi` and `/openapi.json`. Add it -directly if you took the packages à la carte: - -```bash -composer require firefly/openapi -``` - -`firefly/firefly` requires it, so a project built from the skeleton already has it; the line above is for an -application that took the packages à la carte. +`fireflyframework/larafly` includes it, so a skeleton project already serves `/openapi` and `/openapi.json`. +An explicit `firefly/openapi` requirement is satisfied by the root library's `replace` metadata. ## What you get diff --git a/docs/modules/scheduling.md b/docs/modules/scheduling.md index 62133bce..837db9e1 100644 --- a/docs/modules/scheduling.md +++ b/docs/modules/scheduling.md @@ -33,7 +33,7 @@ always wins): |---|---|---|---| | *(unset)* / `none` | `NoneLock` | `firefly/scheduling` | **The default.** Every `tryAcquire()` succeeds and `release()` is a no-op — correct for a single-instance deployment (the only "node" always wins) and for a bare skeleton with no lock infrastructure, but provides **no real mutual exclusion** across nodes. | | `cache` | `CacheLock` | `firefly/scheduling` | Wraps Laravel's atomic `Cache::lock()`. Works over any lock-capable driver (`database`, `redis`, `memcached`, and `array` for tests). The `null` cache driver grants **no-op** locks (every acquire "succeeds" with no real exclusion, same as `NoneLock`); `array` is **per-process only** — it does not coordinate across separate PHP-FPM workers or hosts. Production multi-node deployments need `database` or `redis`. | -| `postgres` | `PgAdvisoryLock` | `firefly/scheduling-postgres` | Session-scoped Postgres advisory lock (see below). Requires installing the separate adapter package. | +| `postgres` | `PgAdvisoryLock` | `firefly/scheduling-postgres` | Session-scoped Postgres advisory lock (see below). Included in the root library; requires a PostgreSQL connection and `ext-pdo_pgsql`. | `CacheLock::tryAcquire()` throws a `ConfigurationException` up front if the configured cache store isn't a `LockProvider` at all (rather than silently degrading), naming the driver requirement explicitly. @@ -45,7 +45,7 @@ always wins): (`PgAdvisoryLock::key()`, the top 60 bits of a SHA-256 digest folded into the signed `bigint` range). It opts in only behind `firefly.scheduling.lock.provider=postgres`, gated by `PgAdvisoryLockAutoConfiguration`'s `#[ConditionalOnProperty(name: 'firefly.scheduling.lock.provider', -havingValue: 'postgres')]` — installing the package with the property unset is otherwise completely inert +havingValue: 'postgres')]` — the bundled adapter remains inactive when the property is unset (`#[Order(1000)]` matches `SchedulingAutoConfiguration`'s own default bean, which backs off via `#[ConditionalOnMissingBean]` once this one binds `DistributedLock`). diff --git a/docs/tutorial.es.md b/docs/tutorial.es.md index 7df28cb5..8cbad1ff 100644 --- a/docs/tutorial.es.md +++ b/docs/tutorial.es.md @@ -1,7 +1,7 @@ # Tutorial: construye tu primera funcionalidad LaraFly Este es un recorrido paso a paso, construido a mano, de cómo levantar una funcionalidad LaraFly real desde -un `composer create-project` vacío hasta una porción completa gobernada por atributos — un controlador REST, +una aplicación creada con `firefly new` hasta una porción completa gobernada por atributos — un controlador REST, un servicio, configuración tipada, un modelo de dominio respaldado por un repositorio, validación de peticiones, manejo de errores RFC-7807, un par de comando/consulta CQRS y un listener de evento de dominio. Cada bloque de código de abajo es fiel al framework tal como se distribuye en este repositorio — los @@ -40,10 +40,11 @@ Consulta [Instalación](installation.md) para la lista completa de requisitos. ## Paso 1: crea la aplicación -Genera una nueva aplicación LaraFly con la plantilla de Composer `firefly/skeleton`: +Instala LaraFly y genera una nueva aplicación con la plantilla incluida: ```bash -composer create-project firefly/skeleton my-app +composer global require fireflyframework/larafly +firefly new my-app cd my-app ``` @@ -53,7 +54,7 @@ arranca y que ya está cacheada: copia `.env.example` a `.env`, crea `database/d `orders`, así que `POST /orders` funciona en la primera petición y no tras un paso que alguien tenga que contarte) y ejecuta `php artisan firefly:cache` — el paso de compilación sin reflexión que retomarás en el [Paso 11](#paso-11-la-cache-sin-reflexion-y-la-introspeccion-de-salud). Consulta -[Instalación](installation.md) para el atajo equivalente del instalador global `firefly new my-app`. +[Instalación](installation.md) para usar la plantilla local directamente desde un checkout del framework. El proyecto generado tiene este aspecto: diff --git a/docs/tutorial.md b/docs/tutorial.md index c66be46c..f1a21ebc 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -1,7 +1,7 @@ # Tutorial: Build Your First LaraFly Feature This is a hand-built, step-by-step walkthrough of building a real LaraFly feature from an empty -`composer create-project` to a fully attribute-driven slice — a REST controller, a service, typed +`firefly new` application to a fully attribute-driven slice — a REST controller, a service, typed configuration, a repository-backed domain model, request validation, RFC-7807 error handling, a CQRS command/query pair, and a domain event listener. Every code block below is accurate to the framework as shipped in this repository — attributes, class names, and method signatures are taken verbatim from @@ -39,10 +39,11 @@ See [Installation](installation.md) for the full requirements list. ## Step 1: Create the App -Scaffold a new LaraFly application with the `firefly/skeleton` Composer template: +Install LaraFly and scaffold a new application with its bundled template: ```bash -composer create-project firefly/skeleton my-app +composer global require fireflyframework/larafly +firefly new my-app cd my-app ``` @@ -52,7 +53,7 @@ already-cached app: it copies `.env.example` to `.env`, touches `database/databa so `POST /orders` works on the first request rather than after a step you have to be told about), and runs `php artisan firefly:cache` — the zero-reflection compile step you'll revisit in [Step 11](#step-11-the-zero-reflection-cache-and-health-introspection). See -[Installation](installation.md) for the equivalent `firefly new my-app` global-installer shortcut. +[Installation](installation.md) for using the local template directly from a framework source checkout. The scaffolded project looks like this: diff --git a/packages/admin/README.md b/packages/admin/README.md index 6fb081d4..7d030cfc 100644 --- a/packages/admin/README.md +++ b/packages/admin/README.md @@ -4,10 +4,10 @@ The LaraFly admin dashboard — a server-rendered browser view over the actuator [Spring Boot Admin](https://docs.spring-boot-admin.com/). ```bash -composer require firefly/admin +composer require fireflyframework/larafly ``` -Then open `/firefly`. +The library includes `firefly/admin`. When `firefly.admin.enabled` is on (default: `app.debug`), open `/firefly`. ## What it shows diff --git a/packages/eda-postgres/README.md b/packages/eda-postgres/README.md index 772da952..c6be8d0c 100644 --- a/packages/eda-postgres/README.md +++ b/packages/eda-postgres/README.md @@ -10,7 +10,13 @@ drives matching `#[EventListener]` handlers, and marks them `PUBLISHED` (or `FAI downstream broker. Auto-configured behind `firefly.eda.provider=postgres`, with a `PostgresHealthIndicator`. ```bash -composer require firefly/eda-postgres +composer require fireflyframework/larafly +``` + +The library includes the PostgreSQL adapter. Enable `ext-pdo_pgsql` and set +`firefly.eda.provider` to `postgres` before migrating and starting delivery: + +```bash php artisan migrate # creates firefly_eda_outbox php artisan firefly:eda:consume # terminal in-process delivery ``` diff --git a/packages/installer/README.md b/packages/installer/README.md index caa6e131..f61700df 100644 --- a/packages/installer/README.md +++ b/packages/installer/README.md @@ -27,14 +27,14 @@ firefly new my-shop --full --with=eda-postgres `--with=` takes a comma-separated capability list (repeat the flag if you prefer). Run `firefly new --help` for the current list — it is interpolated from the catalog, so it cannot drift from what the flag accepts. -A capability's only footprint is a line in the generated `composer.json`: firefly's conditional -auto-configuration means an installed capability is a wired capability, so there is no second copy of the -package's own defaults for you to keep in sync. +A capability records a requirement in the generated `composer.json`, satisfied by the root library's +`replace` metadata. All component code is included; configuration selects optional features. +`--with=testing` also adds the external test harness to the application's development dependencies. Adapters (`eda-kafka`, `eda-rabbitmq`, `eda-postgres`, `scheduling-postgres`) pull their port in with them and are deliberately **excluded from `--full`**: which broker or engine an application talks to is not -something an archetype can guess, and guessing would install a broker client — or demand a PHP extension — -the machine may not have. `security-oauth2-client` pulls `security` in the same way — a login with no +something an archetype can guess. Their code is already bundled, but configuring PostgreSQL or Kafka still +requires the corresponding PHP extension. `security-oauth2-client` pulls `security` in the same way — a login with no principal model to sign into is not a shape worth generating — but it is a capability, not an adapter, so `--full` includes it. @@ -62,9 +62,8 @@ has no flag that says otherwise. ## Where the capability list comes from -`Firefly\Installer\CapabilityCatalog` — a declarative map owned by this package, not a scan. A global -install has no monorepo on disk to enumerate and no firefly runtime package to introspect; the installer -runs before the framework exists. The enumeration happens in CI instead: `CapabilityCatalogTest` reads the +`Firefly\Installer\CapabilityCatalog` — a declarative map of the choices exposed by the installer. +CI validates it against the bundled components: `CapabilityCatalogTest` reads the real `packages/*` directory and fails the build when a firefly package is neither a capability nor listed, with a reason, in `CapabilityCatalog::corePackages()`. diff --git a/skeleton/README.md b/skeleton/README.md index 57c49aac..0f07335c 100644 --- a/skeleton/README.md +++ b/skeleton/README.md @@ -9,11 +9,12 @@ external infrastructure** (sqlite + array/sync drivers by default). ## Create a new app ```bash -composer create-project firefly/skeleton my-app +composer global require fireflyframework/larafly +firefly new my-app cd my-app ``` -`composer create-project` runs `post-create-project-cmd`, which: +The installer supplies this bundled template to Composer, whose `post-create-project-cmd`: 1. copies `.env.example` to `.env`, 2. touches the default `database/database.sqlite`,