Namespaces

Classes

Traits

1: <?php declare(strict_types=1);
2:
3: namespace Salient\Http;
4:
5: use Psr\Http\Message\RequestInterface;
6: use Psr\Http\Message\UriInterface as PsrUriInterface;
7: use Salient\Contract\Core\DateFormatterInterface;
8: use Salient\Contract\Core\MimeType;
9: use Salient\Contract\Http\FormDataFlag;
10: use Salient\Contract\Http\HttpRequestMethod;
11: use Salient\Utility\AbstractUtility;
12: use Salient\Utility\Date;
13: use Salient\Utility\Package;
14: use Salient\Utility\Reflect;
15: use Salient\Utility\Regex;
16: use Salient\Utility\Str;
17: use DateTimeImmutable;
18: use DateTimeInterface;
19: use DateTimeZone;
20: use Generator;
21: use InvalidArgumentException;
22: use Stringable;
23:
24: /**
25: * @api
26: */
27: final class Http extends AbstractUtility
28: {
29: /**
30: * @var array<string,string>
31: *
32: * @link https://www.iana.org/assignments/media-type-structured-suffix/media-type-structured-suffix.xhtml
33: */
34: private const SUFFIX_TYPE = [
35: 'gzip' => MimeType::GZIP,
36: 'json' => MimeType::JSON,
37: 'jwt' => MimeType::JWT,
38: 'xml' => MimeType::XML,
39: 'yaml' => MimeType::YAML,
40: 'zip' => MimeType::ZIP,
41: ];
42:
43: /**
44: * @var array<string,string>
45: */
46: private const ALIAS_TYPE = [
47: 'text/xml' => MimeType::XML,
48: ];
49:
50: /**
51: * Check if a string is a valid HTTP request method
52: *
53: * @phpstan-assert-if-true HttpRequestMethod::* $method
54: */
55: public static function isRequestMethod(string $method): bool
56: {
57: return Reflect::hasConstantWithValue(HttpRequestMethod::class, $method);
58: }
59:
60: /**
61: * Check if a media type is a match for the given MIME type
62: *
63: * Structured syntax suffixes (e.g. `+json` in `application/vnd.api+json`)
64: * are parsed as per \[RFC6838] Section 4.2.8 ("Structured Syntax Name
65: * Suffixes").
66: */
67: public static function mediaTypeIs(string $type, string $mimeType): bool
68: {
69: // Extract and normalise the type and subtype
70: [$type] = explode(';', $type);
71: $type = Str::lower(rtrim($type));
72:
73: if ((self::ALIAS_TYPE[$type] ?? $type) === $mimeType) {
74: return true;
75: }
76:
77: // Check for a structured syntax suffix
78: $pos = strrpos($type, '+');
79: if ($pos === false) {
80: return false;
81: }
82:
83: $suffix = substr($type, $pos + 1);
84: $type = substr($type, 0, $pos);
85:
86: return (self::ALIAS_TYPE[$type] ?? $type) === $mimeType
87: || (self::SUFFIX_TYPE[$suffix] ?? null) === $mimeType;
88: }
89:
90: /**
91: * Get an HTTP date value as per [RFC7231] Section 7.1.1.1
92: */
93: public static function getDate(?DateTimeInterface $date = null): string
94: {
95: return ($date ? Date::immutable($date) : new DateTimeImmutable())
96: ->setTimezone(new DateTimeZone('UTC'))
97: ->format(DateTimeInterface::RFC7231);
98: }
99:
100: /**
101: * Get semicolon-delimited parameters from the value of an HTTP header
102: *
103: * @return string[]
104: */
105: public static function getParameters(
106: string $value,
107: bool $firstIsParameter = false,
108: bool $unquote = true,
109: bool $strict = false
110: ): array {
111: foreach (Str::splitDelimited(';', $value) as $i => $param) {
112: if ($i === 0 && !$firstIsParameter) {
113: $params[] = $unquote
114: ? self::unquoteString($param)
115: : $param;
116: continue;
117: }
118: if (Regex::match('/^(' . Regex::HTTP_TOKEN . ')(?:\h*+=\h*+(.*))?$/D', $param, $matches)) {
119: $param = $matches[2] ?? '';
120: $params[Str::lower($matches[1])] = $unquote
121: ? self::unquoteString($param)
122: : $param;
123: continue;
124: }
125: if ($strict) {
126: throw new InvalidArgumentException(sprintf('Invalid parameter: %s', $param));
127: }
128: }
129: return $params ?? [];
130: }
131:
132: /**
133: * Merge parameters into a semicolon-delimited HTTP header value
134: *
135: * @param string[] $parameters
136: */
137: public static function mergeParameters(array $parameters): string
138: {
139: if (!$parameters) {
140: return '';
141: }
142:
143: foreach ($parameters as $key => $param) {
144: $value = is_int($key) ? [] : [$key];
145: if ($param !== '') {
146: $value[] = self::maybeQuoteString($param);
147: }
148: $merged[] = $last = implode('=', $value);
149: }
150: $merged = implode('; ', $merged);
151: return $last === '' && $merged !== ''
152: ? substr($merged, 0, -1)
153: : $merged;
154: }
155:
156: /**
157: * Get a product identifier suitable for User-Agent and Server headers as
158: * per [RFC7231] Section 5.5.3
159: */
160: public static function getProduct(): string
161: {
162: return sprintf(
163: '%s/%s php/%s',
164: str_replace('/', '~', Package::name()),
165: Package::version(true, true),
166: \PHP_VERSION,
167: );
168: }
169:
170: /**
171: * Escape and quote a string unless it is a valid HTTP token, as per
172: * [RFC7230] Section 3.2.6
173: */
174: public static function maybeQuoteString(string $string): string
175: {
176: return Regex::match('/^' . Regex::HTTP_TOKEN . '$/D', $string)
177: ? $string
178: : '"' . self::escapeQuotedString($string) . '"';
179: }
180:
181: /**
182: * Escape backslashes and double-quote marks in a string as per [RFC7230]
183: * Section 3.2.6
184: */
185: public static function escapeQuotedString(string $string): string
186: {
187: return str_replace(['\\', '"'], ['\\\\', '\"'], $string);
188: }
189:
190: /**
191: * Unescape and remove quotes from a string as per [RFC7230] Section 3.2.6
192: */
193: public static function unquoteString(string $string): string
194: {
195: $string = Regex::replace('/^"(.*)"$/D', '$1', $string, -1, $count);
196: return $count
197: ? Regex::replace('/\\\\(.)/', '$1', $string)
198: : $string;
199: }
200:
201: /**
202: * Merge values into the query string of a request or URI
203: *
204: * @template T of RequestInterface|PsrUriInterface|Stringable|string
205: *
206: * @param T $value
207: * @param mixed[] $data
208: * @param int-mask-of<FormDataFlag::*> $flags
209: * @return (T is RequestInterface|PsrUriInterface ? T : Uri)
210: */
211: public static function mergeQuery(
212: $value,
213: array $data,
214: int $flags = FormDataFlag::PRESERVE_NUMERIC_KEYS | FormDataFlag::PRESERVE_STRING_KEYS,
215: ?DateFormatterInterface $dateFormatter = null
216: ) {
217: $uri = $value instanceof RequestInterface
218: ? $value->getUri()
219: : ($value instanceof PsrUriInterface
220: ? $value
221: : new Uri((string) $value));
222: /** @todo Replace with `parse_str()` alternative */
223: parse_str($uri->getQuery(), $query);
224: $query = (new FormData(array_replace_recursive($query, $data)))
225: ->getQuery($flags, $dateFormatter);
226: if ($value instanceof RequestInterface) {
227: return $value->withUri($uri->withQuery($query));
228: }
229: return $uri->withQuery($query);
230: }
231:
232: /**
233: * Replace the query string of a request or URI with the given values
234: *
235: * @template T of RequestInterface|PsrUriInterface|Stringable|string
236: *
237: * @param T $value
238: * @param mixed[] $data
239: * @param int-mask-of<FormDataFlag::*> $flags
240: * @return (T is RequestInterface|PsrUriInterface ? T : Uri)
241: */
242: public static function replaceQuery(
243: $value,
244: array $data,
245: int $flags = FormDataFlag::PRESERVE_NUMERIC_KEYS | FormDataFlag::PRESERVE_STRING_KEYS,
246: ?DateFormatterInterface $dateFormatter = null
247: ) {
248: $query = (new FormData($data))->getQuery($flags, $dateFormatter);
249: if ($value instanceof RequestInterface) {
250: return $value->withUri($value->getUri()->withQuery($query));
251: }
252: if (!$value instanceof PsrUriInterface) {
253: $value = new Uri((string) $value);
254: }
255: return $value->withQuery($query);
256: }
257:
258: /**
259: * Get key-value pairs from a list of arrays with "name" and "value" keys
260: *
261: * @param iterable<array{name:string,value:string}> $items
262: * @return Generator<string,string>
263: */
264: public static function getNameValueGenerator(iterable $items): Generator
265: {
266: foreach ($items as $item) {
267: yield $item['name'] => $item['value'];
268: }
269: }
270: }
271:
salient/toolkit API documentation generated by ApiGen v7.0.0-alpha.6