| [ Index ] |
PHP Cross Reference of phpBB-3.3.10-deutsch |
[Summary view] [Print] [Text view]
1 # PSR-7 Message Implementation 2 3 This repository contains a full [PSR-7](https://www.php-fig.org/psr/psr-7/) 4 message implementation, several stream decorators, and some helpful 5 functionality like query string parsing. 6 7 8 [](https://travis-ci.org/guzzle/psr7) 9 10 11 # Stream implementation 12 13 This package comes with a number of stream implementations and stream 14 decorators. 15 16 17 ## AppendStream 18 19 `GuzzleHttp\Psr7\AppendStream` 20 21 Reads from multiple streams, one after the other. 22 23 ```php 24 use 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 32 echo $composed; // abc, 123. Above all listen to me. 33 ``` 34 35 36 ## BufferStream 37 38 `GuzzleHttp\Psr7\BufferStream` 39 40 Provides a buffer stream that can be written to fill a buffer, and read 41 from to remove bytes from the buffer. 42 43 This stream returns a "hwm" metadata value that tells upstream consumers 44 what the configured high water mark of the stream is, or the maximum 45 preferred size of the buffer. 46 47 ```php 48 use 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 58 The CachingStream is used to allow seeking over previously read bytes on 59 non-seekable streams. This can be useful when transferring a non-seekable 60 entity body fails due to needing to rewind the stream (for example, resulting 61 from a redirect). Data that is read from the remote stream will be buffered in 62 a PHP temp stream so that previously read bytes are cached first in memory, 63 then on disk. 64 65 ```php 66 use 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); 72 echo $stream->tell(); 73 // 1024 74 75 $stream->seek(0); 76 echo $stream->tell(); 77 // 0 78 ``` 79 80 81 ## DroppingStream 82 83 `GuzzleHttp\Psr7\DroppingStream` 84 85 Stream decorator that begins dropping data once the size of the underlying 86 stream becomes too full. 87 88 ```php 89 use 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'); 98 echo $stream; // 0123456789 99 ``` 100 101 102 ## FnStream 103 104 `GuzzleHttp\Psr7\FnStream` 105 106 Compose stream implementations based on a hash of functions. 107 108 Allows for easy testing and extension of a provided stream without needing 109 to create a concrete class for a simple extension point. 110 111 ```php 112 113 use 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 133 Uses PHP's zlib.inflate filter to inflate deflate or gzipped content. 134 135 This stream decorator skips the first 10 bytes of the given stream to remove 136 the gzip header, converts the provided stream to a PHP stream resource, 137 then appends the zlib.inflate filter. The stream is then converted back 138 to a Guzzle stream resource to be used as a Guzzle stream. 139 140 141 ## LazyOpenStream 142 143 `GuzzleHttp\Psr7\LazyOpenStream` 144 145 Lazily reads or writes to a file that is opened only after an IO operation 146 take place on the stream. 147 148 ```php 149 use GuzzleHttp\Psr7; 150 151 $stream = new Psr7\LazyOpenStream('/path/to/file', 'r'); 152 // The file has not yet been opened... 153 154 echo $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 163 LimitStream can be used to read a subset or slice of an existing stream object. 164 This can be useful for breaking a large file into smaller pieces to be sent in 165 chunks (e.g. Amazon S3's multipart upload API). 166 167 ```php 168 use GuzzleHttp\Psr7; 169 170 $original = Psr7\Utils::streamFor(fopen('/tmp/test.txt', 'r+')); 171 echo $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); 176 echo $stream->getSize(); 177 // >>> 1024 178 echo $stream->tell(); 179 // >>> 0 180 ``` 181 182 183 ## MultipartStream 184 185 `GuzzleHttp\Psr7\MultipartStream` 186 187 Stream that when read returns bytes for a streaming multipart or 188 multipart/form-data stream. 189 190 191 ## NoSeekStream 192 193 `GuzzleHttp\Psr7\NoSeekStream` 194 195 NoSeekStream wraps a stream and does not allow seeking. 196 197 ```php 198 use GuzzleHttp\Psr7; 199 200 $original = Psr7\Utils::streamFor('foo'); 201 $noSeek = new Psr7\NoSeekStream($original); 202 203 echo $noSeek->read(3); 204 // foo 205 var_export($noSeek->isSeekable()); 206 // false 207 $noSeek->seek(0); 208 var_export($noSeek->read(3)); 209 // NULL 210 ``` 211 212 213 ## PumpStream 214 215 `GuzzleHttp\Psr7\PumpStream` 216 217 Provides a read only stream that pumps data from a PHP callable. 218 219 When invoking the provided callable, the PumpStream will pass the amount of 220 data requested to read to the callable. The callable can choose to ignore 221 this value and return fewer or more bytes than requested. Any extra data 222 returned by the provided callable is buffered internally until drained using 223 the read() function of the PumpStream. The provided callable MUST return 224 false when there is no more data to read. 225 226 227 ## Implementing stream decorators 228 229 Creating a stream decorator is very easy thanks to the 230 `GuzzleHttp\Psr7\StreamDecoratorTrait`. This trait provides methods that 231 implement `Psr\Http\Message\StreamInterface` by proxying to an underlying 232 stream. Just `use` the `StreamDecoratorTrait` and implement your custom 233 methods. 234 235 For example, let's say we wanted to call a specific function each time the last 236 byte is read from a stream. This could be implemented by overriding the 237 `read()` method. 238 239 ```php 240 use Psr\Http\Message\StreamInterface; 241 use GuzzleHttp\Psr7\StreamDecoratorTrait; 242 243 class 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 269 This decorator could be added to any existing stream and used like so: 270 271 ```php 272 use 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 291 You can use the `GuzzleHttp\Psr7\StreamWrapper` class if you need to use a 292 PSR-7 stream as a PHP stream resource. 293 294 Use the `GuzzleHttp\Psr7\StreamWrapper::getResource()` method to create a PHP 295 stream from a PSR-7 stream. 296 297 ```php 298 use GuzzleHttp\Psr7\StreamWrapper; 299 300 $stream = GuzzleHttp\Psr7\Utils::streamFor('hello!'); 301 $resource = StreamWrapper::getResource($stream); 302 echo fread($resource, 6); // outputs hello! 303 ``` 304 305 306 # Static API 307 308 There 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 315 Returns the string representation of an HTTP message. 316 317 ```php 318 $request = new GuzzleHttp\Psr7\Request('GET', 'http://example.com'); 319 echo 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 327 Get a short summary of the message body. 328 329 Will 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 336 Attempts to rewind a message body and throws an exception on failure. 337 338 The body of the message will only be rewound if a call to `tell()` 339 returns a value other than `0`. 340 341 342 ## `GuzzleHttp\Psr7\Message::parseMessage` 343 344 `public static function parseMessage(string $message): array` 345 346 Parses an HTTP message into an associative array. 347 348 The array contains the "start-line" key containing the start line of 349 the message, "headers" key containing an associative array of header 350 array 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 357 Constructs a URI for an HTTP request message. 358 359 360 ## `GuzzleHttp\Psr7\Message::parseRequest` 361 362 `public static function parseRequest(string $message): Request` 363 364 Parses 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 371 Parses 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 378 Parse an array of header values containing ";" separated data into an 379 array of associative arrays representing the header key value pair data 380 of the header. When a parameter does not contain a value, but just 381 contains 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 388 Converts an array of header values that may contain comma separated 389 headers 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 396 Parse a query string into an associative array. 397 398 If multiple values are found for the same key, the value of that key 399 value pair will become an array. This function does not parse nested 400 PHP style arrays into an associative array (e.g., `foo[a]=1&foo[b]=2` 401 will 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 408 Build a query string from an array of key value pairs. 409 410 This function can use the return value of `parse()` to build a query 411 string. This function does not modify the provided keys when an array is 412 encountered (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 419 Remove 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 426 Copy the contents of a stream into another stream until the given number 427 of bytes have been read. 428 429 430 ## `GuzzleHttp\Psr7\Utils::copyToString` 431 432 `public static function copyToString(StreamInterface $stream, int $maxLen = -1): string` 433 434 Copy the contents of a stream into a string until the given number of 435 bytes 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 442 Calculate a hash of a stream. 443 444 This method reads the entire stream to calculate a rolling hash, based on 445 PHP's `hash_init` functions. 446 447 448 ## `GuzzleHttp\Psr7\Utils::modifyRequest` 449 450 `public static function modifyRequest(RequestInterface $request, array $changes): RequestInterface` 451 452 Clone and modify a request with the given changes. 453 454 This method is useful for reducing the number of clones needed to mutate 455 a 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 470 Read 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 477 Create a new stream based on the input type. 478 479 Options is an associative array that can contain the following keys: 480 481 - metadata: Array of custom metadata. 482 - size: Size of the stream. 483 484 This 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 525 Safely opens a PHP stream resource using a filename. 526 527 When fopen fails, PHP normally raises a warning. This function adds an 528 error 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 535 Returns a UriInterface for the given value. 536 537 This function accepts a string or UriInterface and returns a 538 UriInterface for the given value. If the value is already a 539 UriInterface, it is returned as-is. 540 541 542 ## `GuzzleHttp\Psr7\MimeType::fromFilename` 543 544 `public static function fromFilename(string $filename): string|null` 545 546 Determines 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 553 Maps a file extensions to a mimetype. 554 555 556 ## Upgrading from Function API 557 558 The 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 588 Aside from the standard `Psr\Http\Message\UriInterface` implementation in form of the `GuzzleHttp\Psr7\Uri` class, 589 this library also provides additional functionality when working with URIs as static methods. 590 591 ## URI Types 592 593 An instance of `Psr\Http\Message\UriInterface` can either be an absolute URI or a relative reference. 594 An absolute URI has a scheme. A relative reference is used to express a URI relative to another URI, 595 the 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 602 The 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 608 Whether 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 614 Whether the URI is a network-path reference. A relative reference that begins with two slash characters is 615 termed an network-path reference. 616 617 ### `GuzzleHttp\Psr7\Uri::isAbsolutePathReference` 618 619 `public static function isAbsolutePathReference(UriInterface $uri): bool` 620 621 Whether the URI is a absolute-path reference. A relative reference that begins with a single slash character is 622 termed an absolute-path reference. 623 624 ### `GuzzleHttp\Psr7\Uri::isRelativePathReference` 625 626 `public static function isRelativePathReference(UriInterface $uri): bool` 627 628 Whether the URI is a relative-path reference. A relative reference that does not begin with a slash character is 629 termed a relative-path reference. 630 631 ### `GuzzleHttp\Psr7\Uri::isSameDocumentReference` 632 633 `public static function isSameDocumentReference(UriInterface $uri, UriInterface $base = null): bool` 634 635 Whether the URI is a same-document reference. A same-document reference refers to a URI that is, aside from its 636 fragment 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 641 Additional methods to work with URI components. 642 643 ### `GuzzleHttp\Psr7\Uri::isDefaultPort` 644 645 `public static function isDefaultPort(UriInterface $uri): bool` 646 647 Whether the URI has the default port of the current scheme. `Psr\Http\Message\UriInterface::getPort` may return null 648 or 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 654 Composes 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 656 manually 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 662 Creates a URI from a hash of [`parse_url`](https://www.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 669 Creates a new URI with a specific query string value. Any existing query string values that exactly match the 670 provided key are removed and replaced with the given key value pair. A value of null will set the query string 671 key 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 677 Creates a new URI with multiple query string values. It has the same behavior as `withQueryValue()` but for an 678 associative array of key => value. 679 680 ### `GuzzleHttp\Psr7\Uri::withoutQueryValue` 681 682 `public static function withoutQueryValue(UriInterface $uri, $key): UriInterface` 683 684 Creates a new URI with a specific query string value removed. Any existing query string values that exactly match the 685 provided key are removed. 686 687 ## Cross-Origin Detection 688 689 `GuzzleHttp\Psr7\UriComparator` provides methods to determine if a modified URL should be considered cross-origin. 690 691 ### `GuzzleHttp\Psr7\UriComparator::isCrossOrigin` 692 693 `public static function isCrossOrigin(UriInterface $original, UriInterface $modified): bool` 694 695 Determines if a modified URL should be considered cross-origin with respect to an original URL. 696 697 ## Reference Resolution 698 699 `GuzzleHttp\Psr7\UriResolver` provides methods to resolve a URI reference in the context of a base URI according 700 to [RFC 3986 Section 5](https://tools.ietf.org/html/rfc3986#section-5). This is for example also what web browsers 701 do when resolving a link in a website based on the current request URI. 702 703 ### `GuzzleHttp\Psr7\UriResolver::resolve` 704 705 `public static function resolve(UriInterface $base, UriInterface $rel): UriInterface` 706 707 Converts the relative URI into a new URI that is resolved against the base URI. 708 709 ### `GuzzleHttp\Psr7\UriResolver::removeDotSegments` 710 711 `public static function removeDotSegments(string $path): string` 712 713 Removes dot segments from a path and returns the new path according to 714 [RFC 3986 Section 5.2.4](https://tools.ietf.org/html/rfc3986#section-5.2.4). 715 716 ### `GuzzleHttp\Psr7\UriResolver::relativize` 717 718 `public static function relativize(UriInterface $base, UriInterface $target): UriInterface` 719 720 Returns the target URI as a relative reference from the base URI. This method is the counterpart to resolve(): 721 722 ```php 723 (string) $target === (string) UriResolver::resolve($base, UriResolver::relativize($base, $target)) 724 ``` 725 726 One use-case is to use the current request URI as base URI and then generate relative links in your documents 727 to reduce the document size or offer self-contained downloadable document archives. 728 729 ```php 730 $base = new Uri('http://example.com/a/b/'); 731 echo UriResolver::relativize($base, new Uri('http://example.com/a/b/c')); // prints 'c'. 732 echo UriResolver::relativize($base, new Uri('http://example.com/a/x/y')); // prints '../x/y'. 733 echo UriResolver::relativize($base, new Uri('http://example.com/a/b/?q')); // prints '?q'. 734 echo UriResolver::relativize($base, new Uri('http://example.org/a/b/')); // prints '//example.org/a/b/'. 735 ``` 736 737 ## Normalization and Comparison 738 739 `GuzzleHttp\Psr7\UriNormalizer` provides methods to normalize and compare URIs according to 740 [RFC 3986 Section 6](https://tools.ietf.org/html/rfc3986#section-6). 741 742 ### `GuzzleHttp\Psr7\UriNormalizer::normalize` 743 744 `public static function normalize(UriInterface $uri, $flags = self::PRESERVING_NORMALIZATIONS): UriInterface` 745 746 Returns a normalized URI. The scheme and host component are already normalized to lowercase per PSR-7 UriInterface. 747 This methods adds additional normalizations that can be configured with the `$flags` parameter which is a bitmask 748 of normalizations to apply. The following normalizations are available: 749 750 - `UriNormalizer::PRESERVING_NORMALIZATIONS` 751 752 Default normalizations which only include the ones that preserve semantics. 753 754 - `UriNormalizer::CAPITALIZE_PERCENT_ENCODING` 755 756 All letters within a percent-encoding triplet (e.g., "%3A") are case-insensitive, and should be capitalized. 757 758 Example: `http://example.org/a%c2%b1b` → `http://example.org/a%C2%B1b` 759 760 - `UriNormalizer::DECODE_UNRESERVED_CHARACTERS` 761 762 Decodes percent-encoded octets of unreserved characters. For consistency, percent-encoded octets in the ranges of 763 ALPHA (%41–%5A and %61–%7A), DIGIT (%30–%39), hyphen (%2D), period (%2E), underscore (%5F), or tilde (%7E) should 764 not be created by URI producers and, when found in a URI, should be decoded to their corresponding unreserved 765 characters by URI normalizers. 766 767 Example: `http://example.org/%7Eusern%61me/` → `http://example.org/~username/` 768 769 - `UriNormalizer::CONVERT_EMPTY_PATH` 770 771 Converts the empty path to "/" for http and https URIs. 772 773 Example: `http://example.org` → `http://example.org/` 774 775 - `UriNormalizer::REMOVE_DEFAULT_HOST` 776 777 Removes the default host of the given URI scheme from the URI. Only the "file" scheme defines the default host 778 "localhost". All of `file:/myfile`, `file:///myfile`, and `file://localhost/myfile` are equivalent according to 779 RFC 3986. 780 781 Example: `file://localhost/myfile` → `file:///myfile` 782 783 - `UriNormalizer::REMOVE_DEFAULT_PORT` 784 785 Removes the default port of the given URI scheme from the URI. 786 787 Example: `http://example.org:80/` → `http://example.org/` 788 789 - `UriNormalizer::REMOVE_DOT_SEGMENTS` 790 791 Removes unnecessary dot-segments. Dot-segments in relative-path references are not removed as it would 792 change the semantics of the URI reference. 793 794 Example: `http://example.org/../a/b/../c/./d.html` → `http://example.org/a/c/d.html` 795 796 - `UriNormalizer::REMOVE_DUPLICATE_SLASHES` 797 798 Paths which include two or more adjacent slashes are converted to one. Webservers usually ignore duplicate slashes 799 and treat those URIs equivalent. But in theory those URIs do not need to be equivalent. So this normalization 800 may change the semantics. Encoded slashes (%2F) are not removed. 801 802 Example: `http://example.org//foo///bar.html` → `http://example.org/foo/bar.html` 803 804 - `UriNormalizer::SORT_QUERY_PARAMETERS` 805 806 Sort query parameters with their values in alphabetical order. However, the order of parameters in a URI may be 807 significant (this is not defined by the standard). So this normalization is not safe and may change the semantics 808 of the URI. 809 810 Example: `?lang=en&article=fred` → `?article=fred&lang=en` 811 812 ### `GuzzleHttp\Psr7\UriNormalizer::isEquivalent` 813 814 `public static function isEquivalent(UriInterface $uri1, UriInterface $uri2, $normalizations = self::PRESERVING_NORMALIZATIONS): bool` 815 816 Whether two URIs can be considered equivalent. Both URIs are normalized automatically before comparison with the given 817 `$normalizations` bitmask. The method also accepts relative URI references and returns true when they are equivalent. 818 This of course assumes they will be resolved against the same base URI. If this is not the case, determination of 819 equivalence or difference of relative references does not mean anything. 820 821 822 ## Version Guidance 823 824 | Version | Status | PHP Version | 825 |---------|----------------|------------------| 826 | 1.x | Security fixes | >=5.4,<8.1 | 827 | 2.x | Latest | ^7.2.5 \|\| ^8.0 | 828 829 830 ## Security 831 832 If 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. 833 834 835 ## License 836 837 Guzzle is made available under the MIT License (MIT). Please see [License File](LICENSE) for more information. 838 839 840 ## For Enterprise 841 842 Available as part of the Tidelift Subscription 843 844 The 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)
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Wed Feb 22 20:16:20 2023 | Cross-referenced by PHPXref 0.7.1 |