diff --git a/.github/wiki b/.github/wiki index 9026028..92ad28e 160000 --- a/.github/wiki +++ b/.github/wiki @@ -1 +1 @@ -Subproject commit 90260281826f7a43e5e177178a9a75ad15c7ca2b +Subproject commit 92ad28e781930b30d2915a1f7327699a0484a422 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e33af2d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# AGENTS - Fast Forward Framework + +This repository is a PHP metapackage (`fast-forward/framework`) that aggregates and wires core +Fast Forward components through a single provider entry point. + +## Repository surfaces + +- Primary package entrypoint: [`src/`](src/) +- Container/service-provider behavior: [`src/ConfigProvider/`](src/ConfigProvider/) +- Tests: [`tests/`](tests/) +- Docs: [`docs/`](docs/) +- CI configuration: [`.github/workflows/`](.github/workflows/) +- Release history: [`CHANGELOG.md`](CHANGELOG.md) +- Project README: [`README.md`](README.md) + +## Setup and local workflow + +- Run `composer install` before making any code changes. +- Keep local runtime aligned to PHP 8.3 (project minimum). +- Run full local validation with: + - `composer dev-tools` +- Apply auto-fixes and generated file synchronization with: + - `composer dev-tools:fix` +- Validate changelog discipline on PR branches with: + - `composer dev-tools changelog:check -- --against=refs/remotes/origin/main` + +## Testing and quality gates + +- Primary test command: `composer dev-tools` (includes PHPUnit and report generation). +- Focused test command used by the dev-tools pipeline: `vendor/bin/phpunit`. +- Relevant changelog and release workflow checks are in + [`.github/workflows/changelog.yml`](.github/workflows/changelog.yml) and + [`.github/workflows/tests.yml`](.github/workflows/tests.yml). + +## Documentation conventions + +- Keep docs consistent with metapackage usage snippets and avoid instantiating providers directly + when the `::class` shorthand is the canonical documented pattern. +- Use `FrameworkServiceProvider::class` in documented bootstrap examples per current standards. + +## PR and review expectations + +- When making user-visible changes, add an entry under `## [Unreleased]` in [`CHANGELOG.md`](CHANGELOG.md). +- Prefer concise entry wording and include the current PR reference when known. diff --git a/CHANGELOG.md b/CHANGELOG.md index b1e120e..69cf99c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add changelog history for releases v1.0.0-v1.3.0 during dev-tools asset synchronization. (#3) - Sync latest Fast Forward dev-tools managed assets (workflow templates, governance metadata, agents, and skills) into this repository. (#3) +- Add repository AGENTS.md for agent task orchestration and local onboarding flow. + +### Changed + +- Prefer FrameworkServiceProvider::class in framework README/docs bootstrap snippets instead of instantiating provider objects. ## [1.3.0] - 2026-03-29 diff --git a/README.md b/README.md index 93a4de8..3d19e28 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,12 @@ # Fast Forward Framework +![Fast Forward mascot](docs/_static/mascot.png) + [![PHP Version](https://img.shields.io/badge/php-^8.3-777BB4?logo=php&logoColor=white)](https://www.php.net/releases/) +[![Composer Package](https://img.shields.io/badge/composer-fast--forward%2Fframework-F28D1A.svg?logo=composer&logoColor=white)](https://packagist.org/packages/fast-forward/framework) [![Tests](https://img.shields.io/github/actions/workflow/status/php-fast-forward/framework/tests.yml?logo=githubactions&logoColor=white&label=tests&color=22C55E)](https://github.com/php-fast-forward/framework/actions/workflows/tests.yml) [![Coverage](https://img.shields.io/badge/coverage-phpunit-4ADE80?logo=php&logoColor=white)](https://php-fast-forward.github.io/framework/coverage/index.html) +[![Metrics](https://img.shields.io/badge/metrics-phpmetrics-8B5CF6?logo=php&logoColor=white)](https://php-fast-forward.github.io/framework/metrics/index.html) [![Docs](https://img.shields.io/github/deployments/php-fast-forward/framework/github-pages?logo=readthedocs&logoColor=white&label=docs&labelColor=1E293B&color=38BDF8&style=flat)](https://php-fast-forward.github.io/framework/index.html) [![License](https://img.shields.io/github/license/php-fast-forward/framework?color=64748B)](LICENSE) [![GitHub Sponsors](https://img.shields.io/github/sponsors/php-fast-forward?logo=githubsponsors&logoColor=white&color=EC4899)](https://github.com/sponsors/php-fast-forward) @@ -14,20 +18,27 @@ [![PSR-18](https://img.shields.io/badge/PSR--18-http--client-777BB4?logo=php&logoColor=white)](https://www.php-fig.org/psr/psr-18/) [![PSR-20](https://img.shields.io/badge/PSR--20-clock-777BB4?logo=php&logoColor=white)](https://www.php-fig.org/psr/psr-20/) -**Fast Forward Framework** is a lightweight and fast PHP framework designed for building modern web -and event-driven applications. -This package serves as an **aggregate metapackage**, bundling all core components of the Fast Forward ecosystem for easier installation and management. +**Fast Forward Framework** is a lightweight aggregate metapackage that installs the core +Fast Forward stack through a single dependency and a single service-provider bootstrap. + +## โœจ Features ---- +- ๐ŸŽฏ One-command installation of core Fast Forward packages +- ๐Ÿงฉ Aggregates HTTP and event-dispatcher infrastructure with container integration +- ๐Ÿš€ Compatible with modern PHP standards (PSR-7, PSR-11, PSR-14, PSR-17, PSR-18, PSR-20) +- ๐Ÿงฑ Built as the foundation layer for Fast Forward applications -## Features +## ๐Ÿ“ฆ Installation -- ๐Ÿš€ **Modern PHP 8.3+ syntax** -- ๐Ÿ“ฆ Simplifies installation of all core packages in one step -- ๐Ÿ”Œ Registers the Fast Forward HTTP and event-dispatcher stacks through a single framework provider -- ๐Ÿงฑ Provides a solid foundation for building scalable PHP applications +```bash +composer require fast-forward/framework +``` -## Usage +Requirements: + +- PHP 8.3 or higher + +## ๐Ÿ› ๏ธ Usage ```php get(ResponseFactoryInterface::class); $dispatcher = $container->get(EventDispatcherInterface::class); $clock = $container->get(ClockInterface::class); ``` ---- +## ๐Ÿ”Œ Package Surface -## Installation +- `FastForward\Framework\ServiceProvider\FrameworkServiceProvider` +- Core HTTP and event-dispatcher service provider orchestration +- Shared configuration and lifecycle defaults for core packages in the ecosystem -Install via [Composer](https://getcomposer.org): - -```bash -composer require fast-forward/framework -``` +## ๐Ÿ“š Documentation -This command will automatically pull in all the required dependencies of the framework. +- [GitHub Repository](https://github.com/php-fast-forward/framework) +- [Packagist](https://packagist.org/packages/fast-forward/framework) +- [Issue Tracker](https://github.com/php-fast-forward/framework/issues) +- [Coverage](https://php-fast-forward.github.io/framework/coverage/index.html) +- [Metrics](https://php-fast-forward.github.io/framework/metrics/index.html) +- [Docs](https://php-fast-forward.github.io/framework/index.html) ---- +## ๐Ÿงช Quality and Observability -## Requirements +- Test suite: [GitHub Actions](https://github.com/php-fast-forward/framework/actions/workflows/tests.yml) +- Coverage: `coverage/index.html` +- Testdox: `coverage/testdox.html` +- Metrics: `metrics/index.html` -- PHP 8.3 or higher +## ๐Ÿค Contributing ---- +Contributions, issues, and feature requests are welcome. Keep changes focused and aligned +with the repository's existing documentation and contribution flow. -## License +## ๐Ÿ›ก License Fast Forward Framework is licensed under the [MIT license](LICENSE). ---- - -## Author +## ๐Ÿ‘ค Author -Developed with โค๏ธ by **Felipe Sayรฃo Lobato Abreu** -๐Ÿ“ง [github@mentordosnerds.com](mailto:github@mentordosnerds.com) +Developed by **Felipe Sayรฃo Lobato Abreu** +- ๐Ÿ“ง [github@mentordosnerds.com](mailto:github@mentordosnerds.com) diff --git a/docs/_static/mascot.png b/docs/_static/mascot.png new file mode 100644 index 0000000..35304ab Binary files /dev/null and b/docs/_static/mascot.png differ diff --git a/docs/advanced/customization.rst b/docs/advanced/customization.rst index 1d92439..cc57c0e 100644 --- a/docs/advanced/customization.rst +++ b/docs/advanced/customization.rst @@ -13,11 +13,12 @@ Register your application provider after the framework provider: use App\ServiceProvider\AppServiceProvider; use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; + use function FastForward\Container\container; $container = container( - new FrameworkServiceProvider(), - new AppServiceProvider(), + FrameworkServiceProvider::class, + AppServiceProvider::class, ); This keeps the framework defaults while giving your application room to add domain-specific @@ -86,6 +87,7 @@ You can extend the framework's event behavior without replacing the framework pr use FastForward\Container\ContainerInterface; use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; use Psr\EventDispatcher\ListenerProviderInterface; + use function FastForward\Container\container; $config = new ArrayConfig([ diff --git a/docs/advanced/integration.rst b/docs/advanced/integration.rst index fbbee24..6b0fed1 100644 --- a/docs/advanced/integration.rst +++ b/docs/advanced/integration.rst @@ -12,9 +12,10 @@ The recommended integration path is the ``container()`` helper from ``fast-forwa .. code-block:: php use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; + use function FastForward\Container\container; - $container = container(new FrameworkServiceProvider()); + $container = container(FrameworkServiceProvider::class); Integrate through configuration ------------------------------- @@ -29,6 +30,7 @@ container helper: use FastForward\Container\ContainerInterface; use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; use Psr\EventDispatcher\ListenerProviderInterface; + use function FastForward\Container\container; $config = new ArrayConfig([ diff --git a/docs/api/service-provider.rst b/docs/api/service-provider.rst index abbb122..4dfc1ab 100644 --- a/docs/api/service-provider.rst +++ b/docs/api/service-provider.rst @@ -18,9 +18,10 @@ Usage .. code-block:: php use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; + use function FastForward\Container\container; - $container = container(new FrameworkServiceProvider()); + $container = container(FrameworkServiceProvider::class); What it aggregates ------------------ diff --git a/docs/faq.rst b/docs/faq.rst index 91b5cfa..2a13c5f 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -49,9 +49,10 @@ Use the helper function from ``fast-forward/container``: .. code-block:: php use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; + use function FastForward\Container\container; - $container = container(new FrameworkServiceProvider()); + $container = container(FrameworkServiceProvider::class); How do I access the current request? ------------------------------------ diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst index a190f96..a5c7b39 100644 --- a/docs/getting-started/index.rst +++ b/docs/getting-started/index.rst @@ -14,3 +14,6 @@ If you are evaluating the package for the first time, read the pages in this ord installation quickstart + +Learn more in the main links section for dependency and report references before you +start production wiring. diff --git a/docs/getting-started/quickstart.rst b/docs/getting-started/quickstart.rst index 035426d..c8abf54 100644 --- a/docs/getting-started/quickstart.rst +++ b/docs/getting-started/quickstart.rst @@ -15,14 +15,15 @@ Minimal bootstrap use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; use FastForward\Http\Message\Factory\ResponseFactoryInterface; - use function FastForward\Container\container; use Psr\EventDispatcher\EventDispatcherInterface; use Psr\Http\Client\ClientInterface; use Psr\Http\Message\ServerRequestInterface; + use function FastForward\Container\container; + require_once __DIR__ . '/../vendor/autoload.php'; - $container = container(new FrameworkServiceProvider()); + $container = container(FrameworkServiceProvider::class); $request = $container->get(ServerRequestInterface::class); $responseFactory = $container->get(ResponseFactoryInterface::class); @@ -55,9 +56,10 @@ function: .. code-block:: php use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; + use function FastForward\Container\container; - $container = container(new FrameworkServiceProvider()); + $container = container(FrameworkServiceProvider::class); This is the preferred documented bootstrap for this repository because the installed container package exposes the helper function and ``ContainerInterface``, not a ``Container`` class. diff --git a/docs/index.rst b/docs/index.rst index e8a83ae..30a5c00 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,16 +4,33 @@ Documentation ============= -**Fast Forward Framework** is the metapackage entry point for the Fast Forward ecosystem. -It installs the core libraries you are most likely to need first and exposes a single -``FrameworkServiceProvider`` that bootstraps the HTTP and event-dispatcher stacks inside a -Fast Forward container. +.. container:: row align-items-center gy-4 my-4 -This package is especially useful when you want one Composer dependency that gives you: + .. container:: col-lg-7 -- a PSR-11 friendly container workflow -- the Fast Forward HTTP and event-dispatcher service-provider stacks -- access to supporting packages such as configuration, deferred callbacks, iterators, and process tools + **Fast Forward Framework** is the metapackage entry point for the Fast Forward ecosystem. + It installs the core libraries you are most likely to need first and exposes a single + ``FrameworkServiceProvider`` that bootstraps the HTTP and event-dispatcher stacks inside a + Fast Forward container. + + If you are new to the package, start with + :doc:`getting-started/installation` and :doc:`getting-started/quickstart`. + + If you are maintaining a consumer application, read + :doc:`advanced/integration`, :doc:`usage/index`, and + :doc:`links/dependencies`. + + This package is especially useful when you want one Composer dependency that gives you: + + - a PSR-11 friendly container workflow + - the Fast Forward HTTP and event-dispatcher service-provider stacks + - access to supporting packages such as configuration, deferred callbacks, iterators, and process tools + + .. container:: col-lg-5 text-center + + .. image:: _static/mascot.png + :alt: Fast Forward Framework mascot + :class: img-fluid w-100 rounded-4 shadow-sm border border-light-subtle bg-body-tertiary p-2 What this package does ---------------------- @@ -41,6 +58,7 @@ Useful Links - `Packagist `_ - `Issue Tracker `_ - `Coverage Report `_ +- `Metrics Report `_ - `Testdox Report `_ .. toctree:: diff --git a/docs/links/index.rst b/docs/links/index.rst index afc4487..17f4472 100644 --- a/docs/links/index.rst +++ b/docs/links/index.rst @@ -6,6 +6,7 @@ This section centralizes external references, dependency docs, and quality repor - `GitHub Repository `_ - `Packagist `_ - `Coverage Report `_ +- `Metrics Report `_ - `Testdox Report `_ - `API Reference (README) `_ diff --git a/docs/usage/event-dispatching.rst b/docs/usage/event-dispatching.rst index 6405c74..b0a2b2c 100644 --- a/docs/usage/event-dispatching.rst +++ b/docs/usage/event-dispatching.rst @@ -34,6 +34,7 @@ The most practical way to add listeners is to provide them under the use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; use Psr\EventDispatcher\EventDispatcherInterface; use Psr\EventDispatcher\ListenerProviderInterface; + use function FastForward\Container\container; final readonly class UserRegistered @@ -77,6 +78,7 @@ If your project uses Symfony subscribers or ``#[AsEventListener]`` attributes, a use Psr\EventDispatcher\ListenerProviderInterface; use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Symfony\Contracts\EventDispatcher\EventDispatcherInterface; + use function FastForward\Container\container; final readonly class PaymentReceived diff --git a/docs/usage/use-cases.rst b/docs/usage/use-cases.rst index cf48645..303b571 100644 --- a/docs/usage/use-cases.rst +++ b/docs/usage/use-cases.rst @@ -13,9 +13,10 @@ Bootstrap an application container .. code-block:: php use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; + use function FastForward\Container\container; - $container = container(new FrameworkServiceProvider()); + $container = container(FrameworkServiceProvider::class); This is the default starting point for web applications and small prototypes. @@ -29,6 +30,7 @@ Build an event-driven application workflow use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; use Psr\EventDispatcher\EventDispatcherInterface; use Psr\EventDispatcher\ListenerProviderInterface; + use function FastForward\Container\container; final readonly class UserRegistered @@ -68,11 +70,12 @@ Register your application services next to the framework use App\ServiceProvider\AppServiceProvider; use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; + use function FastForward\Container\container; $container = container( - new FrameworkServiceProvider(), - new AppServiceProvider(), + FrameworkServiceProvider::class, + AppServiceProvider::class, ); The later provider can add new services or override existing ones when it uses the same @@ -87,6 +90,7 @@ Drive container setup from configuration use FastForward\Config\ArrayConfig; use FastForward\Container\ContainerInterface; use FastForward\Framework\ServiceProvider\FrameworkServiceProvider; + use function FastForward\Container\container; $config = new ArrayConfig([