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: |