From c64eab86d05bbb12f5d122fc500af9417b532440 Mon Sep 17 00:00:00 2001 From: ignace namagana butera Date: Wed, 29 Jan 2020 16:09:41 +0100 Subject: [PATCH] Improve docblocks --- src/Http.php | 3 +-- src/Uri.php | 40 ++++++++++++++-------------- src/UriInfo.php | 5 ++-- src/UriResolver.php | 9 +++---- src/UriString.php | 63 ++++++++++++++++++++++++++++----------------- src/UriTemplate.php | 31 +++++++++++++++++++--- 6 files changed, 93 insertions(+), 58 deletions(-) diff --git a/src/Http.php b/src/Http.php index 0f9b018f..2307d653 100644 --- a/src/Http.php +++ b/src/Http.php @@ -13,7 +13,6 @@ namespace League\Uri; -use JsonSerializable; use League\Uri\Contracts\UriInterface; use League\Uri\Exceptions\SyntaxError; use Psr\Http\Message\UriInterface as Psr7UriInterface; @@ -21,7 +20,7 @@ use function method_exists; use function sprintf; -final class Http implements Psr7UriInterface, JsonSerializable +final class Http implements Psr7UriInterface, \JsonSerializable { /** * @var UriInterface diff --git a/src/Uri.php b/src/Uri.php index 19a85060..7ebdd1cd 100644 --- a/src/Uri.php +++ b/src/Uri.php @@ -13,12 +13,10 @@ namespace League\Uri; -use finfo; use League\Uri\Contracts\UriInterface; use League\Uri\Exceptions\IdnSupportMissing; use League\Uri\Exceptions\SyntaxError; use Psr\Http\Message\UriInterface as Psr7UriInterface; -use TypeError; use function array_filter; use function array_map; use function base64_decode; @@ -76,7 +74,7 @@ final class Uri implements UriInterface /** * RFC3986 invalid characters. * - * @see https://tools.ietf.org/html/rfc3986#section-2.2 + * @link https://tools.ietf.org/html/rfc3986#section-2.2 * * @var string */ @@ -85,7 +83,7 @@ final class Uri implements UriInterface /** * RFC3986 Sub delimiter characters regular expression pattern. * - * @see https://tools.ietf.org/html/rfc3986#section-2.2 + * @link https://tools.ietf.org/html/rfc3986#section-2.2 * * @var string */ @@ -94,7 +92,7 @@ final class Uri implements UriInterface /** * RFC3986 unreserved characters regular expression pattern. * - * @see https://tools.ietf.org/html/rfc3986#section-2.3 + * @link https://tools.ietf.org/html/rfc3986#section-2.3 * * @var string */ @@ -103,14 +101,14 @@ final class Uri implements UriInterface /** * RFC3986 schema regular expression pattern. * - * @see https://tools.ietf.org/html/rfc3986#section-3.1 + * @link https://tools.ietf.org/html/rfc3986#section-3.1 */ private const REGEXP_SCHEME = ',^[a-z]([-a-z0-9+.]+)?$,i'; /** * RFC3986 host identified by a registered name regular expression pattern. * - * @see https://tools.ietf.org/html/rfc3986#section-3.2.2 + * @link https://tools.ietf.org/html/rfc3986#section-3.2.2 */ private const REGEXP_HOST_REGNAME = '/^( (?[a-z0-9_~\-\.])| @@ -121,14 +119,14 @@ final class Uri implements UriInterface /** * RFC3986 delimiters of the generic URI components regular expression pattern. * - * @see https://tools.ietf.org/html/rfc3986#section-2.2 + * @link https://tools.ietf.org/html/rfc3986#section-2.2 */ private const REGEXP_HOST_GEN_DELIMS = '/[:\/?#\[\]@ ]/'; // Also includes space. /** * RFC3986 IPvFuture regular expression pattern. * - * @see https://tools.ietf.org/html/rfc3986#section-3.2.2 + * @link https://tools.ietf.org/html/rfc3986#section-3.2.2 */ private const REGEXP_HOST_IPFUTURE = '/^ v(?[A-F0-9])+\. @@ -151,14 +149,14 @@ final class Uri implements UriInterface /** * Mimetype regular expression pattern. * - * @see https://tools.ietf.org/html/rfc2397 + * @link https://tools.ietf.org/html/rfc2397 */ private const REGEXP_MIMETYPE = ',^\w+/[-.\w]+(?:\+[-.\w]+)?$,'; /** * Base64 content regular expression pattern. * - * @see https://tools.ietf.org/html/rfc2397 + * @link https://tools.ietf.org/html/rfc2397 */ private const REGEXP_BINARY = ',(;|^)base64$,'; @@ -452,7 +450,7 @@ private function formatRegisteredName(string $host): string /** * Retrieves and format IDNA conversion error message. * - * @see http://icu-project.org/apiref/icu4j/com/ibm/icu/text/IDNA.Error.html + * @link http://icu-project.org/apiref/icu4j/com/ibm/icu/text/IDNA.Error.html */ private function getIDNAErrors(int $error_byte): string { @@ -689,7 +687,7 @@ public static function createFromDataPath(string $path, $context = null): self throw new SyntaxError(sprintf('The file `%s` does not exist or is not readable', $path)); } - $mimetype = (string) (new finfo(FILEINFO_MIME))->file(...$mime_args); + $mimetype = (string) (new \finfo(FILEINFO_MIME))->file(...$mime_args); return Uri::createFromComponents([ 'scheme' => 'data', @@ -766,7 +764,7 @@ public static function createFromUri($uri): self } if (!$uri instanceof Psr7UriInterface) { - throw new TypeError(sprintf('The object must implement the `%s` or the `%s`', Psr7UriInterface::class, UriInterface::class)); + throw new \TypeError(sprintf('The object must implement the `%s` or the `%s`', Psr7UriInterface::class, UriInterface::class)); } $scheme = $uri->getScheme(); @@ -965,7 +963,7 @@ private function formatPath(string $path): string /** * Filter the Path component. * - * @see https://tools.ietf.org/html/rfc2397 + * @link https://tools.ietf.org/html/rfc2397 * * @throws SyntaxError If the path is not compliant with RFC2397 */ @@ -1004,7 +1002,7 @@ private function formatDataPath(string $path): string /** * Assert the path is a compliant with RFC2397. * - * @see https://tools.ietf.org/html/rfc2397 + * @link https://tools.ietf.org/html/rfc2397 * * @throws SyntaxError If the mediatype or the data are not compliant with the RFC2397 */ @@ -1085,8 +1083,8 @@ private function formatQueryAndFragment(?string $component): ?string /** * assert the URI internal state is valid. * - * @see https://tools.ietf.org/html/rfc3986#section-3 - * @see https://tools.ietf.org/html/rfc3986#section-3.3 + * @link https://tools.ietf.org/html/rfc3986#section-3 + * @link https://tools.ietf.org/html/rfc3986#section-3.3 * * @throws SyntaxError if the URI is in an invalid state according to RFC3986 * @throws SyntaxError if the URI is in an invalid state according to scheme specific rules @@ -1172,7 +1170,7 @@ private function isNonEmptyHostUriWithoutFragmentAndQuery(): bool /** * Generate the URI string representation from its components. * - * @see https://tools.ietf.org/html/rfc3986#section-5.3 + * @link https://tools.ietf.org/html/rfc3986#section-5.3 * * @param ?string $scheme * @param ?string $authority @@ -1344,7 +1342,7 @@ private function filterString($str): ?string } if (!is_scalar($str) && !method_exists($str, '__toString')) { - throw new TypeError(sprintf('The component must be a string, a scalar or a stringable object %s given', gettype($str))); + throw new \TypeError(sprintf('The component must be a string, a scalar or a stringable object %s given', gettype($str))); } $str = (string) $str; @@ -1425,7 +1423,7 @@ public function withPath($path): UriInterface { $path = $this->filterString($path); if (null === $path) { - throw new TypeError('A path must be a string NULL given'); + throw new \TypeError('A path must be a string NULL given'); } $path = $this->formatPath($path); diff --git a/src/UriInfo.php b/src/UriInfo.php index 1939f900..4e4ad7c7 100644 --- a/src/UriInfo.php +++ b/src/UriInfo.php @@ -15,7 +15,6 @@ use League\Uri\Contracts\UriInterface; use Psr\Http\Message\UriInterface as Psr7UriInterface; -use TypeError; use function explode; use function implode; use function preg_replace_callback; @@ -42,7 +41,7 @@ private function __construct() * * @param mixed $uri the URI to validate * - * @throws TypeError if the URI object does not implements the supported interfaces. + * @throws \TypeError if the URI object does not implements the supported interfaces. * * @return Psr7UriInterface|UriInterface */ @@ -52,7 +51,7 @@ private static function filterUri($uri) return $uri; } - throw new TypeError(sprintf('The uri must be a valid URI object received `%s`', is_object($uri) ? get_class($uri) : gettype($uri))); + throw new \TypeError(sprintf('The uri must be a valid URI object received `%s`', is_object($uri) ? get_class($uri) : gettype($uri))); } /** diff --git a/src/UriResolver.php b/src/UriResolver.php index 7a817d7a..7c34dbef 100644 --- a/src/UriResolver.php +++ b/src/UriResolver.php @@ -15,7 +15,6 @@ use League\Uri\Contracts\UriInterface; use Psr\Http\Message\UriInterface as Psr7UriInterface; -use TypeError; use function array_pop; use function array_reduce; use function count; @@ -32,7 +31,7 @@ final class UriResolver { /** - * @var array + * @var array */ const DOT_SEGMENTS = ['.' => 1, '..' => 1]; @@ -95,12 +94,12 @@ public static function resolve($uri, $base_uri) * * @param mixed $uri an URI object * - * @throws TypeError if the URI object does not implements the supported interfaces. + * @throws \TypeError if the URI object does not implements the supported interfaces. */ private static function filterUri($uri): void { if (!$uri instanceof UriInterface && !$uri instanceof Psr7UriInterface) { - throw new TypeError(sprintf('The uri must be a valid URI object received `%s`', gettype($uri))); + throw new \TypeError(sprintf('The uri must be a valid URI object received `%s`', gettype($uri))); } } @@ -273,7 +272,7 @@ private static function getComponent(string $method, $uri): ?string * * @param null|mixed $uri * - * @throws TypeError if the URI object does not implements the supported interfaces. + * @throws \TypeError if the URI object does not implements the supported interfaces. * * @return Psr7UriInterface|UriInterface */ diff --git a/src/UriString.php b/src/UriString.php index d5f67306..6e0987f0 100644 --- a/src/UriString.php +++ b/src/UriString.php @@ -15,7 +15,6 @@ use League\Uri\Exceptions\IdnSupportMissing; use League\Uri\Exceptions\SyntaxError; -use TypeError; use function array_merge; use function defined; use function explode; @@ -52,10 +51,10 @@ /** * A class to parse a URI string according to RFC3986. * - * @see https://tools.ietf.org/html/rfc3986 + * @link https://tools.ietf.org/html/rfc3986 * @package League\Uri * @author Ignace Nyamagana Butera - * @since 0.1.0 + * @since 6.0.0 */ final class UriString { @@ -87,7 +86,7 @@ final class UriString /** * RFC3986 regular expression URI splitter. * - * @see https://tools.ietf.org/html/rfc3986#appendix-B + * @link https://tools.ietf.org/html/rfc3986#appendix-B */ private const REGEXP_URI_PARTS = ',^ (?(?[^:/?\#]+):)? # URI scheme component @@ -100,14 +99,14 @@ final class UriString /** * URI scheme regular expresssion. * - * @see https://tools.ietf.org/html/rfc3986#section-3.1 + * @link https://tools.ietf.org/html/rfc3986#section-3.1 */ private const REGEXP_URI_SCHEME = '/^([a-z][a-z\d\+\.\-]*)?$/i'; /** * IPvFuture regular expression. * - * @see https://tools.ietf.org/html/rfc3986#section-3.2.2 + * @link https://tools.ietf.org/html/rfc3986#section-3.2.2 */ private const REGEXP_IP_FUTURE = '/^ v(?[A-F0-9])+\. @@ -120,7 +119,7 @@ final class UriString /** * General registered name regular expression. * - * @see https://tools.ietf.org/html/rfc3986#section-3.2.2 + * @link https://tools.ietf.org/html/rfc3986#section-3.2.2 */ private const REGEXP_REGISTERED_NAME = '/(?(DEFINE) (?[a-z0-9_~\-]) # . is missing as it is used to separate labels @@ -133,7 +132,7 @@ final class UriString /** * Invalid characters in host regular expression. * - * @see https://tools.ietf.org/html/rfc3986#section-3.2.2 + * @link https://tools.ietf.org/html/rfc3986#section-3.2.2 */ private const REGEXP_INVALID_HOST_CHARS = '/ [:\/?#\[\]@ ] # gen-delims characters as well as the space character @@ -142,7 +141,7 @@ final class UriString /** * Invalid path for URI without scheme and authority regular expression. * - * @see https://tools.ietf.org/html/rfc3986#section-3.3 + * @link https://tools.ietf.org/html/rfc3986#section-3.3 */ private const REGEXP_INVALID_PATH = ',^(([^/]*):)(.*)?/,'; @@ -169,10 +168,19 @@ final class UriString * If you supply your own array, you are responsible for providing * valid components without their URI delimiters. * - * @see https://tools.ietf.org/html/rfc3986#section-5.3 - * @see https://tools.ietf.org/html/rfc3986#section-7.5 + * @link https://tools.ietf.org/html/rfc3986#section-5.3 + * @link https://tools.ietf.org/html/rfc3986#section-7.5 * - * @param array{scheme:?string, user:?string, pass:?string, host:?string, port:?int, path:string, query:?string, fragment:?string} $components + * @param array{ + * scheme:?string, + * user:?string, + * pass:?string, + * host:?string, + * port:?int, + * path:string, + * query:?string, + * fragment:?string + * } $components */ public static function build(array $components): string { @@ -246,7 +254,7 @@ public static function build(array $components): string * required to validate the returned components against its related scheme specific rules. * * - * @see https://tools.ietf.org/html/rfc3986 + * @link https://tools.ietf.org/html/rfc3986 * * @param mixed $uri any scalar or stringable object * @@ -254,12 +262,21 @@ public static function build(array $components): string * @throws SyntaxError if the URI contains an invalid scheme * @throws SyntaxError if the URI contains an invalid path * - * @return array{scheme:?string, user:?string, pass:?string, host:?string, port:?int, path:string, query:?string, fragment:?string} + * @return array{ + * scheme:?string, + * user:?string, + * pass:?string, + * host:?string, + * port:?int, + * path:string, + * query:?string, + * fragment:?string + * } */ public static function parse($uri): array { if (!is_scalar($uri) && !method_exists($uri, '__toString')) { - throw new TypeError(sprintf('The uri must be a scalar or a stringable object `%s` given', gettype($uri))); + throw new \TypeError(sprintf('The uri must be a scalar or a stringable object `%s` given', gettype($uri))); } $uri = (string) $uri; @@ -328,7 +345,7 @@ public static function parse($uri): array /** * Parses the URI authority part. * - * @see https://tools.ietf.org/html/rfc3986#section-3.2 + * @link https://tools.ietf.org/html/rfc3986#section-3.2 * * @throws SyntaxError If the port component is invalid * @@ -358,7 +375,7 @@ private static function parseAuthority(string $authority): array /** * Filter and format the port component. * - * @see https://tools.ietf.org/html/rfc3986#section-3.2.2 + * @link https://tools.ietf.org/html/rfc3986#section-3.2.2 * * @throws SyntaxError if the registered name is invalid */ @@ -378,7 +395,7 @@ private static function filterPort(string $port): ?int /** * Returns whether a hostname is valid. * - * @see https://tools.ietf.org/html/rfc3986#section-3.2.2 + * @link https://tools.ietf.org/html/rfc3986#section-3.2.2 * * @throws SyntaxError if the registered name is invalid */ @@ -402,7 +419,7 @@ private static function filterHost(string $host): string /** * Returns whether the host is an IPv4 or a registered named. * - * @see https://tools.ietf.org/html/rfc3986#section-3.2.2 + * @link https://tools.ietf.org/html/rfc3986#section-3.2.2 * * @throws SyntaxError if the registered name is invalid * @throws IdnSupportMissing if IDN support or ICU requirement are not available or met. @@ -479,7 +496,7 @@ private static function filterRegisteredName(string $host): string /** * Retrieves and format IDNA conversion error message. * - * @see http://icu-project.org/apiref/icu4j/com/ibm/icu/text/IDNA.Error.html + * @link http://icu-project.org/apiref/icu4j/com/ibm/icu/text/IDNA.Error.html */ private static function getIDNAErrors(int $error_byte): string { @@ -515,9 +532,9 @@ private static function getIDNAErrors(int $error_byte): string /** * Validates a IPv6/IPvfuture host. * - * @see https://tools.ietf.org/html/rfc3986#section-3.2.2 - * @see https://tools.ietf.org/html/rfc6874#section-2 - * @see https://tools.ietf.org/html/rfc6874#section-4 + * @link https://tools.ietf.org/html/rfc3986#section-3.2.2 + * @link https://tools.ietf.org/html/rfc6874#section-2 + * @link https://tools.ietf.org/html/rfc6874#section-4 */ private static function isIpHost(string $ip_host): bool { diff --git a/src/UriTemplate.php b/src/UriTemplate.php index fa915dc1..8b858963 100644 --- a/src/UriTemplate.php +++ b/src/UriTemplate.php @@ -40,15 +40,23 @@ use const PREG_SET_ORDER; /** - * Expands URI templates. + * Defines the URI Template syntax and the process for expanding a URI Template into a URI reference. * - * @link http://tools.ietf.org/html/rfc6570 + * @link https://tools.ietf.org/html/rfc6570 + * @package League\Uri + * @author Ignace Nyamagana Butera + * @since 6.1.0 * - * Based on GuzzleHttp\UriTemplate class which is removed from Guzzle7. - * @see https://github.com/guzzle/guzzle/blob/6.5/src/UriTemplate.php + * Based on GuzzleHttp\UriTemplate class in Guzzle v6.5. + * @link https://github.com/guzzle/guzzle/blob/6.5/src/UriTemplate.php */ final class UriTemplate { + /** + * Expression regular expression pattern. + * + * @link https://tools.ietf.org/html/rfc6570#section-2.2 + */ private const REGEXP_EXPRESSION = '/\{ (? (?[\.\/;\?&\=,\!@\|\+#])? @@ -56,13 +64,28 @@ final class UriTemplate ) \}/x'; + /** + * Variables specification regular expression pattern. + * + * @link https://tools.ietf.org/html/rfc6570#section-2.3 + */ private const REGEXP_VARSPEC = '/^ (?(?:[A-z0-9_\.]|%[0-9a-fA-F]{2})+) (?\:(?\d+)|\*)? $/x'; + /** + * Reserved Operator characters. + * + * @link https://tools.ietf.org/html/rfc6570#section-2.2 + */ private const RESERVED_OPERATOR = '=,!@|'; + /** + * Processing behavior according to the expression type operator. + * + * @link https://tools.ietf.org/html/rfc6570#appendix-A + */ private const OPERATOR_HASH_LOOKUP = [ '' => ['prefix' => '', 'joiner' => ',', 'query' => false], '+' => ['prefix' => '', 'joiner' => ',', 'query' => false],