| commit | author | age | ||
| 2207d6 | 1 | # PSR-7 Message Implementation |
| W | 2 | |
| 3 | This repository contains a full [PSR-7](http://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\stream_for('abc, '); | |
| 27 | $b = Psr7\stream_for('123.'); | |
| 28 | $composed = new Psr7\AppendStream([$a, $b]); | |
| 29 | ||
| 30 | $composed->addStream(Psr7\stream_for(' 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\stream_for(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\stream_for(); | |
| 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\stream_for('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\stream_for(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\stream_for('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\stream_for('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\stream_for('hello!'); | |
| 301 | $resource = StreamWrapper::getResource($stream); | |
| 302 | echo fread($resource, 6); // outputs hello! | |
| 303 | ``` | |
| 304 | ||
| 305 | ||
| 306 | # Function API | |
| 307 | ||
| 308 | There are various functions available under the `GuzzleHttp\Psr7` namespace. | |
| 309 | ||
| 310 | ||
| 311 | ## `function str` | |
| 312 | ||
| 313 | `function str(MessageInterface $message)` | |
| 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\str($request); | |
| 320 | ``` | |
| 321 | ||
| 322 | ||
| 323 | ## `function uri_for` | |
| 324 | ||
| 325 | `function uri_for($uri)` | |
| 326 | ||
| 327 | This function accepts a string or `Psr\Http\Message\UriInterface` and returns a | |
| 328 | UriInterface for the given value. If the value is already a `UriInterface`, it | |
| 329 | is returned as-is. | |
| 330 | ||
| 331 | ```php | |
| 332 | $uri = GuzzleHttp\Psr7\uri_for('http://example.com'); | |
| 333 | assert($uri === GuzzleHttp\Psr7\uri_for($uri)); | |
| 334 | ``` | |
| 335 | ||
| 336 | ||
| 337 | ## `function stream_for` | |
| 338 | ||
| 339 | `function stream_for($resource = '', array $options = [])` | |
| 340 | ||
| 341 | Create a new stream based on the input type. | |
| 342 | ||
| 343 | Options is an associative array that can contain the following keys: | |
| 344 | ||
| 345 | * - metadata: Array of custom metadata. | |
| 346 | * - size: Size of the stream. | |
| 347 | ||
| 348 | This method accepts the following `$resource` types: | |
| 349 | ||
| 350 | - `Psr\Http\Message\StreamInterface`: Returns the value as-is. | |
| 351 | - `string`: Creates a stream object that uses the given string as the contents. | |
| 352 | - `resource`: Creates a stream object that wraps the given PHP stream resource. | |
| 353 | - `Iterator`: If the provided value implements `Iterator`, then a read-only | |
| 354 | stream object will be created that wraps the given iterable. Each time the | |
| 355 | stream is read from, data from the iterator will fill a buffer and will be | |
| 356 | continuously called until the buffer is equal to the requested read size. | |
| 357 | Subsequent read calls will first read from the buffer and then call `next` | |
| 358 | on the underlying iterator until it is exhausted. | |
| 359 | - `object` with `__toString()`: If the object has the `__toString()` method, | |
| 360 | the object will be cast to a string and then a stream will be returned that | |
| 361 | uses the string value. | |
| 362 | - `NULL`: When `null` is passed, an empty stream object is returned. | |
| 363 | - `callable` When a callable is passed, a read-only stream object will be | |
| 364 | created that invokes the given callable. The callable is invoked with the | |
| 365 | number of suggested bytes to read. The callable can return any number of | |
| 366 | bytes, but MUST return `false` when there is no more data to return. The | |
| 367 | stream object that wraps the callable will invoke the callable until the | |
| 368 | number of requested bytes are available. Any additional bytes will be | |
| 369 | buffered and used in subsequent reads. | |
| 370 | ||
| 371 | ```php | |
| 372 | $stream = GuzzleHttp\Psr7\stream_for('foo'); | |
| 373 | $stream = GuzzleHttp\Psr7\stream_for(fopen('/path/to/file', 'r')); | |
| 374 | ||
| 375 | $generator = function ($bytes) { | |
| 376 | for ($i = 0; $i < $bytes; $i++) { | |
| 377 | yield ' '; | |
| 378 | } | |
| 379 | } | |
| 380 | ||
| 381 | $stream = GuzzleHttp\Psr7\stream_for($generator(100)); | |
| 382 | ``` | |
| 383 | ||
| 384 | ||
| 385 | ## `function parse_header` | |
| 386 | ||
| 387 | `function parse_header($header)` | |
| 388 | ||
| 389 | Parse an array of header values containing ";" separated data into an array of | |
| 390 | associative arrays representing the header key value pair data of the header. | |
| 391 | When a parameter does not contain a value, but just contains a key, this | |
| 392 | function will inject a key with a '' string value. | |
| 393 | ||
| 394 | ||
| 395 | ## `function normalize_header` | |
| 396 | ||
| 397 | `function normalize_header($header)` | |
| 398 | ||
| 399 | Converts an array of header values that may contain comma separated headers | |
| 400 | into an array of headers with no comma separated values. | |
| 401 | ||
| 402 | ||
| 403 | ## `function modify_request` | |
| 404 | ||
| 405 | `function modify_request(RequestInterface $request, array $changes)` | |
| 406 | ||
| 407 | Clone and modify a request with the given changes. This method is useful for | |
| 408 | reducing the number of clones needed to mutate a message. | |
| 409 | ||
| 410 | The changes can be one of: | |
| 411 | ||
| 412 | - method: (string) Changes the HTTP method. | |
| 413 | - set_headers: (array) Sets the given headers. | |
| 414 | - remove_headers: (array) Remove the given headers. | |
| 415 | - body: (mixed) Sets the given body. | |
| 416 | - uri: (UriInterface) Set the URI. | |
| 417 | - query: (string) Set the query string value of the URI. | |
| 418 | - version: (string) Set the protocol version. | |
| 419 | ||
| 420 | ||
| 421 | ## `function rewind_body` | |
| 422 | ||
| 423 | `function rewind_body(MessageInterface $message)` | |
| 424 | ||
| 425 | Attempts to rewind a message body and throws an exception on failure. The body | |
| 426 | of the message will only be rewound if a call to `tell()` returns a value other | |
| 427 | than `0`. | |
| 428 | ||
| 429 | ||
| 430 | ## `function try_fopen` | |
| 431 | ||
| 432 | `function try_fopen($filename, $mode)` | |
| 433 | ||
| 434 | Safely opens a PHP stream resource using a filename. | |
| 435 | ||
| 436 | When fopen fails, PHP normally raises a warning. This function adds an error | |
| 437 | handler that checks for errors and throws an exception instead. | |
| 438 | ||
| 439 | ||
| 440 | ## `function copy_to_string` | |
| 441 | ||
| 442 | `function copy_to_string(StreamInterface $stream, $maxLen = -1)` | |
| 443 | ||
| 444 | Copy the contents of a stream into a string until the given number of bytes | |
| 445 | have been read. | |
| 446 | ||
| 447 | ||
| 448 | ## `function copy_to_stream` | |
| 449 | ||
| 450 | `function copy_to_stream(StreamInterface $source, StreamInterface $dest, $maxLen = -1)` | |
| 451 | ||
| 452 | Copy the contents of a stream into another stream until the given number of | |
| 453 | bytes have been read. | |
| 454 | ||
| 455 | ||
| 456 | ## `function hash` | |
| 457 | ||
| 458 | `function hash(StreamInterface $stream, $algo, $rawOutput = false)` | |
| 459 | ||
| 460 | Calculate a hash of a Stream. This method reads the entire stream to calculate | |
| 461 | a rolling hash (based on PHP's hash_init functions). | |
| 462 | ||
| 463 | ||
| 464 | ## `function readline` | |
| 465 | ||
| 466 | `function readline(StreamInterface $stream, $maxLength = null)` | |
| 467 | ||
| 468 | Read a line from the stream up to the maximum allowed buffer length. | |
| 469 | ||
| 470 | ||
| 471 | ## `function parse_request` | |
| 472 | ||
| 473 | `function parse_request($message)` | |
| 474 | ||
| 475 | Parses a request message string into a request object. | |
| 476 | ||
| 477 | ||
| 478 | ## `function parse_response` | |
| 479 | ||
| 480 | `function parse_response($message)` | |
| 481 | ||
| 482 | Parses a response message string into a response object. | |
| 483 | ||
| 484 | ||
| 485 | ## `function parse_query` | |
| 486 | ||
| 487 | `function parse_query($str, $urlEncoding = true)` | |
| 488 | ||
| 489 | Parse a query string into an associative array. | |
| 490 | ||
| 491 | If multiple values are found for the same key, the value of that key value pair | |
| 492 | will become an array. This function does not parse nested PHP style arrays into | |
| 493 | an associative array (e.g., `foo[a]=1&foo[b]=2` will be parsed into | |
| 494 | `['foo[a]' => '1', 'foo[b]' => '2']`). | |
| 495 | ||
| 496 | ||
| 497 | ## `function build_query` | |
| 498 | ||
| 499 | `function build_query(array $params, $encoding = PHP_QUERY_RFC3986)` | |
| 500 | ||
| 501 | Build a query string from an array of key value pairs. | |
| 502 | ||
| 503 | This function can use the return value of parse_query() to build a query string. | |
| 504 | This function does not modify the provided keys when an array is encountered | |
| 505 | (like http_build_query would). | |
| 506 | ||
| 507 | ||
| 508 | ## `function mimetype_from_filename` | |
| 509 | ||
| 510 | `function mimetype_from_filename($filename)` | |
| 511 | ||
| 512 | Determines the mimetype of a file by looking at its extension. | |
| 513 | ||
| 514 | ||
| 515 | ## `function mimetype_from_extension` | |
| 516 | ||
| 517 | `function mimetype_from_extension($extension)` | |
| 518 | ||
| 519 | Maps a file extensions to a mimetype. | |
| 520 | ||
| 521 | ||
| 522 | # Additional URI Methods | |
| 523 | ||
| 524 | Aside from the standard `Psr\Http\Message\UriInterface` implementation in form of the `GuzzleHttp\Psr7\Uri` class, | |
| 525 | this library also provides additional functionality when working with URIs as static methods. | |
| 526 | ||
| 527 | ## URI Types | |
| 528 | ||
| 529 | An instance of `Psr\Http\Message\UriInterface` can either be an absolute URI or a relative reference. | |
| 530 | An absolute URI has a scheme. A relative reference is used to express a URI relative to another URI, | |
| 531 | the base URI. Relative references can be divided into several forms according to | |
| 532 | [RFC 3986 Section 4.2](https://tools.ietf.org/html/rfc3986#section-4.2): | |
| 533 | ||
| 534 | - network-path references, e.g. `//example.com/path` | |
| 535 | - absolute-path references, e.g. `/path` | |
| 536 | - relative-path references, e.g. `subpath` | |
| 537 | ||
| 538 | The following methods can be used to identify the type of the URI. | |
| 539 | ||
| 540 | ### `GuzzleHttp\Psr7\Uri::isAbsolute` | |
| 541 | ||
| 542 | `public static function isAbsolute(UriInterface $uri): bool` | |
| 543 | ||
| 544 | Whether the URI is absolute, i.e. it has a scheme. | |
| 545 | ||
| 546 | ### `GuzzleHttp\Psr7\Uri::isNetworkPathReference` | |
| 547 | ||
| 548 | `public static function isNetworkPathReference(UriInterface $uri): bool` | |
| 549 | ||
| 550 | Whether the URI is a network-path reference. A relative reference that begins with two slash characters is | |
| 551 | termed an network-path reference. | |
| 552 | ||
| 553 | ### `GuzzleHttp\Psr7\Uri::isAbsolutePathReference` | |
| 554 | ||
| 555 | `public static function isAbsolutePathReference(UriInterface $uri): bool` | |
| 556 | ||
| 557 | Whether the URI is a absolute-path reference. A relative reference that begins with a single slash character is | |
| 558 | termed an absolute-path reference. | |
| 559 | ||
| 560 | ### `GuzzleHttp\Psr7\Uri::isRelativePathReference` | |
| 561 | ||
| 562 | `public static function isRelativePathReference(UriInterface $uri): bool` | |
| 563 | ||
| 564 | Whether the URI is a relative-path reference. A relative reference that does not begin with a slash character is | |
| 565 | termed a relative-path reference. | |
| 566 | ||
| 567 | ### `GuzzleHttp\Psr7\Uri::isSameDocumentReference` | |
| 568 | ||
| 569 | `public static function isSameDocumentReference(UriInterface $uri, UriInterface $base = null): bool` | |
| 570 | ||
| 571 | Whether the URI is a same-document reference. A same-document reference refers to a URI that is, aside from its | |
| 572 | fragment component, identical to the base URI. When no base URI is given, only an empty URI reference | |
| 573 | (apart from its fragment) is considered a same-document reference. | |
| 574 | ||
| 575 | ## URI Components | |
| 576 | ||
| 577 | Additional methods to work with URI components. | |
| 578 | ||
| 579 | ### `GuzzleHttp\Psr7\Uri::isDefaultPort` | |
| 580 | ||
| 581 | `public static function isDefaultPort(UriInterface $uri): bool` | |
| 582 | ||
| 583 | Whether the URI has the default port of the current scheme. `Psr\Http\Message\UriInterface::getPort` may return null | |
| 584 | or the standard port. This method can be used independently of the implementation. | |
| 585 | ||
| 586 | ### `GuzzleHttp\Psr7\Uri::composeComponents` | |
| 587 | ||
| 588 | `public static function composeComponents($scheme, $authority, $path, $query, $fragment): string` | |
| 589 | ||
| 590 | Composes a URI reference string from its various components according to | |
| 591 | [RFC 3986 Section 5.3](https://tools.ietf.org/html/rfc3986#section-5.3). Usually this method does not need to be called | |
| 592 | manually but instead is used indirectly via `Psr\Http\Message\UriInterface::__toString`. | |
| 593 | ||
| 594 | ### `GuzzleHttp\Psr7\Uri::fromParts` | |
| 595 | ||
| 596 | `public static function fromParts(array $parts): UriInterface` | |
| 597 | ||
| 598 | Creates a URI from a hash of [`parse_url`](http://php.net/manual/en/function.parse-url.php) components. | |
| 599 | ||
| 600 | ||
| 601 | ### `GuzzleHttp\Psr7\Uri::withQueryValue` | |
| 602 | ||
| 603 | `public static function withQueryValue(UriInterface $uri, $key, $value): UriInterface` | |
| 604 | ||
| 605 | Creates a new URI with a specific query string value. Any existing query string values that exactly match the | |
| 606 | provided key are removed and replaced with the given key value pair. A value of null will set the query string | |
| 607 | key without a value, e.g. "key" instead of "key=value". | |
| 608 | ||
| 609 | ### `GuzzleHttp\Psr7\Uri::withQueryValues` | |
| 610 | ||
| 611 | `public static function withQueryValues(UriInterface $uri, array $keyValueArray): UriInterface` | |
| 612 | ||
| 613 | Creates a new URI with multiple query string values. It has the same behavior as `withQueryValue()` but for an | |
| 614 | associative array of key => value. | |
| 615 | ||
| 616 | ### `GuzzleHttp\Psr7\Uri::withoutQueryValue` | |
| 617 | ||
| 618 | `public static function withoutQueryValue(UriInterface $uri, $key): UriInterface` | |
| 619 | ||
| 620 | Creates a new URI with a specific query string value removed. Any existing query string values that exactly match the | |
| 621 | provided key are removed. | |
| 622 | ||
| 623 | ## Reference Resolution | |
| 624 | ||
| 625 | `GuzzleHttp\Psr7\UriResolver` provides methods to resolve a URI reference in the context of a base URI according | |
| 626 | to [RFC 3986 Section 5](https://tools.ietf.org/html/rfc3986#section-5). This is for example also what web browsers | |
| 627 | do when resolving a link in a website based on the current request URI. | |
| 628 | ||
| 629 | ### `GuzzleHttp\Psr7\UriResolver::resolve` | |
| 630 | ||
| 631 | `public static function resolve(UriInterface $base, UriInterface $rel): UriInterface` | |
| 632 | ||
| 633 | Converts the relative URI into a new URI that is resolved against the base URI. | |
| 634 | ||
| 635 | ### `GuzzleHttp\Psr7\UriResolver::removeDotSegments` | |
| 636 | ||
| 637 | `public static function removeDotSegments(string $path): string` | |
| 638 | ||
| 639 | Removes dot segments from a path and returns the new path according to | |
| 640 | [RFC 3986 Section 5.2.4](https://tools.ietf.org/html/rfc3986#section-5.2.4). | |
| 641 | ||
| 642 | ### `GuzzleHttp\Psr7\UriResolver::relativize` | |
| 643 | ||
| 644 | `public static function relativize(UriInterface $base, UriInterface $target): UriInterface` | |
| 645 | ||
| 646 | Returns the target URI as a relative reference from the base URI. This method is the counterpart to resolve(): | |
| 647 | ||
| 648 | ```php | |
| 649 | (string) $target === (string) UriResolver::resolve($base, UriResolver::relativize($base, $target)) | |
| 650 | ``` | |
| 651 | ||
| 652 | One use-case is to use the current request URI as base URI and then generate relative links in your documents | |
| 653 | to reduce the document size or offer self-contained downloadable document archives. | |
| 654 | ||
| 655 | ```php | |
| 656 | $base = new Uri('http://example.com/a/b/'); | |
| 657 | echo UriResolver::relativize($base, new Uri('http://example.com/a/b/c')); // prints 'c'. | |
| 658 | echo UriResolver::relativize($base, new Uri('http://example.com/a/x/y')); // prints '../x/y'. | |
| 659 | echo UriResolver::relativize($base, new Uri('http://example.com/a/b/?q')); // prints '?q'. | |
| 660 | echo UriResolver::relativize($base, new Uri('http://example.org/a/b/')); // prints '//example.org/a/b/'. | |
| 661 | ``` | |
| 662 | ||
| 663 | ## Normalization and Comparison | |
| 664 | ||
| 665 | `GuzzleHttp\Psr7\UriNormalizer` provides methods to normalize and compare URIs according to | |
| 666 | [RFC 3986 Section 6](https://tools.ietf.org/html/rfc3986#section-6). | |
| 667 | ||
| 668 | ### `GuzzleHttp\Psr7\UriNormalizer::normalize` | |
| 669 | ||
| 670 | `public static function normalize(UriInterface $uri, $flags = self::PRESERVING_NORMALIZATIONS): UriInterface` | |
| 671 | ||
| 672 | Returns a normalized URI. The scheme and host component are already normalized to lowercase per PSR-7 UriInterface. | |
| 673 | This methods adds additional normalizations that can be configured with the `$flags` parameter which is a bitmask | |
| 674 | of normalizations to apply. The following normalizations are available: | |
| 675 | ||
| 676 | - `UriNormalizer::PRESERVING_NORMALIZATIONS` | |
| 677 | ||
| 678 | Default normalizations which only include the ones that preserve semantics. | |
| 679 | ||
| 680 | - `UriNormalizer::CAPITALIZE_PERCENT_ENCODING` | |
| 681 | ||
| 682 | All letters within a percent-encoding triplet (e.g., "%3A") are case-insensitive, and should be capitalized. | |
| 683 | ||
| 684 | Example: `http://example.org/a%c2%b1b` → `http://example.org/a%C2%B1b` | |
| 685 | ||
| 686 | - `UriNormalizer::DECODE_UNRESERVED_CHARACTERS` | |
| 687 | ||
| 688 | Decodes percent-encoded octets of unreserved characters. For consistency, percent-encoded octets in the ranges of | |
| 689 | ALPHA (%41–%5A and %61–%7A), DIGIT (%30–%39), hyphen (%2D), period (%2E), underscore (%5F), or tilde (%7E) should | |
| 690 | not be created by URI producers and, when found in a URI, should be decoded to their corresponding unreserved | |
| 691 | characters by URI normalizers. | |
| 692 | ||
| 693 | Example: `http://example.org/%7Eusern%61me/` → `http://example.org/~username/` | |
| 694 | ||
| 695 | - `UriNormalizer::CONVERT_EMPTY_PATH` | |
| 696 | ||
| 697 | Converts the empty path to "/" for http and https URIs. | |
| 698 | ||
| 699 | Example: `http://example.org` → `http://example.org/` | |
| 700 | ||
| 701 | - `UriNormalizer::REMOVE_DEFAULT_HOST` | |
| 702 | ||
| 703 | Removes the default host of the given URI scheme from the URI. Only the "file" scheme defines the default host | |
| 704 | "localhost". All of `file:/myfile`, `file:///myfile`, and `file://localhost/myfile` are equivalent according to | |
| 705 | RFC 3986. | |
| 706 | ||
| 707 | Example: `file://localhost/myfile` → `file:///myfile` | |
| 708 | ||
| 709 | - `UriNormalizer::REMOVE_DEFAULT_PORT` | |
| 710 | ||
| 711 | Removes the default port of the given URI scheme from the URI. | |
| 712 | ||
| 713 | Example: `http://example.org:80/` → `http://example.org/` | |
| 714 | ||
| 715 | - `UriNormalizer::REMOVE_DOT_SEGMENTS` | |
| 716 | ||
| 717 | Removes unnecessary dot-segments. Dot-segments in relative-path references are not removed as it would | |
| 718 | change the semantics of the URI reference. | |
| 719 | ||
| 720 | Example: `http://example.org/../a/b/../c/./d.html` → `http://example.org/a/c/d.html` | |
| 721 | ||
| 722 | - `UriNormalizer::REMOVE_DUPLICATE_SLASHES` | |
| 723 | ||
| 724 | Paths which include two or more adjacent slashes are converted to one. Webservers usually ignore duplicate slashes | |
| 725 | and treat those URIs equivalent. But in theory those URIs do not need to be equivalent. So this normalization | |
| 726 | may change the semantics. Encoded slashes (%2F) are not removed. | |
| 727 | ||
| 728 | Example: `http://example.org//foo///bar.html` → `http://example.org/foo/bar.html` | |
| 729 | ||
| 730 | - `UriNormalizer::SORT_QUERY_PARAMETERS` | |
| 731 | ||
| 732 | Sort query parameters with their values in alphabetical order. However, the order of parameters in a URI may be | |
| 733 | significant (this is not defined by the standard). So this normalization is not safe and may change the semantics | |
| 734 | of the URI. | |
| 735 | ||
| 736 | Example: `?lang=en&article=fred` → `?article=fred&lang=en` | |
| 737 | ||
| 738 | ### `GuzzleHttp\Psr7\UriNormalizer::isEquivalent` | |
| 739 | ||
| 740 | `public static function isEquivalent(UriInterface $uri1, UriInterface $uri2, $normalizations = self::PRESERVING_NORMALIZATIONS): bool` | |
| 741 | ||
| 742 | Whether two URIs can be considered equivalent. Both URIs are normalized automatically before comparison with the given | |
| 743 | `$normalizations` bitmask. The method also accepts relative URI references and returns true when they are equivalent. | |
| 744 | This of course assumes they will be resolved against the same base URI. If this is not the case, determination of | |
| 745 | equivalence or difference of relative references does not mean anything. | |
