Add documentation for HTTP service providers and usage examples

- Introduced `HttpClientServiceProvider` and `HttpMessageFactoryServiceProvider` documentation.
- Updated API reference to include new service providers.
- Enhanced `HttpServiceProvider` documentation with usage examples and purpose.
- Added compatibility and dependencies documentation.
- Expanded FAQ section to clarify package usage and standards.
- Created detailed guides for getting services, handling server requests, and using the HTTP client.
- Added use cases demonstrating practical applications of the package.
- Included coverage and links documentation for better navigation and understanding.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

README.md

@@ -1,50 +1,80 @@
-# Fast Forward Framework
+# Fast Forward HTTP
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![PHP Version](https://img.shields.io/badge/php-^8.2-blue.svg)](https://www.php.net/releases/)
+[![PHP Version](https://img.shields.io/badge/php-^8.3-blue.svg)](https://www.php.net/releases/)
 
-**Fast Forward** is a lightweight and fast PHP framework designed for building modern web applications.  
-This package serves as an **aggregate metapackage**, bundling all http components of the Fast Forward ecosystem for easier installation and management.
+Fast Forward HTTP is the aggregate HTTP package of the Fast Forward ecosystem.
 
----
+It is designed for developers who want a practical starting point for HTTP work without wiring each
+piece manually. Install one package, register one provider, and you get the default Fast Forward
+HTTP stack in your container.
 
-## Features
+## What You Get
 
-- 🚀 **Modern PHP 8.3+ syntax**
-- ⚙️ Aggregates key components:
-  - [`fast-forward/http-message`](https://github.com/php-fast-forward/http-message) – PSR-7 compatible HTTP message implementation
-  - [`fast-forward/http-factory`](https://github.com/php-fast-forward/http-factory) – HTTP factory for creating PSR-7 request and response objects
-  - [`fast-forward/http-client`](https://github.com/php-fast-forward/http-client) – PSR-18 compatible HTTP client for making requests
-- 📦 Simplifies installation of all http packages in one step
-- 🧱 Provides a solid foundation for building scalable Http PHP applications
-
----
+- PSR-17 factories for requests, responses, server requests, streams, uploaded files, and URIs
+- A PSR-18 HTTP client backed by Symfony HttpClient
+- A `ServerRequestInterface` created from PHP globals
+- Fast Forward convenience factories for JSON, HTML, text, redirect, empty responses, and payload streams
+- One aggregate `HttpServiceProvider` that wires the stack together
 
 ## Installation
 
-Install via [Composer](https://getcomposer.org):
-
 ```bash
 composer require fast-forward/http
 ```
 
-This command will automatically pull in all the required dependencies of the framework.
+## Quickstart
 
----
+```php
+<?php
 
-## Requirements
+declare(strict_types=1);
 
-- PHP 8.2 or higher
+use FastForward\Http\Message\Factory\ResponseFactoryInterface;
+use FastForward\Http\ServiceProvider\HttpServiceProvider;
+use function FastForward\Container\container;
 
----
+$container = container(new HttpServiceProvider());
 
-## License
+$responseFactory = $container->get(ResponseFactoryInterface::class);
+
+$response = $responseFactory->createResponseFromPayload([
+    'message' => 'Hello, Fast Forward HTTP!',
+    'ok' => true,
+]);
+
+echo $response->getHeaderLine('Content-Type');
+// application/json; charset=utf-8
+```
 
-Fast Forward Framework is licensed under the [MIT license](LICENSE).
+## Main Services
 
----
+| Identifier | Default concrete service | Purpose |
+| --- | --- | --- |
+| `Psr\Http\Message\RequestFactoryInterface` | `Nyholm\Psr7\Factory\Psr17Factory` | Create outbound requests |
+| `Psr\Http\Message\ResponseFactoryInterface` | `Nyholm\Psr7\Factory\Psr17Factory` | Create plain PSR-17 responses |
+| `FastForward\Http\Message\Factory\ResponseFactoryInterface` | `FastForward\Http\Message\Factory\ResponseFactory` | Create JSON, HTML, text, redirect, and empty responses |
+| `FastForward\Http\Message\Factory\StreamFactoryInterface` | `FastForward\Http\Message\Factory\StreamFactory` | Create payload-aware JSON streams |
+| `Psr\Http\Message\ServerRequestInterface` | `ServerRequestCreator::fromGlobals()` result | Access the current incoming request |
+| `Psr\Http\Client\ClientInterface` | `Symfony\Component\HttpClient\Psr18Client` | Send outbound HTTP requests |
 
-## Author
+## Documentation
+
+See the documentation sources in [`docs/`](docs/) for:
+
+- installation and quickstart
+- retrieving services from the container
+- responses, streams, and server requests
+- advanced customization and aliasing
+- aggregated services and compatibility notes
+
+## Related Packages
+
+- [`fast-forward/container`](https://github.com/php-fast-forward/container)
+- [`fast-forward/http-client`](https://github.com/php-fast-forward/http-client)
+- [`fast-forward/http-factory`](https://github.com/php-fast-forward/http-factory)
+- [`fast-forward/http-message`](https://github.com/php-fast-forward/http-message)
+
+## License
 
-Developed with ❤️ by **Felipe Sayão Lobato Abreu**  
-📧 [github@mentordosnerds.com](mailto:github@mentordosnerds.com)
+Fast Forward HTTP is licensed under the [MIT license](LICENSE).

composer.json

@@ -40,7 +40,8 @@
             "ergebnis/composer-normalize": true,
             "fast-forward/dev-tools": true,
             "phpdocumentor/shim": true,
-            "phpro/grumphp": true
+            "phpro/grumphp": true,
+            "pyrech/composer-changelogs": true
         },
         "platform": {
             "php": "8.3.0"

docs/advanced/aliases.rst

@@ -1,4 +1,66 @@
 Aliases
 =======
 
-The package registers standard PSR interfaces as service aliases in the container, allowing you to type-hint against PSR-7, PSR-17, and PSR-18 interfaces and retrieve the correct implementation automatically.
+The default setup relies heavily on aliases so you can request standard PSR interfaces and still
+receive a concrete implementation automatically.
+
+Alias Map
+---------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 38 32 30
+
+   * - Requested identifier
+     - Resolves to
+     - Why this alias exists
+   * - ``Psr\Http\Message\RequestFactoryInterface``
+     - ``Nyholm\Psr7\Factory\Psr17Factory``
+     - One factory can create PSR-7 request objects
+   * - ``Psr\Http\Message\ResponseFactoryInterface``
+     - ``Nyholm\Psr7\Factory\Psr17Factory``
+     - One factory can create plain PSR-17 responses
+   * - ``Psr\Http\Message\ServerRequestFactoryInterface``
+     - ``Nyholm\Psr7\Factory\Psr17Factory``
+     - One factory can create server requests manually
+   * - ``Psr\Http\Message\StreamFactoryInterface``
+     - ``Nyholm\Psr7\Factory\Psr17Factory``
+     - One factory can create plain PSR-17 streams
+   * - ``Psr\Http\Message\UploadedFileFactoryInterface``
+     - ``Nyholm\Psr7\Factory\Psr17Factory``
+     - One factory can create uploaded files
+   * - ``Psr\Http\Message\UriFactoryInterface``
+     - ``Nyholm\Psr7\Factory\Psr17Factory``
+     - One factory can create URIs
+   * - ``Nyholm\Psr7Server\ServerRequestCreatorInterface``
+     - ``Nyholm\Psr7Server\ServerRequestCreator``
+     - You code against the interface instead of the concrete class
+   * - ``FastForward\Http\Message\Factory\ResponseFactoryInterface``
+     - ``FastForward\Http\Message\Factory\ResponseFactory``
+     - Adds convenience methods for common response types
+   * - ``FastForward\Http\Message\Factory\StreamFactoryInterface``
+     - ``FastForward\Http\Message\Factory\StreamFactory``
+     - Adds payload-aware stream creation
+
+What This Means In Practice
+---------------------------
+
+- All PSR-17 factory interfaces resolve to the same underlying ``Psr17Factory`` instance in the
+  default container setup.
+- You can type-hint the standard interfaces in your own services and stay decoupled from concrete
+  implementations.
+- You can request the Fast Forward convenience interfaces when you want extra helper methods that
+  do not exist in the PSR interfaces.
+
+Provider Instances Are Also Registered
+--------------------------------------
+
+Because ``HttpServiceProvider`` extends ``AggregateServiceProvider``, the following provider
+instances are also available by class name:
+
+- ``FastForward\Http\ServiceProvider\HttpServiceProvider``
+- ``FastForward\Http\Message\Factory\ServiceProvider\HttpMessageFactoryServiceProvider``
+- ``FastForward\Http\Client\ServiceProvider\HttpClientServiceProvider``
+
+This is mostly useful for inspection, debugging, or advanced composition, not for day-to-day
+application code.

docs/advanced/customization.rst

@@ -0,0 +1,89 @@
+Customization
+=============
+
+The default configuration is intentionally simple, but you can replace or narrow parts of the stack
+when your application needs different defaults.
+
+Use Only The Underlying Provider You Need
+-----------------------------------------
+
+If you only need factories, you can register the message factory provider directly instead of the
+full aggregate provider:
+
+.. code-block:: php
+
+   <?php
+
+   declare(strict_types=1);
+
+   use FastForward\Http\Message\Factory\ServiceProvider\HttpMessageFactoryServiceProvider;
+   use function FastForward\Container\container;
+
+   $container = container(new HttpMessageFactoryServiceProvider());
+
+If you need only the client provider, register ``HttpClientServiceProvider`` directly.
+
+Override A Service With Your Own Provider
+-----------------------------------------
+
+The easiest way to replace one of the default services is to register your own provider *before*
+``HttpServiceProvider``. The aggregate container resolves identifiers in registration order, so the
+first matching provider wins.
+
+.. code-block:: php
+
+   <?php
+
+   declare(strict_types=1);
+
+   use FastForward\Http\ServiceProvider\HttpServiceProvider;
+   use Interop\Container\ServiceProviderInterface;
+   use Psr\Container\ContainerInterface;
+   use Psr\Http\Client\ClientInterface;
+   use Psr\Http\Message\ResponseFactoryInterface;
+   use Psr\Http\Message\StreamFactoryInterface;
+   use Symfony\Component\HttpClient\HttpClient;
+   use Symfony\Component\HttpClient\Psr18Client;
+   use function FastForward\Container\container;
+
+   final class CustomHttpClientServiceProvider implements ServiceProviderInterface
+   {
+       public function getFactories(): array
+       {
+           return [
+               HttpClient::class => static fn() => HttpClient::create([
+                   'timeout' => 5.0,
+               ]),
+               ClientInterface::class => static fn(ContainerInterface $container) => new Psr18Client(
+                   $container->get(HttpClient::class),
+                   $container->get(ResponseFactoryInterface::class),
+                   $container->get(StreamFactoryInterface::class),
+               ),
+           ];
+       }
+
+       public function getExtensions(): array
+       {
+           return [];
+       }
+   }
+
+   $container = container(
+       new CustomHttpClientServiceProvider(),
+       new HttpServiceProvider(),
+   );
+
+What You Can Replace Safely
+---------------------------
+
+- ``Psr\Http\Client\ClientInterface`` if you want a different PSR-18 client
+- ``Symfony\Component\HttpClient\HttpClient`` if you want different Symfony client defaults
+- any PSR-17 factory interface if you need different object creation rules
+- the Fast Forward convenience factory interfaces if you want different helper behavior
+
+When Not To Customize
+---------------------
+
+Avoid replacing services just to reach the defaults. If the default behavior already matches your
+needs, prefer the stock provider because it keeps application bootstrap code shorter and easier to
+understand.

docs/advanced/index.rst

@@ -1,10 +1,13 @@
 Advanced
 ========
 
-This section covers advanced integration and extension topics for FastForward HTTP.
+This section explains how the package integrates with the Fast Forward container, how aliases work,
+and how to replace or narrow parts of the default HTTP stack when you need more control.
 
 .. toctree::
    :maxdepth: 1
 
    integration
    aliases
+   customization
+   troubleshooting

docs/advanced/integration.rst

@@ -1,6 +1,77 @@
 Integration
 ===========
 
-FastForward HTTP is designed to work seamlessly with the FastForward Container and other FastForward packages. By aggregating service providers, it ensures all HTTP-related services are available in your dependency injection container.
+Fast Forward HTTP is designed to fit naturally into the Fast Forward container story, but the
+package remains useful anywhere service providers and PSR-11 containers are part of the
+application architecture.
 
-You can extend or override services by providing your own service providers to the container alongside or instead of the default ones.
+Registering With The ``container()`` Helper
+-------------------------------------------
+
+.. code-block:: php
+
+   <?php
+
+   declare(strict_types=1);
+
+   use FastForward\Http\ServiceProvider\HttpServiceProvider;
+   use function FastForward\Container\container;
+
+   $container = container(new HttpServiceProvider());
+
+This is the most direct and beginner-friendly setup.
+
+Registering Through Configuration
+---------------------------------
+
+The Fast Forward container helper can also discover service providers from configuration.
+
+.. code-block:: php
+
+   <?php
+
+   declare(strict_types=1);
+
+   use FastForward\Config\ArrayConfig;
+   use FastForward\Container\ContainerInterface;
+   use FastForward\Http\ServiceProvider\HttpServiceProvider;
+   use function FastForward\Container\container;
+
+   $config = new ArrayConfig([
+       ContainerInterface::class => [
+           HttpServiceProvider::class,
+       ],
+   ]);
+
+   $container = container($config);
+
+This is useful when your application already centralizes provider registration in configuration.
+
+Working Alongside Other Providers
+---------------------------------
+
+You can compose ``HttpServiceProvider`` with your own service providers or with providers from
+other Fast Forward packages.
+
+.. code-block:: php
+
+   <?php
+
+   declare(strict_types=1);
+
+   use App\ServiceProvider\ApplicationServiceProvider;
+   use FastForward\Http\ServiceProvider\HttpServiceProvider;
+   use function FastForward\Container\container;
+
+   $container = container(
+       new ApplicationServiceProvider(),
+       new HttpServiceProvider(),
+   );
+
+General Integration Guidance
+----------------------------
+
+- Use ``HttpServiceProvider`` when you want the full HTTP stack in one place.
+- Use the underlying providers directly when you only want factories or only want the client.
+- Keep your own services typed against PSR interfaces whenever possible.
+- Move to :doc:`customization` when you need to override the default implementations.