Documentation

URI
in package

Application

Abstraction for a uniform resource identifier (URI).

CHAR_SUB_DELIMS = '!\$&'\*\+,;=': Sub-delimiters used in query strings and fragments.
CHAR_UNRESERVED = 'a-zA-Z0-9_\-\.~': Unreserved characters used in paths, query strings, and fragments.
$defaultPorts : array<string|int, mixed>: Default schemes/ports.
$fragment : string: The name of any fragment.
$host : string: URI Host
$password : string: URI User Password
$path : string: URI path.
$port : int: URI Port
$query : array<string|int, mixed>: The query string.
$rawQueryString : bool: If true, will use raw query string.
$scheme : string: The URI Scheme.
$segments : array<string|int, mixed>: List of URI segments.
$showPassword : bool: Whether passwords should be shown in userInfo/authority calls.
$silent : bool: If true, will continue instead of throwing exceptions.
$uriString : string: Current URI string
$user : string: URI User Info
__construct() : mixed: Constructor.
__toString() : string: Formats the URI as a string.
addQuery() : $this: Adds a single new element to the query vars.
createURIString() : string: Builds a representation of the string from the component parts.
getAuthority() : string: Retrieve the authority component of the URI.
getFragment() : string: Retrieve a URI fragment
getHost() : string: Retrieve the host component of the URI.
getPath() : string: Retrieve the path component of the URI.
getPort() : null|int: Retrieve the port component of the URI.
getQuery() : string: Retrieve the query string
getScheme() : string: Retrieve the scheme component of the URI.
getSegment() : string: Returns the value of a specific segment of the URI path.
getSegments() : array<string|int, mixed>: Returns the segments of the path as an array.
getTotalSegments() : int: Returns the total number of segments.
getUserInfo() : string|null: Retrieve the user information component of the URI.
keepQuery() : $this: Filters the query variables so that only the keys passed in are kept. The rest are removed from the object.
refreshPath() : $this: Sets the path portion of the URI based on segments.
resolveRelativeURI() : URI: Combines one URI string with this one based on the rules set out in RFC 3986 Section 2
setAuthority() : $this: Parses the given string and saves the appropriate authority pieces.
setFragment() : $this: Sets the fragment portion of the URI.
setHost() : $this: Sets the host name to use.
setPath() : $this: Sets the path portion of the URI.
setPort() : $this: Sets the port portion of the URI.
setQuery() : $this: Sets the query portion of the URI, while attempting to clean the various parts of the query keys and values.
setQueryArray() : URI: A convenience method to pass an array of items in as the Query portion of the URI.
setScheme() : $this: Sets the scheme for this URI.
setSegment() : $this: Set the value of a specific segment of the URI path.
setSilent() : URI: If $silent == true, then will not throw exceptions and will attempt to continue gracefully.
setURI() : URI: Sets and overwrites any current URI information.
setUserInfo() : $this: Sets the userInfo/Authority portion of the URI.
showPassword() : URI: Temporarily sets the URI to show a password in userInfo. Will reset itself after the first call to authority().
stripQuery() : $this: Removes one or more query vars from the URI.
useRawQueryString() : URI: If $raw == true, then will use parseStr() method instead of native parse_str() function.
applyParts() : mixed: Saves our parts from a parse_url call.
filterPath() : string: Encodes any dangerous characters, and removes dot segments.
mergePaths() : string: Given 2 paths, will merge them according to rules set out in RFC 2986, Section 5.2
parseStr() : array<string|int, mixed>: This is equivalent to the native PHP parse_str() function.

CHAR_SUB_DELIMS

Sub-delimiters used in query strings and fragments.


    public
    mixed
    CHAR_SUB_DELIMS
    = '!\$&'\(\)\*\+,;='

CHAR_UNRESERVED

Unreserved characters used in paths, query strings, and fragments.


    public
    mixed
    CHAR_UNRESERVED
    = 'a-zA-Z0-9_\-\.~'

$defaultPorts

Default schemes/ports.


    protected
        array<string|int, mixed>
    $defaultPorts
     = ['http' => 80, 'https' => 443, 'ftp' => 21, 'sftp' => 22]

$fragment

The name of any fragment.


    protected
        string
    $fragment
     = ''

$host

URI Host


    protected
        string
    $host

$password

URI User Password


    protected
        string
    $password

$path

URI path.


    protected
        string
    $path

$port

URI Port


    protected
        int
    $port

$query

The query string.


    protected
        array<string|int, mixed>
    $query
     = []

$rawQueryString

If true, will use raw query string.


    protected
        bool
    $rawQueryString
     = false

$scheme

The URI Scheme.


    protected
        string
    $scheme
     = 'http'

$segments

List of URI segments.


    protected
        array<string|int, mixed>
    $segments
     = []

Starts at 1 instead of 0

$showPassword

Whether passwords should be shown in userInfo/authority calls.


    protected
        bool
    $showPassword
     = false

Default to false because URIs often show up in logs

$silent

If true, will continue instead of throwing exceptions.


    protected
        bool
    $silent
     = false

$uriString

Current URI string


    protected
        string
    $uriString

$user

URI User Info


    protected
        string
    $user

__construct()

Constructor.


    public
                __construct([string $uri = null ]) : mixed

Parameters

$uri : string = null

Return values

mixed —

__toString()

Formats the URI as a string.


    public
                __toString() : string

Warning: For backwards-compatability this method assumes URIs with the same host as baseURL should be relative to the project's configuration. This aspect of __toString() is deprecated and should be avoided.

Return values

string —

addQuery()

Adds a single new element to the query vars.


    public
                addQuery(string $key[, mixed $value = null ]) : $this

Parameters

$key : string
$value : mixed = null

Return values

$this —

createURIString()

Builds a representation of the string from the component parts.


    public
            static    createURIString([string $scheme = null ][, string $authority = null ][, string $path = null ][, string $query = null ][, string $fragment = null ]) : string

Parameters

$scheme : string = null
$authority : string = null
$path : string = null
$query : string = null
$fragment : string = null

Return values

string —

getAuthority()

Retrieve the authority component of the URI.


    public
                getAuthority([bool $ignorePort = false ]) : string

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.

Parameters

$ignorePort : bool = false

Return values

string —

The URI authority, in "[user-info@]host[:port]" format.

getFragment()

Retrieve a URI fragment


    public
                getFragment() : string

Return values

string —

getHost()

Retrieve the host component of the URI.


    public
                getHost() : string

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.

Return values

string —

The URI host.

getPath()

Retrieve the path component of the URI.


    public
                getPath() : string

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.

Return values

string —

The URI path.

getPort()

Retrieve the port component of the URI.


    public
                getPort() : null|int

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.

Return values

null|int —

The URI port.

getQuery()

Retrieve the query string


    public
                getQuery([array<string|int, mixed> $options = [] ]) : string

Parameters

$options : array<string|int, mixed> = []

Return values

string —

getScheme()

Retrieve the scheme component of the URI.


    public
                getScheme() : string

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.

Return values

string —

The URI scheme.

getSegment()

Returns the value of a specific segment of the URI path.


    public
                getSegment(int $number[, string $default = '' ]) : string

Parameters

$number : int: Segment number
$default : string = '': Default value

Return values

string —

The value of the segment. If no segment is found, throws InvalidArgumentError

getSegments()

Returns the segments of the path as an array.


    public
                getSegments() : array<string|int, mixed>

Return values

array<string|int, mixed> —

getTotalSegments()

Returns the total number of segments.


    public
                getTotalSegments() : int

Return values

int —

getUserInfo()

Retrieve the user information component of the URI.


    public
                getUserInfo() : string|null

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.

NOTE that be default, the password, if available, will NOT be shown as a security measure as discussed in RFC 3986, Section 7.5. If you know the password is not a security issue, you can force it to be shown with $this->showPassword();

The trailing "@" character is not part of the user information and MUST NOT be added.

Return values

string|null —

The URI user information, in "username[:password]" format.

keepQuery()

Filters the query variables so that only the keys passed in are kept. The rest are removed from the object.


    public
                keepQuery(string ...$params) : $this

Parameters

$params : string

Return values

$this —

refreshPath()

Sets the path portion of the URI based on segments.


    public
                refreshPath() : $this

Return values

$this —

resolveRelativeURI()

Combines one URI string with this one based on the rules set out in RFC 3986 Section 2


    public
                resolveRelativeURI(string $uri) : URI

Parameters

$uri : string

Return values

URI —

setAuthority()

Parses the given string and saves the appropriate authority pieces.


    public
                setAuthority(string $str) : $this

Parameters

$str : string

Return values

$this —

setFragment()

Sets the fragment portion of the URI.


    public
                setFragment(string $string) : $this

Parameters

