1: <?php declare(strict_types=1);
2:
3: namespace Salient\Contract\Http;
4:
5: use Salient\Contract\Collection\DictionaryInterface;
6: use Salient\Contract\Core\Arrayable;
7: use Salient\Contract\Core\Immutable;
8: use Salient\Contract\Http\Exception\InvalidHeaderException;
9: use LogicException;
10: use Stringable;
11:
12: /**
13: * @api
14: *
15: * @extends DictionaryInterface<string,string[]>
16: */
17: interface HeadersInterface extends
18: DictionaryInterface,
19: HasHeaders,
20: Immutable,
21: Stringable,
22: HasHttpHeader
23: {
24: /**
25: * @param Arrayable<string,string[]|string>|iterable<string,string[]|string> $items
26: */
27: public function __construct($items = []);
28:
29: /**
30: * Parse and apply a header field line or continuation thereof
31: *
32: * To initialise an instance from an HTTP stream or message, call this
33: * method once per field line after the request or status line, including
34: * the CRLF sequence at the end of each line. After receiving an empty line
35: * (`"\r\n"`), {@see hasEmptyLine()} returns `true`, and any headers
36: * received via {@see addLine()} are applied as trailers.
37: *
38: * @return static
39: * @throws LogicException if headers have been applied to the instance via
40: * another method.
41: * @throws InvalidHeaderException if `$line` is invalid.
42: */
43: public function addLine(string $line);
44:
45: /**
46: * Check if an empty line has been received via addLine()
47: */
48: public function hasEmptyLine(): bool;
49:
50: /**
51: * Check if a line with bad whitespace has been received via addLine()
52: */
53: public function hasBadWhitespace(): bool;
54:
55: /**
56: * Check if obsolete line folding has been received via addLine()
57: */
58: public function hasObsoleteLineFolding(): bool;
59:
60: /**
61: * Apply a value to a header, preserving any existing values
62: *
63: * @param string $key
64: * @param string[]|string $value
65: * @return static
66: */
67: public function addValue($key, $value);
68:
69: /**
70: * Apply a value to a header, replacing any existing values
71: *
72: * @param string[]|string $value
73: */
74: public function set($key, $value);
75:
76: /**
77: * Remove a header
78: */
79: public function unset($key);
80:
81: /**
82: * Merge the collection with the given headers, optionally preserving any
83: * existing values
84: *
85: * @param Arrayable<string,string[]|string>|iterable<string,string[]|string> $items
86: */
87: public function merge($items, bool $preserveValues = false);
88:
89: /**
90: * Apply a credential to a header
91: *
92: * @return static
93: */
94: public function authorize(
95: CredentialInterface $credential,
96: string $headerName = HeadersInterface::HEADER_AUTHORIZATION
97: );
98:
99: /**
100: * Move the "Host" header to the start of the collection if present
101: *
102: * @return static
103: */
104: public function normalise();
105:
106: /**
107: * Reduce the collection to headers received after the message body
108: *
109: * @return static
110: */
111: public function trailers();
112:
113: /**
114: * Reduce the collection to headers received before the message body
115: *
116: * @return static
117: */
118: public function withoutTrailers();
119:
120: /**
121: * Get header names and values in their original order as a list of field
122: * lines, preserving the original case of each header
123: *
124: * If `$emptyFormat` is given, it is used for headers with an empty value.
125: *
126: * @return string[]
127: */
128: public function getLines(
129: string $format = '%s: %s',
130: ?string $emptyFormat = null
131: ): array;
132:
133: /**
134: * Get header names and values in their original order as a list of HTTP
135: * Archive (HAR) header objects, preserving the original case of each header
136: *
137: * @return array<array{name:string,value:string}>
138: */
139: public function jsonSerialize(): array;
140: }
141: