ILIAS  release_5-3 Revision v5.3.23-19-g915713cf615
Static Public Member Functions | Data Fields | Private Member Functions | Static Private Member Functions
GuzzleHttp\Psr7\UriNormalizer Class Reference

Provides methods to normalize and compare URIs. More...

+ Collaboration diagram for GuzzleHttp\Psr7\UriNormalizer:

Static Public Member Functions

static normalize (UriInterface $uri, $flags=self::PRESERVING_NORMALIZATIONS)
 Returns a normalized URI. More...
 
static isEquivalent (UriInterface $uri1, UriInterface $uri2, $normalizations=self::PRESERVING_NORMALIZATIONS)
 Whether two URIs can be considered equivalent. More...
 

Data Fields

const PRESERVING_NORMALIZATIONS = 63
 Default normalizations which only include the ones that preserve semantics. More...
 
const CAPITALIZE_PERCENT_ENCODING = 1
 All letters within a percent-encoding triplet (e.g., "%3A") are case-insensitive, and should be capitalized. More...
 
const DECODE_UNRESERVED_CHARACTERS = 2
 Decodes percent-encoded octets of unreserved characters. More...
 
const CONVERT_EMPTY_PATH = 4
 Converts the empty path to "/" for http and https URIs. More...
 
const REMOVE_DEFAULT_HOST = 8
 Removes the default host of the given URI scheme from the URI. More...
 
const REMOVE_DEFAULT_PORT = 16
 Removes the default port of the given URI scheme from the URI. More...
 
const REMOVE_DOT_SEGMENTS = 32
 Removes unnecessary dot-segments. More...
 
const REMOVE_DUPLICATE_SLASHES = 64
 Paths which include two or more adjacent slashes are converted to one. More...
 
const SORT_QUERY_PARAMETERS = 128
 Sort query parameters with their values in alphabetical order. More...
 

Private Member Functions

 __construct ()
 

Static Private Member Functions

static capitalizePercentEncoding (UriInterface $uri)
 
static decodeUnreservedCharacters (UriInterface $uri)
 

Detailed Description

Provides methods to normalize and compare URIs.

Author
Tobias Schultze

https://tools.ietf.org/html/rfc3986#section-6

Definition at line 13 of file UriNormalizer.php.

Constructor & Destructor Documentation

◆ __construct()

GuzzleHttp\Psr7\UriNormalizer::__construct ( )
private

Definition at line 212 of file UriNormalizer.php.

213  {
214  // cannot be instantiated
215  }

Member Function Documentation

◆ capitalizePercentEncoding()

static GuzzleHttp\Psr7\UriNormalizer::capitalizePercentEncoding ( UriInterface  $uri)
staticprivate

Definition at line 180 of file UriNormalizer.php.

References array, Psr\Http\Message\UriInterface\getPath(), Psr\Http\Message\UriInterface\getQuery(), and Psr\Http\Message\UriInterface\withPath().

181  {
182  $regex = '/(?:%[A-Fa-f0-9]{2})++/';
183 
184  $callback = function (array $match) {
185  return strtoupper($match[0]);
186  };
187 
188  return
189  $uri->withPath(
190  preg_replace_callback($regex, $callback, $uri->getPath())
191  )->withQuery(
192  preg_replace_callback($regex, $callback, $uri->getQuery())
193  );
194  }
array
Create styles array
The data for the language used.
Definition: 40duplicateStyle.php:19
+ Here is the call graph for this function:

◆ decodeUnreservedCharacters()

static GuzzleHttp\Psr7\UriNormalizer::decodeUnreservedCharacters ( UriInterface  $uri)
staticprivate

Definition at line 196 of file UriNormalizer.php.

References array, Psr\Http\Message\UriInterface\getPath(), Psr\Http\Message\UriInterface\getQuery(), and Psr\Http\Message\UriInterface\withPath().

197  {
198  $regex = '/%(?:2D|2E|5F|7E|3[0-9]|[46][1-9A-F]|[57][0-9A])/i';
199 
200  $callback = function (array $match) {
201  return rawurldecode($match[0]);
202  };
203 
204  return
205  $uri->withPath(
206  preg_replace_callback($regex, $callback, $uri->getPath())
207  )->withQuery(
208  preg_replace_callback($regex, $callback, $uri->getQuery())
209  );
210  }
array
Create styles array
The data for the language used.
Definition: 40duplicateStyle.php:19
+ Here is the call graph for this function:

◆ isEquivalent()

static GuzzleHttp\Psr7\UriNormalizer::isEquivalent ( UriInterface  $uri1,
UriInterface  $uri2,
  $normalizations = self::PRESERVING_NORMALIZATIONS 
)
static