$string : string

Return values

$this —

setHost()

Sets the host name to use.


    public
                setHost(string $str) : $this

Parameters

$str : string

Return values

$this —

setPath()

Sets the path portion of the URI.


    public
                setPath(string $path) : $this

Parameters

$path : string

Return values

$this —

setPort()

Sets the port portion of the URI.


    public
                setPort([int $port = null ]) : $this

Parameters

$port : int = null

Return values

$this —

setQuery()

Sets the query portion of the URI, while attempting to clean the various parts of the query keys and values.


    public
                setQuery(string $query) : $this

Parameters

$query : string

Return values

$this —

setQueryArray()

A convenience method to pass an array of items in as the Query portion of the URI.


    public
                setQueryArray(array<string|int, mixed> $query) : URI

Parameters

$query : array<string|int, mixed>

Return values

URI —

setScheme()

Sets the scheme for this URI.


    public
                setScheme(string $str) : $this

Because of the large number of valid schemes we cannot limit this to only http or https.

Parameters

$str : string

Return values

$this —

setSegment()

Set the value of a specific segment of the URI path.


    public
                setSegment(int $number, mixed $value) : $this

Allows to set only existing segments or add new one.

Parameters

$number : int
$value : mixed: (string or int)

Return values

$this —

setSilent()

If $silent == true, then will not throw exceptions and will attempt to continue gracefully.


    public
                setSilent([bool $silent = true ]) : URI

Parameters

$silent : bool = true

Return values

URI —

setURI()

Sets and overwrites any current URI information.


    public
                setURI([string|null $uri = null ]) : URI

Parameters

$uri : string|null = null

Return values

URI —

setUserInfo()

Sets the userInfo/Authority portion of the URI.


    public
                setUserInfo(string $user, string $pass) : $this

Parameters

$user : string: The user's username
$pass : string: The user's password

Return values

$this —

showPassword()

Temporarily sets the URI to show a password in userInfo. Will reset itself after the first call to authority().


    public
                showPassword([bool $val = true ]) : URI

Parameters

$val : bool = true

Return values

URI —

stripQuery()

Removes one or more query vars from the URI.


    public
                stripQuery(string ...$params) : $this

Parameters

$params : string

Return values

$this —

useRawQueryString()

If $raw == true, then will use parseStr() method instead of native parse_str() function.


    public
                useRawQueryString([bool $raw = true ]) : URI

Parameters

$raw : bool = true

Return values

URI —

applyParts()

Saves our parts from a parse_url call.


    protected
                applyParts(array<string|int, mixed> $parts) : mixed

Parameters

$parts : array<string|int, mixed>

Return values

mixed —

filterPath()

Encodes any dangerous characters, and removes dot segments.


    protected
                filterPath([string|null $path = null ]) : string

While dot segments have valid uses according to the spec, this URI class does not allow them.

Parameters

$path : string|null = null

Return values

string —

mergePaths()

Given 2 paths, will merge them according to rules set out in RFC 2986, Section 5.2


    protected
                mergePaths(URI $base, URI $reference) : string

Parameters

$base : URI
$reference : URI

Return values

string —

parseStr()

This is equivalent to the native PHP parse_str() function.


    protected
                parseStr(string $query) : array<string|int, mixed>

This version allows the dot to be used as a key of the query string.

Parameters

$query : string

Return values

array<string|int, mixed> —

URI in package Application

Table of Contents

Constants

CHAR_SUB_DELIMS

CHAR_UNRESERVED

Properties

$defaultPorts

$fragment

$host

$password

$path

$port

$query

$rawQueryString

$scheme

$segments

$showPassword

$silent

$uriString

$user

Methods

__construct()

Parameters

Tags

Return values

__toString()

Return values

addQuery()

Parameters

Return values

createURIString()

Parameters

Return values

getAuthority()

Parameters

Tags

Return values

getFragment()

Return values

getHost()

Tags

Return values

getPath()

Tags

Return values

getPort()

Return values

getQuery()

Parameters

Return values

getScheme()

Tags

Return values

getSegment()

Parameters

Return values

getSegments()

Return values

getTotalSegments()

Return values

getUserInfo()

Return values

keepQuery()

Parameters

Return values

refreshPath()

Return values

resolveRelativeURI()

Parameters

Tags

Return values

setAuthority()

Parameters

Return values

setFragment()

Parameters

Tags

Return values

setHost()

Parameters

URI
in package

Application