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[](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
){kind=link}