Whether two URIs can be considered equivalent.

Both URIs are normalized automatically before comparison with the given $normalizations bitmask. The method also accepts relative URI references and returns true when they are equivalent. This of course assumes they will be resolved against the same base URI. If this is not the case, determination of equivalence or difference of relative references does not mean anything.

Parameters
UriInterface$uri1An URI to compare
UriInterface$uri2An URI to compare
int$normalizationsA bitmask of normalizations to apply, see constants
Returns
bool https://tools.ietf.org/html/rfc3986#section-6.1

Definition at line 175 of file UriNormalizer.php.

References string.

176  {
177  return (string) self::normalize($uri1, $normalizations) === (string) self::normalize($uri2, $normalizations);
178  }
string
Add rich text string
Definition: 05featuredemo.inc.php:117

◆ normalize()

static GuzzleHttp\Psr7\UriNormalizer::normalize ( UriInterface  $uri,
  $flags = self::PRESERVING_NORMALIZATIONS 
)
static

Returns a normalized URI.

The scheme and host component are already normalized to lowercase per PSR-7 UriInterface. This methods adds additional normalizations that can be configured with the $flags parameter.

PSR-7 UriInterface cannot distinguish between an empty component and a missing component as getQuery(), getFragment() etc. always return a string. This means the URIs "/?#" and "/" are treated equivalent which is not necessarily true according to RFC 3986. But that difference is highly uncommon in reality. So this potential normalization is implied in PSR-7 as well.

Parameters
UriInterface$uriThe URI to normalize
int$flagsA bitmask of normalizations to apply, see constants
Returns
UriInterface The normalized URI https://tools.ietf.org/html/rfc3986#section-6.2

Definition at line 119 of file UriNormalizer.php.

References Psr\Http\Message\UriInterface\getHost(), Psr\Http\Message\UriInterface\getPath(), Psr\Http\Message\UriInterface\getPort(), Psr\Http\Message\UriInterface\getQuery(), Psr\Http\Message\UriInterface\getScheme(), GuzzleHttp\Psr7\Uri\isDefaultPort(), GuzzleHttp\Psr7\Uri\isRelativePathReference(), GuzzleHttp\Psr7\UriResolver\removeDotSegments(), Psr\Http\Message\UriInterface\withHost(), Psr\Http\Message\UriInterface\withPath(), Psr\Http\Message\UriInterface\withPort(), and Psr\Http\Message\UriInterface\withQuery().

120  {
121  if ($flags & self::CAPITALIZE_PERCENT_ENCODING) {
122  $uri = self::capitalizePercentEncoding($uri);
123  }
124 
125  if ($flags & self::DECODE_UNRESERVED_CHARACTERS) {
126  $uri = self::decodeUnreservedCharacters($uri);
127  }
128 
129  if ($flags & self::CONVERT_EMPTY_PATH && $uri->getPath() === '' &&
130  ($uri->getScheme() === 'http' || $uri->getScheme() === 'https')
131  ) {
132  $uri = $uri->withPath('/');
133  }
134 
135  if ($flags & self::REMOVE_DEFAULT_HOST && $uri->getScheme() === 'file' && $uri->getHost() === 'localhost') {
136  $uri = $uri->withHost('');
137  }
138 
139  if ($flags & self::REMOVE_DEFAULT_PORT && $uri->getPort() !== null && Uri::isDefaultPort($uri)) {
140  $uri = $uri->withPort(null);
141  }
142 
143  if ($flags & self::REMOVE_DOT_SEGMENTS && !Uri::isRelativePathReference($uri)) {
144  $uri = $uri->withPath(UriResolver::removeDotSegments($uri->getPath()));
145  }
146 
147  if ($flags & self::REMOVE_DUPLICATE_SLASHES) {
148  $uri = $uri->withPath(preg_replace('#//++#', '/', $uri->getPath()));
149  }
150 
151  if ($flags & self::SORT_QUERY_PARAMETERS && $uri->getQuery() !== '') {
152  $queryKeyValues = explode('&', $uri->getQuery());
153  sort($queryKeyValues);
154  $uri = $uri->withQuery(implode('&', $queryKeyValues));
155  }
156 
157  return $uri;
158  }
GuzzleHttp\Psr7\UriResolver\removeDotSegments
static removeDotSegments($path)
Removes dot segments from a path and returns the new path.
Definition: UriResolver.php:23
GuzzleHttp\Psr7\Uri\isRelativePathReference
static isRelativePathReference(UriInterface $uri)
Whether the URI is a relative-path reference.
Definition: Uri.php:222
GuzzleHttp\Psr7\Uri\isDefaultPort
static isDefaultPort(UriInterface $uri)
Whether the URI has the default port of the current scheme.
Definition: Uri.php:150
+ Here is the call graph for this function:

Field Documentation

◆ CAPITALIZE_PERCENT_ENCODING

const GuzzleHttp\Psr7\UriNormalizer::CAPITALIZE_PERCENT_ENCODING = 1

All letters within a percent-encoding triplet (e.g., "%3A") are case-insensitive, and should be capitalized.

Example: http://example.org/a%c2%b1b → http://example.org/a%C2%B1b

Definition at line 28 of file UriNormalizer.php.

◆ CONVERT_EMPTY_PATH

const GuzzleHttp\Psr7\UriNormalizer::CONVERT_EMPTY_PATH = 4

Converts the empty path to "/" for http and https URIs.

Example: http://example.org → http://example.org/

Definition at line 46 of file UriNormalizer.php.

◆ DECODE_UNRESERVED_CHARACTERS

const GuzzleHttp\Psr7\UriNormalizer::DECODE_UNRESERVED_CHARACTERS = 2

Decodes percent-encoded octets of unreserved characters.

For consistency, percent-encoded octets in the ranges of ALPHA (%41–%5A and %61–%7A), DIGIT (%30–%39), hyphen (%2D), period (%2E), underscore (%5F), or tilde (%7E) should not be created by URI producers and, when found in a URI, should be decoded to their corresponding unreserved characters by URI normalizers.

Example: http://example.org/%7Eusern%61me/ → http://example.org/~username/

Definition at line 39 of file UriNormalizer.php.

◆ PRESERVING_NORMALIZATIONS

const GuzzleHttp\Psr7\UriNormalizer::PRESERVING_NORMALIZATIONS = 63

Default normalizations which only include the ones that preserve semantics.

self::CAPITALIZE_PERCENT_ENCODING | self::DECODE_UNRESERVED_CHARACTERS | self::CONVERT_EMPTY_PATH | self::REMOVE_DEFAULT_HOST | self::REMOVE_DEFAULT_PORT | self::REMOVE_DOT_SEGMENTS

Definition at line 21 of file UriNormalizer.php.

◆ REMOVE_DEFAULT_HOST

const GuzzleHttp\Psr7\UriNormalizer::REMOVE_DEFAULT_HOST = 8

Removes the default host of the given URI scheme from the URI.

Only the "file" scheme defines the default host "localhost". All of file:/myfile, file:///myfile, and file://localhost/myfile are equivalent according to RFC 3986. The first format is not accepted by PHPs stream functions and thus already normalized implicitly to the second format in the Uri class. See GuzzleHttp\Psr7\Uri::composeComponents.

Example: file://localhost/myfile → file:///myfile

Definition at line 59 of file UriNormalizer.php.

◆ REMOVE_DEFAULT_PORT

const GuzzleHttp\Psr7\UriNormalizer::REMOVE_DEFAULT_PORT = 16

Removes the default port of the given URI scheme from the URI.

Example: http://example.org:80/ → http://example.org/

Definition at line 66 of file UriNormalizer.php.

◆ REMOVE_DOT_SEGMENTS

const GuzzleHttp\Psr7\UriNormalizer::REMOVE_DOT_SEGMENTS = 32

Removes unnecessary dot-segments.

Dot-segments in relative-path references are not removed as it would change the semantics of the URI reference.

Example: http://example.org/../a/b/../c/./d.html → http://example.org/a/c/d.html

Definition at line 76 of file UriNormalizer.php.

◆ REMOVE_DUPLICATE_SLASHES

const GuzzleHttp\Psr7\UriNormalizer::REMOVE_DUPLICATE_SLASHES = 64

Paths which include two or more adjacent slashes are converted to one.

Webservers usually ignore duplicate slashes and treat those URIs equivalent. But in theory those URIs do not need to be equivalent. So this normalization may change the semantics. Encoded slashes (%2F) are not removed.

Example: http://example.org//foo///bar.html → http://example.org/foo/bar.html

Definition at line 87 of file UriNormalizer.php.

◆ SORT_QUERY_PARAMETERS

const GuzzleHttp\Psr7\UriNormalizer::SORT_QUERY_PARAMETERS = 128

Sort query parameters with their values in alphabetical order.

However, the order of parameters in a URI may be significant (this is not defined by the standard). So this normalization is not safe and may change the semantics of the URI.

Example: ?lang=en&article=fred → ?article=fred&lang=en

Note: The sorting is neither locale nor Unicode aware (the URI query does not get decoded at all) as the purpose is to be able to compare URIs in a reproducible way, not to have the params sorted perfectly.

Definition at line 100 of file UriNormalizer.php.

The documentation for this class was generated from the following file: