Trait UriTrait

Provides a set of methods to honor the Psr-7 Uri Interface.

Traits provide extended method support to classes without requiring a direct, linear chain of inheritance. This allows functions to inherit subsets of related methods without declaring a parent class.

In Oroboros core, ALL methods are granted to classes via traits, and the classes themselves are just containers that correlate their methods to an interface they are expected to honor. This approach maximizes interoperability, by entirely removing class inheritance as a requirement for extension of any class in this system.

3rd parties using this package are not expected to follow this approach,

but ALL of our internal class and logic structure does.

Direct Known Users

oroboros\core\abstracts\libraries\uri\AbstractUri

Indirect Known Users

oroboros\core\libraries\uri\Uri

Namespace: oroboros\core\traits\libraries\uri
Package: oroboros\core\psr7
Category: traits
License: The MIT License (MIT)
Author: Brian Dayhoff mopsyd@me.com
Version: 0.2.4
Since: 0.2.4-alpha
Used by: oroboros\core\interfaces\api\psr\Psr7Api::URI_ABSTRACT_CLASS
Link: bitbucket.org/oroborosframework/oroboros-core/wiki/development/api/traits.md
Satisfies: \oroboros\core\interfaces\contract\libraries\uri\UriContract
Satisfies: \Psr\Http\Message\UriInterface
Located at core/traits/libraries/uri/UriTrait.php

Methods summary

