[ Index ]

PHP Cross Reference of phpBB-3.3.14-deutsch

title

Body

[close]

/vendor/guzzlehttp/psr7/ -> README.md (source)

   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  [![Build Status](https://travis-ci.org/guzzle/psr7.svg?branch=master)](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)


Generated: Mon Nov 25 19:05:08 2024 Cross-referenced by PHPXref 0.7.1