1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* This file is part of php-fast-forward/http-factory.
7	*
8	* This source file is subject to the license bundled
9	* with this source code in the file LICENSE.
10	*
11	* @copyright Copyright (c) 2025-2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12	* @license   https://opensource.org/licenses/MIT MIT License
13	*
14	* @see       https://github.com/php-fast-forward/http-factory
15	* @see       https://github.com/php-fast-forward
16	* @see       https://datatracker.ietf.org/doc/html/rfc2119
17	*/
18
19	namespace FastForward\Http\Message\Factory;
20
21	use FastForward\Http\Message\PayloadResponseInterface;
22	use Psr\Http\Message\ResponseFactoryInterface as PsrResponseFactoryInterface;
23	use Psr\Http\Message\ResponseInterface;
24	use Psr\Http\Message\UriInterface;
25
26	/**
27	* Interface ResponseFactoryInterface.
28	*
29	* Extends PSR-17 ResponseFactoryInterface and defines additional convenience methods
30	* for generating common types of HTTP responses, including HTML, plain text, JSON payloads,
31	* redirects, and empty responses.
32	*
33	* Implementations of this interface MUST comply with the method requirements and MUST return
34	* immutable instances as per PSR-7 standards.
35	*/
36	interface ResponseFactoryInterface extends PsrResponseFactoryInterface
37	{
38	/**
39	* Creates an HTTP response containing HTML content.
40	*
41	* The response MUST have 'Content-Type: text/html' set automatically.
42	*
43	* @param string $html the HTML content to include in the response body
44	*
45	* @return ResponseInterface the generated HTML response
46	*/
47	public function createResponseFromHtml(string $html): ResponseInterface;
48
49	/**
50	* Creates an HTTP response containing a JSON-encoded payload.
51	*
52	* The response MUST have 'Content-Type: application/json' set automatically.
53	*
54	* @param array $payload the payload to encode as JSON
55	*
56	* @return PayloadResponseInterface the generated JSON response
57	*/
58	public function createResponseFromPayload(array $payload): PayloadResponseInterface;
59
60	/**
61	* Creates an HTTP response containing plain text content.
62	*
63	* The response MUST have 'Content-Type: text/plain' set automatically.
64	*
65	* @param string $text the plain text content to include in the response body
66	*
67	* @return ResponseInterface the generated plain text response
68	*/
69	public function createResponseFromText(string $text): ResponseInterface;
70
71	/**
72	* Creates an HTTP 204 No Content response.
73	*
74	* The response MUST contain no body and MUST have status code 204.
75	*
76	* @param array<string, string|string[]> $headers optional headers to include in the response
77	* @param array $headers
78	*
79	* @return ResponseInterface the generated no content response
80	*/
81	public function createResponseNoContent(array $headers): ResponseInterface;
82
83	/**
84	* Creates an HTTP redirect response.
85	*
86	* The response MUST include a 'Location' header and an appropriate status code:
87	* 301 (permanent) if $permanent is true, or 302 (temporary) otherwise.
88	*
89	* @param string|UriInterface $uri the target location for the redirect
90	* @param bool $permanent if true, issues a permanent redirect; otherwise, temporary
91	* @param array<string, string|string[]> $headers optional additional headers to include
92	* @param array $headers
93	*
94	* @return ResponseInterface the generated redirect response
95	*/
96	public function createResponseRedirect(
97	string|UriInterface $uri,
98	bool $permanent,
99	array $headers,
100	): ResponseInterface;
101	}