Verzeichnisstruktur phpBB-3.3.15
- Veröffentlicht
- 28.08.2024
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. |
|
|
(Beispiel Datei-Icons)
|
Auf das Icon klicken um den Quellcode anzuzeigen |
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 [](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