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