Verzeichnisstruktur phpBB-3.3.16


Veröffentlicht
27.04.2026

So funktioniert es

Auf das letzte Element klicken. Dies geht jeweils ein Schritt zurück

Auf das Icon klicken, dies öffnet das Verzeichnis. Nochmal klicken schließt das Verzeichnis.
Auf den Verzeichnisnamen klicken, dies zeigt nur das Verzeichnis mit Inhalt an
      (Beispiel Datei-Icons)

Auf das Icon klicken um den Quellcode anzuzeigen

README.md

Zuletzt modifiziert: 01.05.2026, 11:26 - Dateigröße: 27.63 KiB


 001  # PSR-7 Message Implementation
 002   
 003  This repository contains a full [PSR-7](https://www.php-fig.org/psr/psr-7/)
 004  message implementation, several stream decorators, and some helpful
 005  functionality like query string parsing.
 006   
 007   
 008  [![Build Status](https://travis-ci.org/guzzle/psr7.svg?branch=master)](https://travis-ci.org/guzzle/psr7)
 009   
 010   
 011  # Stream implementation
 012   
 013  This package comes with a number of stream implementations and stream
 014  decorators.
 015   
 016   
 017  ## AppendStream
 018   
 019  `GuzzleHttp\Psr7\AppendStream`
 020   
 021  Reads from multiple streams, one after the other.
 022   
 023  ```php
 024  use GuzzleHttp\Psr7;
 025   
 026  $a = Psr7\Utils::streamFor('abc, ');
 027  $b = Psr7\Utils::streamFor('123.');
 028  $composed = new Psr7\AppendStream([$a, $b]);
 029   
 030  $composed->addStream(Psr7\Utils::streamFor(' Above all listen to me'));
 031   
 032  echo $composed; // abc, 123. Above all listen to me.
 033  ```
 034   
 035   
 036  ## BufferStream
 037   
 038  `GuzzleHttp\Psr7\BufferStream`
 039   
 040  Provides a buffer stream that can be written to fill a buffer, and read
 041  from to remove bytes from the buffer.
 042   
 043  This stream returns a "hwm" metadata value that tells upstream consumers
 044  what the configured high water mark of the stream is, or the maximum
 045  preferred size of the buffer.
 046   
 047  ```php
 048  use GuzzleHttp\Psr7;
 049   
 050  // When more than 1024 bytes are in the buffer, it will begin returning
 051  // false to writes. This is an indication that writers should slow down.
 052  $buffer = new Psr7\BufferStream(1024);
 053  ```
 054   
 055   
 056  ## CachingStream
 057   
 058  The CachingStream is used to allow seeking over previously read bytes on
 059  non-seekable streams. This can be useful when transferring a non-seekable
 060  entity body fails due to needing to rewind the stream (for example, resulting
 061  from a redirect). Data that is read from the remote stream will be buffered in
 062  a PHP temp stream so that previously read bytes are cached first in memory,
 063  then on disk.
 064   
 065  ```php
 066  use GuzzleHttp\Psr7;
 067   
 068  $original = Psr7\Utils::streamFor(fopen('http://www.google.com', 'r'));
 069  $stream = new Psr7\CachingStream($original);
 070   
 071  $stream->read(1024);
 072  echo $stream->tell();
 073  // 1024
 074   
 075  $stream->seek(0);
 076  echo $stream->tell();
 077  // 0
 078  ```
 079   
 080   
 081  ## DroppingStream
 082   
 083  `GuzzleHttp\Psr7\DroppingStream`
 084   
 085  Stream decorator that begins dropping data once the size of the underlying
 086  stream becomes too full.
 087   
 088  ```php
 089  use GuzzleHttp\Psr7;
 090   
 091  // Create an empty stream
 092  $stream = Psr7\Utils::streamFor();
 093   
 094  // Start dropping data when the stream has more than 10 bytes
 095  $dropping = new Psr7\DroppingStream($stream, 10);
 096   
 097  $dropping->write('01234567890123456789');
 098  echo $stream; // 0123456789
 099  ```
 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)
 845   

Powered by TreeView® & SyntaxHighlight® PHP-Tools © St. Frank

Verzeichnisstruktur phpBB-3.3.16

Zuletzt modifiziert: 01.05.2026, 11:26 - Dateigröße: 27.63 KiB

README.md


 001  # PSR-7 Message Implementation
 002   
 003  This repository contains a full [PSR-7](https://www.php-fig.org/psr/psr-7/)
 004  message implementation, several stream decorators, and some helpful
 005  functionality like query string parsing.
 006   
 007   
 008  [![Build Status](https://travis-ci.org/guzzle/psr7.svg?branch=master)](https://travis-ci.org/guzzle/psr7)
 009   
 010   
 011  # Stream implementation
 012   
 013  This package comes with a number of stream implementations and stream
 014  decorators.
 015   
 016   
 017  ## AppendStream
 018   
 019  `GuzzleHttp\Psr7\AppendStream`
 020   
 021  Reads from multiple streams, one after the other.
 022   
 023  ```php
 024  use GuzzleHttp\Psr7;
 025   
 026  $a = Psr7\Utils::streamFor('abc, ');
 027  $b = Psr7\Utils::streamFor('123.');
 028  $composed = new Psr7\AppendStream([$a, $b]);
 029   
 030  $composed->addStream(Psr7\Utils::streamFor(' Above all listen to me'));
 031   
 032  echo $composed; // abc, 123. Above all listen to me.
 033  ```
 034   
 035   
 036  ## BufferStream
 037   
 038  `GuzzleHttp\Psr7\BufferStream`
 039   
 040  Provides a buffer stream that can be written to fill a buffer, and read
 041  from to remove bytes from the buffer.
 042   
 043  This stream returns a "hwm" metadata value that tells upstream consumers
 044  what the configured high water mark of the stream is, or the maximum
 045  preferred size of the buffer.
 046   
 047  ```php
 048  use GuzzleHttp\Psr7;
 049   
 050  // When more than 1024 bytes are in the buffer, it will begin returning
 051  // false to writes. This is an indication that writers should slow down.
 052  $buffer = new Psr7\BufferStream(1024);
 053  ```
 054   
 055   
 056  ## CachingStream
 057   
 058  The CachingStream is used to allow seeking over previously read bytes on
 059  non-seekable streams. This can be useful when transferring a non-seekable
 060  entity body fails due to needing to rewind the stream (for example, resulting
 061  from a redirect). Data that is read from the remote stream will be buffered in
 062  a PHP temp stream so that previously read bytes are cached first in memory,
 063  then on disk.
 064   
 065  ```php
 066  use GuzzleHttp\Psr7;
 067   
 068  $original = Psr7\Utils::streamFor(fopen('http://www.google.com', 'r'));
 069  $stream = new Psr7\CachingStream($original);
 070   
 071  $stream->read(1024);
 072  echo $stream->tell();
 073  // 1024
 074   
 075  $stream->seek(0);
 076  echo $stream->tell();
 077  // 0
 078  ```
 079   
 080   
 081  ## DroppingStream
 082   
 083  `GuzzleHttp\Psr7\DroppingStream`
 084   
 085  Stream decorator that begins dropping data once the size of the underlying
 086  stream becomes too full.
 087   
 088  ```php
 089  use GuzzleHttp\Psr7;
 090   
 091  // Create an empty stream
 092  $stream = Psr7\Utils::streamFor();
 093   
 094  // Start dropping data when the stream has more than 10 bytes
 095  $dropping = new Psr7\DroppingStream($stream, 10);
 096   
 097  $dropping->write('01234567890123456789');
 098  echo $stream; // 0123456789
 099  ```
 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)
 845   

Powered by TreeView® & SyntaxHighlight® PHP-Tools © St. Frank