1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* This file is part of php-fast-forward/http-message.
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-message
15	* @see       https://github.com/php-fast-forward
16	* @see       https://datatracker.ietf.org/doc/html/rfc2119
17	*/
18
19	namespace FastForward\Http\Message;
20
21	/**
22	* Interface PayloadAwareInterface.
23	*
24	* Defines functionality for objects that encapsulate and manage a payload.
25	* Implementations of this interface MUST provide immutable methods for accessing and replacing the payload.
26	* The payload MAY be of any type supported by the implementation, including arrays, objects, scalars, or null.
27	*
28	* @internal
29	*/
30	interface PayloadImmutableInterface
31	{
32	/**
33	* Returns a new instance with the specified payload.
34	*
35	* This method MUST NOT modify the current instance. It SHALL return a new instance with the updated payload.
36	* The payload MAY be of any type supported by the implementation. Implementations MAY throw exceptions if
37	* constraints on the payload type are violated.
38	*
39	* @param mixed $payload the new payload to set in the instance
40	*
41	* @return self a new instance with the updated payload
42	*/
43	public function withPayload(mixed $payload): self;
44	}