• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..29-Apr-2022-

src/H29-Apr-2022-5,9543,396

.php_cs.distH A D28-Apr-20222.1 KiB5754

CHANGELOG.mdH A D28-Apr-20228.1 KiB313189

LICENSEH A D28-Apr-20221.4 KiB2722

README.mdH A D28-Apr-202227 KiB825510

composer.jsonH A D28-Apr-20222.2 KiB7776

README.md

1# PSR-7 Message Implementation
2
3This repository contains a full [PSR-7](http://www.php-fig.org/psr/psr-7/)
4message implementation, several stream decorators, and some helpful
5functionality like query string parsing.
6
7
8[![Build Status](https://travis-ci.org/guzzle/psr7.svg?branch=master)](https://travis-ci.org/guzzle/psr7)
9
10
11# Stream implementation
12
13This package comes with a number of stream implementations and stream
14decorators.
15
16
17## AppendStream
18
19`GuzzleHttp\Psr7\AppendStream`
20
21Reads from multiple streams, one after the other.
22
23```php
24use GuzzleHttp\Psr7;
25
26$a = Psr7\Utils::streamFor('abc, ');
27$b = Psr7\Utils::streamFor('123.');
28$composed = new Psr7\AppendStream([$a, $b]);
29
30$composed->addStream(Psr7\Utils::streamFor(' Above all listen to me'));
31
32echo $composed; // abc, 123. Above all listen to me.
33```
34
35
36## BufferStream
37
38`GuzzleHttp\Psr7\BufferStream`
39
40Provides a buffer stream that can be written to fill a buffer, and read
41from to remove bytes from the buffer.
42
43This stream returns a "hwm" metadata value that tells upstream consumers
44what the configured high water mark of the stream is, or the maximum
45preferred size of the buffer.
46
47```php
48use GuzzleHttp\Psr7;
49
50// When more than 1024 bytes are in the buffer, it will begin returning
51// false to writes. This is an indication that writers should slow down.
52$buffer = new Psr7\BufferStream(1024);
53```
54
55
56## CachingStream
57
58The CachingStream is used to allow seeking over previously read bytes on
59non-seekable streams. This can be useful when transferring a non-seekable
60entity body fails due to needing to rewind the stream (for example, resulting
61from a redirect). Data that is read from the remote stream will be buffered in
62a PHP temp stream so that previously read bytes are cached first in memory,
63then on disk.
64
65```php
66use GuzzleHttp\Psr7;
67
68$original = Psr7\Utils::streamFor(fopen('http://www.google.com', 'r'));
69$stream = new Psr7\CachingStream($original);
70
71$stream->read(1024);
72echo $stream->tell();
73// 1024
74
75$stream->seek(0);
76echo $stream->tell();
77// 0
78```
79
80
81## DroppingStream
82
83`GuzzleHttp\Psr7\DroppingStream`
84
85Stream decorator that begins dropping data once the size of the underlying
86stream becomes too full.
87
88```php
89use GuzzleHttp\Psr7;
90
91// Create an empty stream
92$stream = Psr7\Utils::streamFor();
93
94// Start dropping data when the stream has more than 10 bytes
95$dropping = new Psr7\DroppingStream($stream, 10);
96
97$dropping->write('01234567890123456789');
98echo $stream; // 0123456789
99```
100
101
102## FnStream
103
104`GuzzleHttp\Psr7\FnStream`
105
106Compose stream implementations based on a hash of functions.
107
108Allows for easy testing and extension of a provided stream without needing
109to create a concrete class for a simple extension point.
110
111```php
112
113use GuzzleHttp\Psr7;
114
115$stream = Psr7\Utils::streamFor('hi');
116$fnStream = Psr7\FnStream::decorate($stream, [
117    'rewind' => function () use ($stream) {
118        echo 'About to rewind - ';
119        $stream->rewind();
120        echo 'rewound!';
121    }
122]);
123
124$fnStream->rewind();
125// Outputs: About to rewind - rewound!
126```
127
128
129## InflateStream
130
131`GuzzleHttp\Psr7\InflateStream`
132
133Uses PHP's zlib.inflate filter to inflate deflate or gzipped content.
134
135This stream decorator skips the first 10 bytes of the given stream to remove
136the gzip header, converts the provided stream to a PHP stream resource,
137then appends the zlib.inflate filter. The stream is then converted back
138to a Guzzle stream resource to be used as a Guzzle stream.
139
140
141## LazyOpenStream
142
143`GuzzleHttp\Psr7\LazyOpenStream`
144
145Lazily reads or writes to a file that is opened only after an IO operation
146take place on the stream.
147
148```php
149use GuzzleHttp\Psr7;
150
151$stream = new Psr7\LazyOpenStream('/path/to/file', 'r');
152// The file has not yet been opened...
153
154echo $stream->read(10);
155// The file is opened and read from only when needed.
156```
157
158
159## LimitStream
160
161`GuzzleHttp\Psr7\LimitStream`
162
163LimitStream can be used to read a subset or slice of an existing stream object.
164This can be useful for breaking a large file into smaller pieces to be sent in
165chunks (e.g. Amazon S3's multipart upload API).
166
167```php
168use GuzzleHttp\Psr7;
169
170$original = Psr7\Utils::streamFor(fopen('/tmp/test.txt', 'r+'));
171echo $original->getSize();
172// >>> 1048576
173
174// Limit the size of the body to 1024 bytes and start reading from byte 2048
175$stream = new Psr7\LimitStream($original, 1024, 2048);
176echo $stream->getSize();
177// >>> 1024
178echo $stream->tell();
179// >>> 0
180```
181
182
183## MultipartStream
184
185`GuzzleHttp\Psr7\MultipartStream`
186
187Stream that when read returns bytes for a streaming multipart or
188multipart/form-data stream.
189
190
191## NoSeekStream
192
193`GuzzleHttp\Psr7\NoSeekStream`
194
195NoSeekStream wraps a stream and does not allow seeking.
196
197```php
198use GuzzleHttp\Psr7;
199
200$original = Psr7\Utils::streamFor('foo');
201$noSeek = new Psr7\NoSeekStream($original);
202
203echo $noSeek->read(3);
204// foo
205var_export($noSeek->isSeekable());
206// false
207$noSeek->seek(0);
208var_export($noSeek->read(3));
209// NULL
210```
211
212
213## PumpStream
214
215`GuzzleHttp\Psr7\PumpStream`
216
217Provides a read only stream that pumps data from a PHP callable.
218
219When invoking the provided callable, the PumpStream will pass the amount of
220data requested to read to the callable. The callable can choose to ignore
221this value and return fewer or more bytes than requested. Any extra data
222returned by the provided callable is buffered internally until drained using
223the read() function of the PumpStream. The provided callable MUST return
224false when there is no more data to read.
225
226
227## Implementing stream decorators
228
229Creating a stream decorator is very easy thanks to the
230`GuzzleHttp\Psr7\StreamDecoratorTrait`. This trait provides methods that
231implement `Psr\Http\Message\StreamInterface` by proxying to an underlying
232stream. Just `use` the `StreamDecoratorTrait` and implement your custom
233methods.
234
235For example, let's say we wanted to call a specific function each time the last
236byte is read from a stream. This could be implemented by overriding the
237`read()` method.
238
239```php
240use Psr\Http\Message\StreamInterface;
241use GuzzleHttp\Psr7\StreamDecoratorTrait;
242
243class EofCallbackStream implements StreamInterface
244{
245    use StreamDecoratorTrait;
246
247    private $callback;
248
249    public function __construct(StreamInterface $stream, callable $cb)
250    {
251        $this->stream = $stream;
252        $this->callback = $cb;
253    }
254
255    public function read($length)
256    {
257        $result = $this->stream->read($length);
258
259        // Invoke the callback when EOF is hit.
260        if ($this->eof()) {
261            call_user_func($this->callback);
262        }
263
264        return $result;
265    }
266}
267```
268
269This decorator could be added to any existing stream and used like so:
270
271```php
272use GuzzleHttp\Psr7;
273
274$original = Psr7\Utils::streamFor('foo');
275
276$eofStream = new EofCallbackStream($original, function () {
277    echo 'EOF!';
278});
279
280$eofStream->read(2);
281$eofStream->read(1);
282// echoes "EOF!"
283$eofStream->seek(0);
284$eofStream->read(3);
285// echoes "EOF!"
286```
287
288
289## PHP StreamWrapper
290
291You can use the `GuzzleHttp\Psr7\StreamWrapper` class if you need to use a
292PSR-7 stream as a PHP stream resource.
293
294Use the `GuzzleHttp\Psr7\StreamWrapper::getResource()` method to create a PHP
295stream from a PSR-7 stream.
296
297```php
298use GuzzleHttp\Psr7\StreamWrapper;
299
300$stream = GuzzleHttp\Psr7\Utils::streamFor('hello!');
301$resource = StreamWrapper::getResource($stream);
302echo fread($resource, 6); // outputs hello!
303```
304
305
306# Static API
307
308There are various static methods available under the `GuzzleHttp\Psr7` namespace.
309
310
311## `GuzzleHttp\Psr7\Message::toString`
312
313`public static function toString(MessageInterface $message): string`
314
315Returns the string representation of an HTTP message.
316
317```php
318$request = new GuzzleHttp\Psr7\Request('GET', 'http://example.com');
319echo GuzzleHttp\Psr7\Message::toString($request);
320```
321
322
323## `GuzzleHttp\Psr7\Message::bodySummary`
324
325`public static function bodySummary(MessageInterface $message, int $truncateAt = 120): string|null`
326
327Get a short summary of the message body.
328
329Will return `null` if the response is not printable.
330
331
332## `GuzzleHttp\Psr7\Message::rewindBody`
333
334`public static function rewindBody(MessageInterface $message): void`
335
336Attempts to rewind a message body and throws an exception on failure.
337
338The body of the message will only be rewound if a call to `tell()`
339returns a value other than `0`.
340
341
342## `GuzzleHttp\Psr7\Message::parseMessage`
343
344`public static function parseMessage(string $message): array`
345
346Parses an HTTP message into an associative array.
347
348The array contains the "start-line" key containing the start line of
349the message, "headers" key containing an associative array of header
350array values, and a "body" key containing the body of the message.
351
352
353## `GuzzleHttp\Psr7\Message::parseRequestUri`
354
355`public static function parseRequestUri(string $path, array $headers): string`
356
357Constructs a URI for an HTTP request message.
358
359
360## `GuzzleHttp\Psr7\Message::parseRequest`
361
362`public static function parseRequest(string $message): Request`
363
364Parses a request message string into a request object.
365
366
367## `GuzzleHttp\Psr7\Message::parseResponse`
368
369`public static function parseResponse(string $message): Response`
370
371Parses a response message string into a response object.
372
373
374## `GuzzleHttp\Psr7\Header::parse`
375
376`public static function parse(string|array $header): array`
377
378Parse an array of header values containing ";" separated data into an
379array of associative arrays representing the header key value pair data
380of the header. When a parameter does not contain a value, but just
381contains a key, this function will inject a key with a '' string value.
382
383
384## `GuzzleHttp\Psr7\Header::normalize`
385
386`public static function normalize(string|array $header): array`
387
388Converts an array of header values that may contain comma separated
389headers into an array of headers with no comma separated values.
390
391
392## `GuzzleHttp\Psr7\Query::parse`
393
394`public static function parse(string $str, int|bool $urlEncoding = true): array`
395
396Parse a query string into an associative array.
397
398If multiple values are found for the same key, the value of that key
399value pair will become an array. This function does not parse nested
400PHP style arrays into an associative array (e.g., `foo[a]=1&foo[b]=2`
401will be parsed into `['foo[a]' => '1', 'foo[b]' => '2'])`.
402
403
404## `GuzzleHttp\Psr7\Query::build`
405
406`public static function build(array $params, int|false $encoding = PHP_QUERY_RFC3986): string`
407
408Build a query string from an array of key value pairs.
409
410This function can use the return value of `parse()` to build a query
411string. This function does not modify the provided keys when an array is
412encountered (like `http_build_query()` would).
413
414
415## `GuzzleHttp\Psr7\Utils::caselessRemove`
416
417`public static function caselessRemove(iterable<string> $keys, $keys, array $data): array`
418
419Remove the items given by the keys, case insensitively from the data.
420
421
422## `GuzzleHttp\Psr7\Utils::copyToStream`
423
424`public static function copyToStream(StreamInterface $source, StreamInterface $dest, int $maxLen = -1): void`
425
426Copy the contents of a stream into another stream until the given number
427of bytes have been read.
428
429
430## `GuzzleHttp\Psr7\Utils::copyToString`
431
432`public static function copyToString(StreamInterface $stream, int $maxLen = -1): string`
433
434Copy the contents of a stream into a string until the given number of
435bytes have been read.
436
437
438## `GuzzleHttp\Psr7\Utils::hash`
439
440`public static function hash(StreamInterface $stream, string $algo, bool $rawOutput = false): string`
441
442Calculate a hash of a stream.
443
444This method reads the entire stream to calculate a rolling hash, based on
445PHP's `hash_init` functions.
446
447
448## `GuzzleHttp\Psr7\Utils::modifyRequest`
449
450`public static function modifyRequest(RequestInterface $request, array $changes): RequestInterface`
451
452Clone and modify a request with the given changes.
453
454This method is useful for reducing the number of clones needed to mutate
455a message.
456
457- method: (string) Changes the HTTP method.
458- set_headers: (array) Sets the given headers.
459- remove_headers: (array) Remove the given headers.
460- body: (mixed) Sets the given body.
461- uri: (UriInterface) Set the URI.
462- query: (string) Set the query string value of the URI.
463- version: (string) Set the protocol version.
464
465
466## `GuzzleHttp\Psr7\Utils::readLine`
467
468`public static function readLine(StreamInterface $stream, int $maxLength = null): string`
469
470Read a line from the stream up to the maximum allowed buffer length.
471
472
473## `GuzzleHttp\Psr7\Utils::streamFor`
474
475`public static function streamFor(resource|string|null|int|float|bool|StreamInterface|callable|\Iterator $resource = '', array $options = []): StreamInterface`
476
477Create a new stream based on the input type.
478
479Options is an associative array that can contain the following keys:
480
481- metadata: Array of custom metadata.
482- size: Size of the stream.
483
484This method accepts the following `$resource` types:
485
486- `Psr\Http\Message\StreamInterface`: Returns the value as-is.
487- `string`: Creates a stream object that uses the given string as the contents.
488- `resource`: Creates a stream object that wraps the given PHP stream resource.
489- `Iterator`: If the provided value implements `Iterator`, then a read-only
490  stream object will be created that wraps the given iterable. Each time the
491  stream is read from, data from the iterator will fill a buffer and will be
492  continuously called until the buffer is equal to the requested read size.
493  Subsequent read calls will first read from the buffer and then call `next`
494  on the underlying iterator until it is exhausted.
495- `object` with `__toString()`: If the object has the `__toString()` method,
496  the object will be cast to a string and then a stream will be returned that
497  uses the string value.
498- `NULL`: When `null` is passed, an empty stream object is returned.
499- `callable` When a callable is passed, a read-only stream object will be
500  created that invokes the given callable. The callable is invoked with the
501  number of suggested bytes to read. The callable can return any number of
502  bytes, but MUST return `false` when there is no more data to return. The
503  stream object that wraps the callable will invoke the callable until the
504  number of requested bytes are available. Any additional bytes will be
505  buffered and used in subsequent reads.
506
507```php
508$stream = GuzzleHttp\Psr7\Utils::streamFor('foo');
509$stream = GuzzleHttp\Psr7\Utils::streamFor(fopen('/path/to/file', 'r'));
510
511$generator = function ($bytes) {
512    for ($i = 0; $i < $bytes; $i++) {
513        yield ' ';
514    }
515}
516
517$stream = GuzzleHttp\Psr7\Utils::streamFor($generator(100));
518```
519
520
521## `GuzzleHttp\Psr7\Utils::tryFopen`
522
523`public static function tryFopen(string $filename, string $mode): resource`
524
525Safely opens a PHP stream resource using a filename.
526
527When fopen fails, PHP normally raises a warning. This function adds an
528error handler that checks for errors and throws an exception instead.
529
530
531## `GuzzleHttp\Psr7\Utils::uriFor`
532
533`public static function uriFor(string|UriInterface $uri): UriInterface`
534
535Returns a UriInterface for the given value.
536
537This function accepts a string or UriInterface and returns a
538UriInterface for the given value. If the value is already a
539UriInterface, it is returned as-is.
540
541
542## `GuzzleHttp\Psr7\MimeType::fromFilename`
543
544`public static function fromFilename(string $filename): string|null`
545
546Determines the mimetype of a file by looking at its extension.
547
548
549## `GuzzleHttp\Psr7\MimeType::fromExtension`
550
551`public static function fromExtension(string $extension): string|null`
552
553Maps a file extensions to a mimetype.
554
555
556## Upgrading from Function API
557
558The static API was first introduced in 1.7.0, in order to mitigate problems with functions conflicting between global and local copies of the package. The function API will be removed in 2.0.0. A migration table has been provided here for your convenience:
559
560| Original Function | Replacement Method |
561|----------------|----------------|
562| `str` | `Message::toString` |
563| `uri_for` | `Utils::uriFor` |
564| `stream_for` | `Utils::streamFor` |
565| `parse_header` | `Header::parse` |
566| `normalize_header` | `Header::normalize` |
567| `modify_request` | `Utils::modifyRequest` |
568| `rewind_body` | `Message::rewindBody` |
569| `try_fopen` | `Utils::tryFopen` |
570| `copy_to_string` | `Utils::copyToString` |
571| `copy_to_stream` | `Utils::copyToStream` |
572| `hash` | `Utils::hash` |
573| `readline` | `Utils::readLine` |
574| `parse_request` | `Message::parseRequest` |
575| `parse_response` | `Message::parseResponse` |
576| `parse_query` | `Query::parse` |
577| `build_query` | `Query::build` |
578| `mimetype_from_filename` | `MimeType::fromFilename` |
579| `mimetype_from_extension` | `MimeType::fromExtension` |
580| `_parse_message` | `Message::parseMessage` |
581| `_parse_request_uri` | `Message::parseRequestUri` |
582| `get_message_body_summary` | `Message::bodySummary` |
583| `_caseless_remove` | `Utils::caselessRemove` |
584
585
586# Additional URI Methods
587
588Aside from the standard `Psr\Http\Message\UriInterface` implementation in form of the `GuzzleHttp\Psr7\Uri` class,
589this library also provides additional functionality when working with URIs as static methods.
590
591## URI Types
592
593An instance of `Psr\Http\Message\UriInterface` can either be an absolute URI or a relative reference.
594An absolute URI has a scheme. A relative reference is used to express a URI relative to another URI,
595the base URI. Relative references can be divided into several forms according to
596[RFC 3986 Section 4.2](https://tools.ietf.org/html/rfc3986#section-4.2):
597
598- network-path references, e.g. `//example.com/path`
599- absolute-path references, e.g. `/path`
600- relative-path references, e.g. `subpath`
601
602The following methods can be used to identify the type of the URI.
603
604### `GuzzleHttp\Psr7\Uri::isAbsolute`
605
606`public static function isAbsolute(UriInterface $uri): bool`
607
608Whether the URI is absolute, i.e. it has a scheme.
609
610### `GuzzleHttp\Psr7\Uri::isNetworkPathReference`
611
612`public static function isNetworkPathReference(UriInterface $uri): bool`
613
614Whether the URI is a network-path reference. A relative reference that begins with two slash characters is
615termed an network-path reference.
616
617### `GuzzleHttp\Psr7\Uri::isAbsolutePathReference`
618
619`public static function isAbsolutePathReference(UriInterface $uri): bool`
620
621Whether the URI is a absolute-path reference. A relative reference that begins with a single slash character is
622termed an absolute-path reference.
623
624### `GuzzleHttp\Psr7\Uri::isRelativePathReference`
625
626`public static function isRelativePathReference(UriInterface $uri): bool`
627
628Whether the URI is a relative-path reference. A relative reference that does not begin with a slash character is
629termed a relative-path reference.
630
631### `GuzzleHttp\Psr7\Uri::isSameDocumentReference`
632
633`public static function isSameDocumentReference(UriInterface $uri, UriInterface $base = null): bool`
634
635Whether the URI is a same-document reference. A same-document reference refers to a URI that is, aside from its
636fragment component, identical to the base URI. When no base URI is given, only an empty URI reference
637(apart from its fragment) is considered a same-document reference.
638
639## URI Components
640
641Additional methods to work with URI components.
642
643### `GuzzleHttp\Psr7\Uri::isDefaultPort`
644
645`public static function isDefaultPort(UriInterface $uri): bool`
646
647Whether the URI has the default port of the current scheme. `Psr\Http\Message\UriInterface::getPort` may return null
648or the standard port. This method can be used independently of the implementation.
649
650### `GuzzleHttp\Psr7\Uri::composeComponents`
651
652`public static function composeComponents($scheme, $authority, $path, $query, $fragment): string`
653
654Composes a URI reference string from its various components according to
655[RFC 3986 Section 5.3](https://tools.ietf.org/html/rfc3986#section-5.3). Usually this method does not need to be called
656manually but instead is used indirectly via `Psr\Http\Message\UriInterface::__toString`.
657
658### `GuzzleHttp\Psr7\Uri::fromParts`
659
660`public static function fromParts(array $parts): UriInterface`
661
662Creates a URI from a hash of [`parse_url`](http://php.net/manual/en/function.parse-url.php) components.
663
664
665### `GuzzleHttp\Psr7\Uri::withQueryValue`
666
667`public static function withQueryValue(UriInterface $uri, $key, $value): UriInterface`
668
669Creates a new URI with a specific query string value. Any existing query string values that exactly match the
670provided key are removed and replaced with the given key value pair. A value of null will set the query string
671key without a value, e.g. "key" instead of "key=value".
672
673### `GuzzleHttp\Psr7\Uri::withQueryValues`
674
675`public static function withQueryValues(UriInterface $uri, array $keyValueArray): UriInterface`
676
677Creates a new URI with multiple query string values. It has the same behavior as `withQueryValue()` but for an
678associative array of key => value.
679
680### `GuzzleHttp\Psr7\Uri::withoutQueryValue`
681
682`public static function withoutQueryValue(UriInterface $uri, $key): UriInterface`
683
684Creates a new URI with a specific query string value removed. Any existing query string values that exactly match the
685provided key are removed.
686
687## Reference Resolution
688
689`GuzzleHttp\Psr7\UriResolver` provides methods to resolve a URI reference in the context of a base URI according
690to [RFC 3986 Section 5](https://tools.ietf.org/html/rfc3986#section-5). This is for example also what web browsers
691do when resolving a link in a website based on the current request URI.
692
693### `GuzzleHttp\Psr7\UriResolver::resolve`
694
695`public static function resolve(UriInterface $base, UriInterface $rel): UriInterface`
696
697Converts the relative URI into a new URI that is resolved against the base URI.
698
699### `GuzzleHttp\Psr7\UriResolver::removeDotSegments`
700
701`public static function removeDotSegments(string $path): string`
702
703Removes dot segments from a path and returns the new path according to
704[RFC 3986 Section 5.2.4](https://tools.ietf.org/html/rfc3986#section-5.2.4).
705
706### `GuzzleHttp\Psr7\UriResolver::relativize`
707
708`public static function relativize(UriInterface $base, UriInterface $target): UriInterface`
709
710Returns the target URI as a relative reference from the base URI. This method is the counterpart to resolve():
711
712```php
713(string) $target === (string) UriResolver::resolve($base, UriResolver::relativize($base, $target))
714```
715
716One use-case is to use the current request URI as base URI and then generate relative links in your documents
717to reduce the document size or offer self-contained downloadable document archives.
718
719```php
720$base = new Uri('http://example.com/a/b/');
721echo UriResolver::relativize($base, new Uri('http://example.com/a/b/c'));  // prints 'c'.
722echo UriResolver::relativize($base, new Uri('http://example.com/a/x/y'));  // prints '../x/y'.
723echo UriResolver::relativize($base, new Uri('http://example.com/a/b/?q')); // prints '?q'.
724echo UriResolver::relativize($base, new Uri('http://example.org/a/b/'));   // prints '//example.org/a/b/'.
725```
726
727## Normalization and Comparison
728
729`GuzzleHttp\Psr7\UriNormalizer` provides methods to normalize and compare URIs according to
730[RFC 3986 Section 6](https://tools.ietf.org/html/rfc3986#section-6).
731
732### `GuzzleHttp\Psr7\UriNormalizer::normalize`
733
734`public static function normalize(UriInterface $uri, $flags = self::PRESERVING_NORMALIZATIONS): UriInterface`
735
736Returns a normalized URI. The scheme and host component are already normalized to lowercase per PSR-7 UriInterface.
737This methods adds additional normalizations that can be configured with the `$flags` parameter which is a bitmask
738of normalizations to apply. The following normalizations are available:
739
740- `UriNormalizer::PRESERVING_NORMALIZATIONS`
741
742    Default normalizations which only include the ones that preserve semantics.
743
744- `UriNormalizer::CAPITALIZE_PERCENT_ENCODING`
745
746    All letters within a percent-encoding triplet (e.g., "%3A") are case-insensitive, and should be capitalized.
747
748    Example: `http://example.org/a%c2%b1b` → `http://example.org/a%C2%B1b`
749
750- `UriNormalizer::DECODE_UNRESERVED_CHARACTERS`
751
752    Decodes percent-encoded octets of unreserved characters. For consistency, percent-encoded octets in the ranges of
753    ALPHA (%41–%5A and %61–%7A), DIGIT (%30–%39), hyphen (%2D), period (%2E), underscore (%5F), or tilde (%7E) should
754    not be created by URI producers and, when found in a URI, should be decoded to their corresponding unreserved
755    characters by URI normalizers.
756
757    Example: `http://example.org/%7Eusern%61me/` → `http://example.org/~username/`
758
759- `UriNormalizer::CONVERT_EMPTY_PATH`
760
761    Converts the empty path to "/" for http and https URIs.
762
763    Example: `http://example.org` → `http://example.org/`
764
765- `UriNormalizer::REMOVE_DEFAULT_HOST`
766
767    Removes the default host of the given URI scheme from the URI. Only the "file" scheme defines the default host
768    "localhost". All of `file:/myfile`, `file:///myfile`, and `file://localhost/myfile` are equivalent according to
769    RFC 3986.
770
771    Example: `file://localhost/myfile` → `file:///myfile`
772
773- `UriNormalizer::REMOVE_DEFAULT_PORT`
774
775    Removes the default port of the given URI scheme from the URI.
776
777    Example: `http://example.org:80/` → `http://example.org/`
778
779- `UriNormalizer::REMOVE_DOT_SEGMENTS`
780
781    Removes unnecessary dot-segments. Dot-segments in relative-path references are not removed as it would
782    change the semantics of the URI reference.
783
784    Example: `http://example.org/../a/b/../c/./d.html` → `http://example.org/a/c/d.html`
785
786- `UriNormalizer::REMOVE_DUPLICATE_SLASHES`
787
788    Paths which include two or more adjacent slashes are converted to one. Webservers usually ignore duplicate slashes
789    and treat those URIs equivalent. But in theory those URIs do not need to be equivalent. So this normalization
790    may change the semantics. Encoded slashes (%2F) are not removed.
791
792    Example: `http://example.org//foo///bar.html` → `http://example.org/foo/bar.html`
793
794- `UriNormalizer::SORT_QUERY_PARAMETERS`
795
796    Sort query parameters with their values in alphabetical order. However, the order of parameters in a URI may be
797    significant (this is not defined by the standard). So this normalization is not safe and may change the semantics
798    of the URI.
799
800    Example: `?lang=en&article=fred` → `?article=fred&lang=en`
801
802### `GuzzleHttp\Psr7\UriNormalizer::isEquivalent`
803
804`public static function isEquivalent(UriInterface $uri1, UriInterface $uri2, $normalizations = self::PRESERVING_NORMALIZATIONS): bool`
805
806Whether two URIs can be considered equivalent. Both URIs are normalized automatically before comparison with the given
807`$normalizations` bitmask. The method also accepts relative URI references and returns true when they are equivalent.
808This of course assumes they will be resolved against the same base URI. If this is not the case, determination of
809equivalence or difference of relative references does not mean anything.
810
811
812## Security
813
814If you discover a security vulnerability within this package, please send an email to security@tidelift.com. All security vulnerabilities will be promptly addressed. Please do not disclose security-related issues publicly until a fix has been announced. Please see [Security Policy](https://github.com/guzzle/psr7/security/policy) for more information.
815
816## License
817
818Guzzle is made available under the MIT License (MIT). Please see [License File](LICENSE) for more information.
819
820## For Enterprise
821
822Available as part of the Tidelift Subscription
823
824The maintainers of Guzzle and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/packagist-guzzlehttp-psr7?utm_source=packagist-guzzlehttp-psr7&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
825