You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Enhance documentation for FastForward HTTP Factory
- Added detailed descriptions and examples for StreamFactoryInterface and StreamFactory.
- Introduced a new compatibility section outlining package metadata and compatibility expectations.
- Expanded FAQ section to clarify differences between PSR and Fast Forward factories, container usage, and service registration.
- Updated getting started guide with clearer installation instructions and usage examples.
- Improved quickstart guide to demonstrate common workflows for new users.
- Added use cases for various response types including JSON, HTML, text, and redirect responses.
- Clarified stream usage with examples for creating JSON streams and handling payloads.
- Documented dependencies and their roles in the package architecture.
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
A [PSR-11](https://www.php-fig.org/psr/psr-11/) compatible service provider that registers a fully functional set of [PSR-17](https://www.php-fig.org/psr/psr-17/) and [PSR-7](https://www.php-fig.org/psr/psr-7/) HTTP factories using[Nyholm PSR-7](https://github.com/Nyholm/psr7) and [Nyholm ServerRequestCreator](https://github.com/Nyholm/psr7-server).
7
+
A Fast Forward service provider and helper-factory package for [PSR-17](https://www.php-fig.org/psr/psr-17/) and [PSR-7](https://www.php-fig.org/psr/psr-7/) HTTP objects, built on top of[Nyholm PSR-7](https://github.com/Nyholm/psr7) and [Nyholm ServerRequestCreator](https://github.com/Nyholm/psr7-server).
8
8
9
9
Designed to work out of the box with the [`php-fast-forward/container`](https://github.com/php-fast-forward/container) autowiring system.
10
10
@@ -16,19 +16,19 @@ Designed to work out of the box with the [`php-fast-forward/container`](https://
16
16
composer require fast-forward/http-factory
17
17
```
18
18
19
-
## ✅ Features
20
-
- Registers the Psr17Factory as the base implementation for all PSR-17 interfaces
21
-
- Registers the ServerRequestCreator using InvokableFactory
22
-
- Provides ServerRequestInterface::class using fromGlobals() via MethodFactory
23
-
- Aliases:
24
-
- RequestFactoryInterface
25
-
- ResponseFactoryInterface
26
-
- ServerRequestFactoryInterface
27
-
- StreamFactoryInterface
28
-
- UploadedFileFactoryInterface
29
-
- UriFactoryInterface
19
+
## Features
20
+
- Reuses one `Nyholm\Psr7\Factory\Psr17Factory` instance for the standard PSR-17 interfaces
21
+
- Registers `Nyholm\Psr7Server\ServerRequestCreator` and exposes `ServerRequestInterface::class` via `fromGlobals()`
22
+
- Exposes `FastForward\Http\Message\Factory\ResponseFactoryInterface` for HTML, JSON, text, redirect, and no-content helpers
23
+
- Exposes `FastForward\Http\Message\Factory\StreamFactoryInterface` for payload-aware JSON stream helpers
24
+
- Keeps returned objects PSR-7 compatible
30
25
31
-
## 🛠️ Usage
26
+
## Usage
27
+
28
+
There are two similarly named response and stream factory interfaces:
29
+
30
+
-`Psr\Http\Message\ResponseFactoryInterface` and `Psr\Http\Message\StreamFactoryInterface` for plain PSR-17 behavior
31
+
-`FastForward\Http\Message\Factory\ResponseFactoryInterface` and `FastForward\Http\Message\Factory\StreamFactoryInterface` for Fast Forward helper methods
All PSR-17 aliases are resolved to a single instance of `Nyholm\Psr7\Factory\Psr17Factory`, ensuring consistency and resource efficiency.
4
+
The service provider uses aliases so that multiple interfaces can reuse the same underlying object.
5
+
This keeps the container setup compact and avoids duplicate factory instances.
5
6
6
-
Details:
7
-
--------
7
+
PSR-17 Alias Group
8
+
------------------
8
9
9
-
- **Singleton Pattern**: The same instance is reused for all PSR-17 interfaces, reducing memory usage and initialization overhead.
10
-
- **Custom Implementations**: You can override any alias by registering your own implementation in the container.
11
-
- **ServerRequestInterface**: Resolved using the static `fromGlobals()` method from `Nyholm\Psr7Server\ServerRequestCreator`, providing easy access to the current HTTP request.
12
-
- **Extensibility**: The provider is designed to be extensible, allowing you to add or replace factories as needed for your application.
10
+
All of the following service ids resolve to the same ``Nyholm\Psr7\Factory\Psr17Factory`` instance:
- ``FastForward\Http\Message\Factory\ResponseFactoryInterface`` resolves to ``FastForward\Http\Message\Factory\ResponseFactory``
25
+
- ``FastForward\Http\Message\Factory\StreamFactoryInterface`` resolves to ``FastForward\Http\Message\Factory\StreamFactory``
26
+
- ``Nyholm\Psr7Server\ServerRequestCreatorInterface`` resolves to ``Nyholm\Psr7Server\ServerRequestCreator``
27
+
28
+
Why This Matters
29
+
----------------
30
+
31
+
The alias setup creates a clean separation:
32
+
33
+
- PSR-17 interfaces give you low-level factory behavior
34
+
- Fast Forward interfaces give you convenience methods for common application responses
35
+
36
+
Overriding A Service
37
+
--------------------
38
+
39
+
If you want different behavior, replace the alias target in your container configuration with your own implementation.
40
+
Typical examples include:
41
+
42
+
- a custom response factory that always adds application-specific headers
43
+
- a custom stream factory that uses another payload encoding strategy
44
+
- a different request bootstrap process in long-running servers
45
+
46
+
Before overriding, check your container's precedence rules so you know whether your registration replaces or is replaced by the service-provider definition.
FastForward HTTP Factory is designed to work seamlessly with any PSR-11 compatible container, such as `fast-forward/container` or other popular PHP containers.
4
+
Preferred Integration: ``fast-forward/container``
5
+
-------------------------------------------------
5
6
6
-
Key Points:
7
-
-----------
7
+
The service provider in this package is designed first for ``fast-forward/container``.
8
+
That is the most direct way to consume the aliases and factory definitions provided by ``HttpMessageFactoryServiceProvider``.
8
9
9
-
- **Automatic Registration**: All required factories and aliases are registered for immediate use.
10
-
- **Configuration Example**:
10
+
.. code-block:: php
11
11
12
-
.. code-block:: php
12
+
use FastForward\Config\ArrayConfig;
13
+
use FastForward\Container\ContainerInterface;
14
+
use FastForward\Container\container;
15
+
use FastForward\Http\Message\Factory\ServiceProvider\HttpMessageFactoryServiceProvider;
13
16
14
-
use FastForward\Container\container;
15
-
use FastForward\Config\ArrayConfig;
16
-
use FastForward\Container\ContainerInterface;
17
-
use FastForward\Http\Message\Factory\ServiceProvider\HttpMessageFactoryServiceProvider;
17
+
$config = new ArrayConfig([
18
+
ContainerInterface::class => [
19
+
HttpMessageFactoryServiceProvider::class,
20
+
],
21
+
]);
18
22
19
-
$config = new ArrayConfig([
20
-
ContainerInterface::class => [
21
-
HttpMessageFactoryServiceProvider::class,
22
-
],
23
-
]);
23
+
$container = container($config);
24
24
25
-
$container = container($config);
25
+
Important Clarification
26
+
----------------------
26
27
27
-
- **Custom Containers**: You can use the service provider with any container that implements PSR-11.
28
-
- **Best Practices**: Register the provider as early as possible in your configuration to ensure all HTTP factories are available for dependency injection.
28
+
The services exposed by this package are PSR-7 and PSR-17 compatible once resolved, but the service provider itself uses Fast Forward container helper classes such as:
29
+
30
+
- ``AliasFactory``
31
+
- ``InvokableFactory``
32
+
- ``MethodFactory``
33
+
34
+
Because of that, you should not assume that any generic PSR-11 container can consume this provider directly.
35
+
If your container does not support Fast Forward service-provider definitions, register equivalent services manually.
36
+
37
+
Manual Wiring Example
38
+
---------------------
39
+
40
+
.. code-block:: php
41
+
42
+
use FastForward\Http\Message\Factory\ResponseFactory;
43
+
use FastForward\Http\Message\Factory\StreamFactory;
44
+
use Nyholm\Psr7\Factory\Psr17Factory;
45
+
use Nyholm\Psr7Server\ServerRequestCreator;
46
+
47
+
$psr17Factory = new Psr17Factory();
48
+
49
+
$responseFactory = new ResponseFactory($psr17Factory);
50
+
$streamFactory = new StreamFactory($psr17Factory);
You resolved the PSR-17 interface, not the Fast Forward convenience interface.
8
+
Use ``FastForward\Http\Message\Factory\ResponseFactoryInterface`` when you need methods such as ``createResponseFromPayload()`` or ``createResponseRedirect()``.
9
+
10
+
I resolved ``Psr\\Http\\Message\\StreamFactoryInterface`` but ``createStreamFromPayload()`` is missing
Copy file name to clipboardExpand all lines: docs/api/index.rst
+18-13Lines changed: 18 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,26 +1,31 @@
1
1
API Reference
2
2
=============
3
3
4
-
Main Interfaces and Classes
5
-
--------------------------
4
+
This package is intentionally small, so the API surface is easy to learn.
5
+
There are five main pieces to understand:
6
6
7
-
.. contents:: Table of Contents
8
-
:local:
9
-
:depth: 2
7
+
.. list-table::
8
+
:header-rows: 1
10
9
11
-
ResponseFactoryInterface
12
-
-----------------------
13
-
14
-
API Reference
15
-
=============
10
+
* - Type
11
+
- Role
12
+
* - ``HttpMessageFactoryServiceProvider``
13
+
- Registers aliases and concrete services in the container
14
+
* - ``ResponseFactoryInterface``
15
+
- Defines the response helper methods on top of PSR-17
16
+
* - ``ResponseFactory``
17
+
- Concrete decorator that implements the response helper methods
18
+
* - ``StreamFactoryInterface``
19
+
- Defines the payload-stream helper method on top of PSR-17
20
+
* - ``StreamFactory``
21
+
- Concrete decorator that implements the stream helper methods
16
22
17
23
.. toctree::
18
24
:maxdepth:2
19
25
:caption:API Reference
20
26
21
27
response-factory-interface
28
+
response-factory
22
29
stream-factory-interface
30
+
stream-factory
23
31
service-provider
24
-
25
-
This section provides detailed documentation for the main interfaces and classes of FastForward HTTP Factory. Select a topic above for in-depth reference and examples.
26
-
- **createResponseFromPayload**: Creates a JSON response from an associative array.
0 commit comments