`public`	# `__construct( string $uri )` Creates a new uri wrapper based on the supplied uri parameter. Creates a new uri wrapper based on the supplied uri parameter. Parameters `$uri`
`public string`	# `getScheme( )` Retrieve the scheme component of the URI. If no scheme is present, this method MUST return an empty string. The value returned MUST be normalized to lowercase, per RFC 3986 Section 3.1. The trailing ":" character is not part of the scheme and MUST NOT be added. Retrieve the scheme component of the URI. If no scheme is present, this method MUST return an empty string. The value returned MUST be normalized to lowercase, per RFC 3986 Section 3.1. The trailing ":" character is not part of the scheme and MUST NOT be added. Returns string The URI scheme. See https://tools.ietf.org/html/rfc3986#section-3.1
`public string`	# `getAuthority( )` Retrieve the authority component of the URI. If no authority information is present, this method MUST return an empty string. The authority syntax of the URI is: [user-info@]host[:port] If the port component is not set or is the standard port for the current scheme, it SHOULD NOT be included. Retrieve the authority component of the URI. If no authority information is present, this method MUST return an empty string. The authority syntax of the URI is: [user-info@]host[:port] If the port component is not set or is the standard port for the current scheme, it SHOULD NOT be included. Returns string The URI authority, in "[user-info@]host[:port]" format. See https://tools.ietf.org/html/rfc3986#section-3.2
`public string`	# `getUserInfo( )` Retrieve the user information component of the URI. If no user information is present, this method MUST return an empty string. If a user is present in the URI, this will return that value; additionally, if the password is also present, it will be appended to the user value, with a colon (":") separating the values. The trailing "@" character is not part of the user information and MUST NOT be added. Retrieve the user information component of the URI. If no user information is present, this method MUST return an empty string. If a user is present in the URI, this will return that value; additionally, if the password is also present, it will be appended to the user value, with a colon (":") separating the values. The trailing "@" character is not part of the user information and MUST NOT be added. Returns string The URI user information, in "username[:password]" format.
`public string`	# `getHost( )` Retrieve the host component of the URI. If no host is present, this method MUST return an empty string. The value returned MUST be normalized to lowercase, per RFC 3986 Section 3.2.2. Retrieve the host component of the URI. If no host is present, this method MUST return an empty string. The value returned MUST be normalized to lowercase, per RFC 3986 Section 3.2.2. Returns string The URI host. See http://tools.ietf.org/html/rfc3986#section-3.2.2
`public null\|integer`	# `getPort( )` Retrieve the port component of the URI. If a port is present, and it is non-standard for the current scheme, this method MUST return it as an integer. If the port is the standard port used with the current scheme, this method SHOULD return null. If no port is present, and no scheme is present, this method MUST return a null value. If no port is present, but a scheme is present, this method MAY return the standard port for that scheme, but SHOULD return null. Retrieve the port component of the URI. If a port is present, and it is non-standard for the current scheme, this method MUST return it as an integer. If the port is the standard port used with the current scheme, this method SHOULD return null. If no port is present, and no scheme is present, this method MUST return a null value. If no port is present, but a scheme is present, this method MAY return the standard port for that scheme, but SHOULD return null. Returns null\|integer The URI port.
`public string`	# `getPath( )` Retrieve the path component of the URI. The path can either be empty or absolute (starting with a slash) or rootless (not starting with a slash). Implementations MUST support all three syntaxes. Normally, the empty path "" and absolute path "/" are considered equal as defined in RFC 7230 Section 2.7.3. But this method MUST NOT automatically do this normalization because in contexts with a trimmed base path, e.g. the front controller, this difference becomes significant. It's the task of the user to handle both "" and "/". The value returned MUST be percent-encoded, but MUST NOT double-encode any characters. To determine what characters to encode, please refer to RFC 3986, Sections 2 and 3.3. As an example, if the value should include a slash ("/") not intended as delimiter between path segments, that value MUST be passed in encoded form (e.g., "%2F") to the instance. Retrieve the path component of the URI. The path can either be empty or absolute (starting with a slash) or rootless (not starting with a slash). Implementations MUST support all three syntaxes. Normally, the empty path "" and absolute path "/" are considered equal as defined in RFC 7230 Section 2.7.3. But this method MUST NOT automatically do this normalization because in contexts with a trimmed base path, e.g. the front controller, this difference becomes significant. It's the task of the user to handle both "" and "/". The value returned MUST be percent-encoded, but MUST NOT double-encode any characters. To determine what characters to encode, please refer to RFC 3986, Sections 2 and 3.3. As an example, if the value should include a slash ("/") not intended as delimiter between path segments, that value MUST be passed in encoded form (e.g., "%2F") to the instance. Returns string The URI path. See https://tools.ietf.org/html/rfc3986#section-2 https://tools.ietf.org/html/rfc3986#section-3.3
`public string`	# `getQuery( )` Retrieve the query string of the URI. If no query string is present, this method MUST return an empty string. The leading "?" character is not part of the query and MUST NOT be added. The value returned MUST be percent-encoded, but MUST NOT double-encode any characters. To determine what characters to encode, please refer to RFC 3986, Sections 2 and 3.4. As an example, if a value in a key/value pair of the query string should include an ampersand ("&") not intended as a delimiter between values, that value MUST be passed in encoded form (e.g., "%26") to the instance. Retrieve the query string of the URI. If no query string is present, this method MUST return an empty string. The leading "?" character is not part of the query and MUST NOT be added. The value returned MUST be percent-encoded, but MUST NOT double-encode any characters. To determine what characters to encode, please refer to RFC 3986, Sections 2 and 3.4. As an example, if a value in a key/value pair of the query string should include an ampersand ("&") not intended as a delimiter between values, that value MUST be passed in encoded form (e.g., "%26") to the instance. Returns string The URI query string. See https://tools.ietf.org/html/rfc3986#section-2 https://tools.ietf.org/html/rfc3986#section-3.4
`public string`	# `getFragment( )` Retrieve the fragment component of the URI. If no fragment is present, this method MUST return an empty string. The leading "#" character is not part of the fragment and MUST NOT be added. The value returned MUST be percent-encoded, but MUST NOT double-encode any characters. To determine what characters to encode, please refer to RFC 3986, Sections 2 and 3.5. Retrieve the fragment component of the URI. If no fragment is present, this method MUST return an empty string. The leading "#" character is not part of the fragment and MUST NOT be added. The value returned MUST be percent-encoded, but MUST NOT double-encode any characters. To determine what characters to encode, please refer to RFC 3986, Sections 2 and 3.5. Returns string The URI fragment. See https://tools.ietf.org/html/rfc3986#section-2 https://tools.ietf.org/html/rfc3986#section-3.5
`public static`	# `withScheme( string $scheme )` Return an instance with the specified scheme. This method MUST retain the state of the current instance, and return an instance that contains the specified scheme. Implementations MUST support the schemes "http" and "https" case insensitively, and MAY accommodate other schemes if required. An empty scheme is equivalent to removing the scheme. Return an instance with the specified scheme. This method MUST retain the state of the current instance, and return an instance that contains the specified scheme. Implementations MUST support the schemes "http" and "https" case insensitively, and MAY accommodate other schemes if required. An empty scheme is equivalent to removing the scheme. Parameters `$scheme` The scheme to use with the new instance. Returns static A new instance with the specified scheme. Throws `oroboros\core\utilities\exception\InvalidArgumentException` for invalid or unsupported schemes.
`public static`	# `withUserInfo( string $user, null\|string $password = null )` Return an instance with the specified user information. This method MUST retain the state of the current instance, and return an instance that contains the specified user information. Password is optional, but the user information MUST include the user; an empty string for the user is equivalent to removing user information. Return an instance with the specified user information. This method MUST retain the state of the current instance, and return an instance that contains the specified user information. Password is optional, but the user information MUST include the user; an empty string for the user is equivalent to removing user information. Parameters `$user` The user name to use for authority. `$password` The password associated with $user. Returns static A new instance with the specified user information.
`public static`	# `withHost( string $host )` Return an instance with the specified host. This method MUST retain the state of the current instance, and return an instance that contains the specified host. An empty host value is equivalent to removing the host. Return an instance with the specified host. This method MUST retain the state of the current instance, and return an instance that contains the specified host. An empty host value is equivalent to removing the host. Parameters `$host` The hostname to use with the new instance. Returns static A new instance with the specified host. Throws `oroboros\core\utilities\exception\InvalidArgumentException` for invalid hostnames.
`public static`	# `withPort( null\|integer $port )` Return an instance with the specified port. This method MUST retain the state of the current instance, and return an instance that contains the specified port. Implementations MUST raise an exception for ports outside the established TCP and UDP port ranges. A null value provided for the port is equivalent to removing the port information. Return an instance with the specified port. This method MUST retain the state of the current instance, and return an instance that contains the specified port. Implementations MUST raise an exception for ports outside the established TCP and UDP port ranges. A null value provided for the port is equivalent to removing the port information. Parameters `$port` The port to use with the new instance; a null value removes the port information. Returns static A new instance with the specified port. Throws `oroboros\core\utilities\exception\InvalidArgumentException` for invalid ports.
`public static`	# `withPath( string $path )` Return an instance with the specified path. This method MUST retain the state of the current instance, and return an instance that contains the specified path. The path can either be empty or absolute (starting with a slash) or rootless (not starting with a slash). Implementations MUST support all three syntaxes. If the path is intended to be domain-relative rather than path relative then it must begin with a slash ("/"). Paths not starting with a slash ("/") are assumed to be relative to some base path known to the application or consumer. Users can provide both encoded and decoded path characters. Implementations ensure the correct encoding as outlined in getPath(). Return an instance with the specified path. This method MUST retain the state of the current instance, and return an instance that contains the specified path. The path can either be empty or absolute (starting with a slash) or rootless (not starting with a slash). Implementations MUST support all three syntaxes. If the path is intended to be domain-relative rather than path relative then it must begin with a slash ("/"). Paths not starting with a slash ("/") are assumed to be relative to some base path known to the application or consumer. Users can provide both encoded and decoded path characters. Implementations ensure the correct encoding as outlined in getPath(). Parameters `$path` The path to use with the new instance. Returns static A new instance with the specified path. Throws `oroboros\core\utilities\exception\InvalidArgumentException` for invalid paths.
`public static`	# `withQuery( string $query )` Return an instance with the specified query string. Return an instance with the specified query string. This method MUST retain the state of the current instance, and return an instance that contains the specified query string. Users can provide both encoded and decoded query characters. Implementations ensure the correct encoding as outlined in getQuery(). An empty query string value is equivalent to removing the query string. Parameters `$query` The query string to use with the new instance. Returns static A new instance with the specified query string. Throws `oroboros\core\utilities\exception\InvalidArgumentException` for invalid query strings.
`public static`	# `withFragment( string $fragment )` Return an instance with the specified URI fragment. This method MUST retain the state of the current instance, and return an instance that contains the specified URI fragment. Users can provide both encoded and decoded fragment characters. Implementations ensure the correct encoding as outlined in getFragment(). An empty fragment value is equivalent to removing the fragment. Return an instance with the specified URI fragment. This method MUST retain the state of the current instance, and return an instance that contains the specified URI fragment. Users can provide both encoded and decoded fragment characters. Implementations ensure the correct encoding as outlined in getFragment(). An empty fragment value is equivalent to removing the fragment. Parameters `$fragment` The fragment to use with the new instance. Returns static A new instance with the specified fragment.
`public string`	# `__toString( )` Return the string representation as a URI reference. Depending on which components of the URI are present, the resulting string is either a full URI or relative reference according to RFC 3986, Section 4.1. The method concatenates the various components of the URI, using the appropriate delimiters: - If a scheme is present, it MUST be suffixed by ":". - If an authority is present, it MUST be prefixed by "//". - The path can be concatenated without delimiters. But there are two cases where the path has to be adjusted to make the URI reference valid as PHP does not allow to throw an exception in __toString(): - If the path is rootless and an authority is present, the path MUST be prefixed by "/". - If the path is starting with more than one "/" and no authority is present, the starting slashes MUST be reduced to one. - If a query is present, it MUST be prefixed by "?". - If a fragment is present, it MUST be prefixed by "#". Return the string representation as a URI reference. Depending on which components of the URI are present, the resulting string is either a full URI or relative reference according to RFC 3986, Section 4.1. The method concatenates the various components of the URI, using the appropriate delimiters: - If a scheme is present, it MUST be suffixed by ":". - If an authority is present, it MUST be prefixed by "//". - The path can be concatenated without delimiters. But there are two cases where the path has to be adjusted to make the URI reference valid as PHP does not allow to throw an exception in __toString(): - If the path is rootless and an authority is present, the path MUST be prefixed by "/". - If the path is starting with more than one "/" and no authority is present, the starting slashes MUST be reduced to one. - If a query is present, it MUST be prefixed by "?". - If a fragment is present, it MUST be prefixed by "#". Returns string See http://tools.ietf.org/html/rfc3986#section-4.1
`protected`	# `_initializeUri( array $uri, array $flags,… )` Parameters `$uri` $args `$flags`,… Throws `oroboros\core\utilities\exception\InvalidArgumentException`
`protected Psr\Http\Message\UriInterface`	# `_composeNewUriDefaultClass( array $args = array() , array $flags,… )` Returns a new instance of the defined default class, as defined in the class constant: [NEW_URI_DEFAULT_CLASS]. Arguments for initialization may be passed into this method to update the class. Returns a new instance of the defined default class, as defined in the class constant: [NEW_URI_DEFAULT_CLASS]. Arguments for initialization may be passed into this method to update the class. Parameters `$args` (optional) Arguments used to create the new class instance. `$flags`,… (optional) Placeholder for future flag processing Returns Psr\Http\Message\UriInterface The new class instance. Throws `oroboros\core\utilities\exception\Exception` Thrown if the current class implementing this trait is not an instance of \Psr\Http\Message\UriInterface
`private`	# `_getObjectArguments( )` Logic Methods (private) Logic Methods (private) These methods are not externally exposed. They represent the actual work.
`private`	# `_parseUriParameters( $uri )`
`private string`	# `_filterScheme( string $scheme )` Parameters `$scheme` Returns string Throws `oroboros\core\utilities\exception\InvalidArgumentException` If the scheme is invalid.
`private string`	# `_filterHost( string $host )` Parameters `$host` Returns string Throws `oroboros\core\utilities\exception\InvalidArgumentException` If the host is invalid.
`private integer\|null`	# `_filterPort( integer\|null $port )` Parameters `$port` Returns integer\|null Throws `oroboros\core\utilities\exception\InvalidArgumentException` If the port is invalid.
`private string`	# `_filterPath( string $path )` Filters the path of a URI Filters the path of a URI Parameters `$path` Returns string Throws `oroboros\core\utilities\exception\InvalidArgumentException` If the path is invalid.
`private string`	# `_filterQueryAndFragment( string $str )` Filters the query string or fragment of a URI. Filters the query string or fragment of a URI. Parameters `$str` Returns string Throws `oroboros\core\utilities\exception\InvalidArgumentException` If the query or fragment is invalid.
`private`	# `_rawurlencodeMatchZero( array $match )`
`private`	# `_validateState( )`
`private string`	# `_composeComponents( string $scheme, string $user, string $host, string $port, string $path, $query, $fragment )` Composes a URI reference string from its various components. PSR-7 UriInterface treats an empty component the same as a missing component as getQuery(), getFragment() etc. always return a string. This explains the slight difference to RFC 3986 Section 5.3. Composes a URI reference string from its various components. PSR-7 UriInterface treats an empty component the same as a missing component as getQuery(), getFragment() etc. always return a string. This explains the slight difference to RFC 3986 Section 5.3. Another adjustment is that the authority separator is added even when the authority is missing/empty for the "file" scheme. This is because PHP stream functions like `file_get_contents` only work with `file:///myfile` but not with `file:/myfile` although they are equivalent according to RFC 3986. But `file:///` is the more common syntax for the file scheme anyway (Chrome for example redirects to that format). Parameters `$scheme` `$user` $authority `$host` $path `$port` $query `$path` $fragment `$query` `$fragment` Returns string Returns the full semantically correct uri if the request is http. If the request is cli, it returns the top level fully qualified path to the script originally called. Link https://tools.ietf.org/html/rfc3986#section-5.3

Properties summary

`private static array`	`$_regex`	# `array( 'path' => '/(?:[^a-zA-Z0-9_\-\.~!\$&\'\\+,;=%:@\/]++\|%(?![A-Fa-f0-9]{2}))/', 'queryAndFragment' => '/(?:[^a-zA-Z0-9_\-\.~!\$&\'\\+,;=%:@\/\?]++\|%(?![A-Fa-f0-9]{2}))/', )`
`private static array`	`$_replaceQuery`	# `[ '=' => '%3D', '&' => '%26' ]`
`private string`	`$_scheme` Uri scheme. Uri scheme.	# `''`
`private string`	`$_userInfo` Uri user info. Uri user info.	# `''`
`private string`	`$_host` Uri host. Uri host.	# `''`
`private integer\|null`	`$_port` Uri port. Uri port.	#
`private string`	`$_path` Uri path. Uri path.	# `''`
`private string`	`$_query` Uri query string. Uri query string.	# `''`
`private string`	`$_fragment` Uri fragment. Uri fragment.	# `''`
`private array`	`$_defaultPorts`	# `array( 'http' => 80, 'https' => 443, 'ftp' => 21, 'gopher' => 70, 'nntp' => 119, 'news' => 119, 'telnet' => 23, 'tn3270' => 23, 'imap' => 143, 'pop' => 110, 'ldap' => 389, )`

Namespaces

Traits

Trait UriTrait

Provides a set of methods to honor the Psr-7 Uri Interface.

but ALL of our internal class and logic structure does.

Direct Known Users

Indirect Known Users

Methods summary

Parameters

Returns

See

Returns

See

Returns

Returns

See

Returns

Returns

See

Returns

See

Returns

See

Parameters

Returns

Throws

Parameters

Returns

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Returns

See

Parameters

Throws

Parameters

Returns

Throws

They represent the actual work.

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Link

Properties summary