Subreality\Dilmun\Anshar\Http\Uri

Complexity

Total Complexity

52

Size/Duplication

Total Lines	790
Duplicated Lines	0 %

Coupling/Cohesion

Components	1
Dependencies	3

Test Coverage

Coverage

93.41%

Importance

Changes	9
Bugs	0	Features	0

32 Methods

Rating	Name	Duplication	Size	Complexity
A	__construct()	0	8	2
A	getParsedUri()	0	4	1
A	getScheme()	0	4	1
A	getAuthority()	0	16	3
A	getUserInfo()	0	4	1
A	getHost()	0	4	1
A	getPort()	0	6	1
A	getPath()	0	13	2
A	getQuery()	0	8	1
A	getFragment()	0	8	1
A	withScheme()	0	4	1
A	withAuthority()	0	17	3
A	withUserInfo()	0	4	1
A	withHost()	0	4	1
A	withPort()	0	4	1
B	withPath()	0	20	5
A	withQuery()	0	4	1
A	withFragment()	0	4	1
A	__toString()	0	4	1
A	toString()	0	16	1
A	explodeUri()	0	21	1
A	explodeHierParts()	0	21	2
A	explodeAuthority()	0	18	2
A	normalizePort()	0	14	2
A	sanitizeUriPartsArray()	0	6	1
A	encodeComponent()	0	10	1
A	containsUnallowedUriCharacters()	0	10	1
A	schemeToString()	0	10	2
A	authorityToString()	0	10	2
A	pathToString()	0	19	4
A	queryToString()	0	10	2
A	fragmentToString()	0	10	2

<?php
namespace Subreality\Dilmun\Anshar\Http;

use Psr\Http\Message\UriInterface;
use Subreality\Dilmun\Anshar\Utils\ArrayHelper;
use Subreality\Dilmun\Anshar\Utils\StringHelper;

class Uri implements UriInterface
{
    use SchemePortsTrait;

    protected $uri_parts = array(
        "scheme"    => "",
        "hier_part" => "",
        "authority" => "",
        "user_info" => "",
        "host"      => "",
        "port"      => null,
        "path"      => "",
        "query"     => "",
        "fragment"  => "",
    );

    protected $sub_delims = array(
        "!",
        "$",
        "&",
        "'",
        "(",
        ")",
        "*",
        "+",
        ",",
        ";",
        "=",
    );

    protected $pchar_unencoded = array(
        ":",
        "@",
    );

    /**
     * Uri constructor.  Accepts a string representing a URI and parses the string into the URI's component parts.
     *
     * @throws \InvalidArgumentException    Throws an \InvalidArgumentException when its parameter is not a string
     * @param string $uri
     */
    public function __construct($uri)
    {
        if (!is_string($uri)) {
            throw new \InvalidArgumentException("New Uri objects must be constructed with a string URI");
        }

        $this->explodeUri($uri);
    }

    /**
     * @todo Add a distinct test for this outside of constructor test

Comment refers to a TODO task

     * Retrieve the parsed components of the URI string.
     *
     * If the class was provided an invalid URI string, URI components will be empty strings, except port, which will
     * be null
     *
     * @return mixed[]
     */
    public function getParsedUri()
    {
        return $this->uri_parts;
    }

    /**
     * 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.
     *
     * @see https://tools.ietf.org/html/rfc3986#section-3.1
     * @return string The URI scheme.
     */
    public function getScheme()
    {
        return strtolower($this->uri_parts["scheme"]);
    }

    /**
     * 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:
     *
     * <pre>
     * [user-info@]host[:port]
     * </pre>
     *
     * If the port component is not set or is the standard port for the current
     * scheme, it SHOULD NOT be included.
     *
     * @see https://tools.ietf.org/html/rfc3986#section-3.2
     * @return string The URI authority, in "[user-info@]host[:port]" format.
     */
    public function getAuthority()
    {
        $normalized_authority = $this->uri_parts["host"];

        if (!empty($this->uri_parts["user_info"])) {
            $normalized_authority = $this->uri_parts["user_info"] . "@" . $normalized_authority;
        }

        $normalized_port = $this->normalizePort();

        if (!is_null($normalized_port)) {
            $normalized_authority = $normalized_authority . ":" . $normalized_port;
        }

        return $normalized_authority;
    }

    /**
     * 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.
     *
     * @return string The URI user information, in "username[:password]" format.
     */
    public function getUserInfo()
    {
        return $this->uri_parts["user_info"];
    }

    /**
     * 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.
     *
     * @see http://tools.ietf.org/html/rfc3986#section-3.2.2
     * @return string The URI host.
     */
    public function getHost()
    {
        return strtolower($this->uri_parts["host"]);
    }

    /**
     * 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.
     *
     * @return null|int The URI port.
     */
    public function getPort()
    {
        $normalized_port = $this->normalizePort();

        return $normalized_port;
    }

    /**
     * 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.
     *
     * @see https://tools.ietf.org/html/rfc3986#section-2
     * @see https://tools.ietf.org/html/rfc3986#section-3.3
     * @return string The URI path.
     */
    public function getPath()
    {
        $path_unencoded = array("/");
        $allowed        = implode($this->pchar_unencoded) . implode($this->sub_delims) . implode($path_unencoded);

        if ($this->containsUnallowedUriCharacters($this->uri_parts["path"], $allowed)) {
            $encoded_string = $this->encodeComponent($this->uri_parts["path"], $path_unencoded);

            return $encoded_string;
        } else {
            return $this->uri_parts["path"];
        }
    }

    /**
     * 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.
     *
     * @see https://tools.ietf.org/html/rfc3986#section-2
     * @see https://tools.ietf.org/html/rfc3986#section-3.4
     * @return string The URI query string.
     */
    public function getQuery()
    {
        $query_unencoded = array("/", "?");

        $encoded_string = $this->encodeComponent($this->uri_parts["query"], $query_unencoded);

        return $encoded_string;
    }

    /**
     * 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.
     *
     * @see https://tools.ietf.org/html/rfc3986#section-2
     * @see https://tools.ietf.org/html/rfc3986#section-3.5
     * @return string The URI fragment.
     */
    public function getFragment()
    {
        $fragment_unencoded = array("/", "?");

        $encoded_string = $this->encodeComponent($this->uri_parts["fragment"], $fragment_unencoded);

        return $encoded_string;
    }

    /**
     * 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.
     *
     * @param string $scheme The scheme to use with the new instance.
     * @return static A new instance with the specified scheme.

Should the return type not be Uri|null?

     * @throws \InvalidArgumentException for invalid or unsupported schemes.
     */
    public function withScheme($scheme)
    {
        // TODO: Implement withScheme() method.

Comments for TODO tasks are often forgotten in the code; it might be better to use a dedicated issue tracker.

    }

    /**
     * Return an instance with the specified authority.
     *
     * This method MUST retain the state of the current instance, and return
     * an instance that contains the specified authority.
     *
     * Replacing the authority is equivalent to replacing or removing all authority components depending upon the
     * composition of the authority.
     *
     * An empty authority is equivalent to removing the authority and all authority components.
     *
     * @param string $authority The scheme to use with the new instance.
     * @return static A new instance with the specified authority.
     * @throws \InvalidArgumentException for invalid authorities.
     */
    public function withAuthority($authority)
    {
        if (!is_string($authority)) {
            throw new \InvalidArgumentException("Authority must be a string");
        } elseif (stristr($authority, "/")) {
            throw new \InvalidArgumentException("Authority must not contain a slash");
        }

        $uri_parts              = $this->uri_parts;
        $uri_parts["authority"] = $authority;

        $new_authority_string = $this->toString($uri_parts);

        $new_authority_uri = new Uri($new_authority_string);

        return $new_authority_uri;
    }

    /**
     * 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.
     *
     * @param string $user The user name to use for authority.
     * @param null|string $password The password associated with $user.
     * @return static A new instance with the specified user information.

Should the return type not be Uri|null?

     */
    public function withUserInfo($user, $password = null)
    {
        // TODO: Implement withUserInfo() method.

Comments for TODO tasks are often forgotten in the code; it might be better to use a dedicated issue tracker.

    }

    /**
     * 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.
     *
     * @param string $host The hostname to use with the new instance.
     * @return static A new instance with the specified host.

Should the return type not be Uri|null?

     * @throws \InvalidArgumentException for invalid hostnames.
     */
    public function withHost($host)
    {
        // TODO: Implement withHost() method.

Comments for TODO tasks are often forgotten in the code; it might be better to use a dedicated issue tracker.

    }

    /**
     * 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.
     *
     * @param null|int $port The port to use with the new instance; a null value
     *     removes the port information.
     * @return static A new instance with the specified port.

Should the return type not be Uri|null?

     * @throws \InvalidArgumentException for invalid ports.
     */
    public function withPort($port)
    {
        // TODO: Implement withPort() method.

Comments for TODO tasks are often forgotten in the code; it might be better to use a dedicated issue tracker.

    }

    /**
     * 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().
     *
     * @param string $path The path to use with the new instance.
     * @return static A new instance with the specified path.
     * @throws \InvalidArgumentException for invalid paths.
     */
    public function withPath($path)
    {
        if (!is_string($path)) {
            throw new \InvalidArgumentException("Supplied path must be a string");
        }

        $uri_parts          = $this->uri_parts;
        $uri_parts["path"]  = $path;
        $path_string_helper = new StringHelper($path);

        if (!empty($uri_parts["authority"]) && !empty($path) && !$path_string_helper->startsWith("/")) {
            throw new \InvalidArgumentException("Cannot create a URI with an authority given a rootless path");
        }

        $new_path_string = $this->toString($uri_parts);

        $new_path_uri = new Uri($new_path_string);

        return $new_path_uri;
    }

    /**
     * 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.
     *
     * @param string $query The query string to use with the new instance.
     * @return static A new instance with the specified query string.

Should the return type not be Uri|null?

     * @throws \InvalidArgumentException for invalid query strings.
     */
    public function withQuery($query)
    {
        // TODO: Implement withQuery() method.

Comments for TODO tasks are often forgotten in the code; it might be better to use a dedicated issue tracker.

    }

    /**
     * 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.
     *
     * @param string $fragment The fragment to use with the new instance.
     * @return static A new instance with the specified fragment.

Should the return type not be Uri|null?

     */
    public function withFragment($fragment)
    {
        // TODO: Implement withFragment() method.

Comments for TODO tasks are often forgotten in the code; it might be better to use a dedicated issue tracker.

    }

    /**
     * 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 "#".
     *
     * @see http://tools.ietf.org/html/rfc3986#section-4.1
     * @return string
     */
    public function __toString()
    {
        return $this->toString($this->uri_parts);
    }

    /**
     * Converts a given array of URI parts to a string according to the specification of the __toString magic method
     *
     * @see Uri::__toString
     *
     * @param array $uri_parts  The URI parts to be combined into a string
     * @return string           The string combined from the array of URI parts
     */
    private function toString(array $uri_parts)
    {
        $uri_string = "";

        $uri_string .= $this->schemeToString($uri_parts["scheme"]);

        $uri_string .= $this->authorityToString($uri_parts["authority"]);

        $uri_string .= $this->pathToString($uri_parts["path"], $uri_parts["authority"]);

        $uri_string .= $this->queryToString($uri_parts["query"]);

        $uri_string .= $this->fragmentToString($uri_parts["fragment"]);

        return $uri_string;
    }

    /**
     * Splits a string URI into its component parts, returning true if the URI string matches a valid URI's syntax
     * and false if the URI string does not
     *
     * @param string $uri   The URI string to be decomposed
     * @return bool         Returns true if the URI string matches a valid URI's syntax
     *                      Returns false otherwise
     */
    private function explodeUri($uri)
    {
        $reg_start     = '/^';
        $scheme_part   = '(?:(?P<scheme>[A-Za-z0-9][^\/\?#:]+):)?';
        $hier_part     = '(?P<hier_part>[^\?#]+)?';
        $query_part    = '(?:\?(?P<query>[^#]*))?';
        $fragment_part = '(?:#(?P<fragment>.*))?';
        $reg_end       = '/';

        $uri_syntax = $reg_start . $scheme_part . $hier_part . $query_part . $fragment_part . $reg_end;

        $uri_valid = preg_match($uri_syntax, $uri, $parts);

        $this->uri_parts = array_merge($this->uri_parts, $parts); //overwriting default values with matches

        $this->explodeHierParts($this->uri_parts["hier_part"]);

        $this->sanitizeUriPartsArray();

        return (bool) $uri_valid;
    }

    /**
     * Splits URI hierarchy data into authority and path data.
     *
     * @param string $hier_part     The hierarchy part of a URI to be decomposed
     * @return void
     */
    private function explodeHierParts($hier_part)
    {
        $authority_parts = array();

        $reg_start      = '/^';
        $authority_part = '(?:(?:\/\/)(?P<authority>.[^\/]+))?';
        $path_part      = '(?P<path>.+)?';
        $reg_end        = '/';

        $hier_part_syntax = $reg_start . $authority_part . $path_part . $reg_end;

        preg_match($hier_part_syntax, $hier_part, $hier_parts);

        if (isset($hier_parts["authority"])) {
            $authority_parts = $this->explodeAuthority($hier_parts["authority"]);
        }

        $hier_parts = array_merge($hier_parts, $authority_parts);

        $this->uri_parts = array_merge($this->uri_parts, $hier_parts);
    }

    /**
     * Splits URI authority data into user info, host, and port data, returning an array with named keys.
     *
     * For the host component, it will capture everything within brackets to support ipv6 or match all characters until
     * it finds a colon indicating the start of the port component.
     *
     * @param string $authority     The authority part of a URI to be decomposed
     * @return mixed[]              An array with named keys containing the component parts of the supplied

Should the return type not be array<*,string|integer|null>?

     *                              authority
     */
    private function explodeAuthority($authority)
    {
        $reg_start      = '/^';
        $user_info_part = '(?:(?P<user_info>.+)@)?';
        $host_part      = '(?P<host>\[.+\]|.[^:]+)';
        $port_part      = '(?::(?P<port>[0-9]+))?';
        $reg_end        = '/';

        $authority_syntax = $reg_start . $user_info_part . $host_part . $port_part . $reg_end;

        preg_match($authority_syntax, $authority, $authority_parts);

        if (isset($authority_parts["port"])) {
            $authority_parts["port"] = (int) $authority_parts["port"];
        }

        return $authority_parts;
    }

    /**
     * Normalizes a port string based on whether the URI's port is standard for its scheme
     *
     * @return int|null     Returns null if the port is standard for the scheme
     *                      Returns the port prepended with a colon if the port is not standard for the scheme
     */
    private function normalizePort()
    {
        $scheme_port_array = new ArrayHelper($this->scheme_ports);

        $standard_port = $scheme_port_array->valueLookup($this->uri_parts["scheme"]);

        if ($this->uri_parts["port"] == $standard_port) {
            $normalized_port = null;
        } else {
            $normalized_port = $this->uri_parts["port"];
        }

        return $normalized_port;
    }

    /**
     * Sanitizes the URI component array by removing redundant key/value pairs
     *
     * @return void
     */
    private function sanitizeUriPartsArray()
    {
        $uri_part_array = new ArrayHelper($this->uri_parts);

        $this->uri_parts = $uri_part_array->removeNumericKeys();
    }

    /**
     * Percent encodes a component string except for sub-delims and unencoded pchar characters as defined by RFC 3986
     * in addition to any component-specific unencoded characters
     *
     * @param string $component_string          The string representing a URI component
     * @param string[] $component_unencoded     [OPTIONAL] Any additional unencoded characters specific to the component
     *
     * @return string                           The string with appropriate characters percent-encoded
     */
    private function encodeComponent($component_string, array $component_unencoded = array())
    {
        $uri_unencoded = array_merge($component_unencoded, $this->sub_delims, $this->pchar_unencoded);

        $string_helper = new StringHelper($component_string);

        $encoded_string = $string_helper->affectChunks("rawurlencode", ...$uri_unencoded);

        return $encoded_string;
    }

    /**
     * Determines whether a string contains unallowed URI characters, provided a string of allowed characters for a
     * given component.
     *
     * Note that a percent-encoded character (e.g. %20 for space) automatically counts as an allowed character, whereas
     * a percent sign not followed by two hex digits (e.g. %2X) does not count as an allowed character.
     *
     * @param string $string    The string to be checked for unallowed characters
     * @param string $allowed   A string containing all allowed characters for a given component
     *
     * @return bool             Returns true if the string contains unallowed characters
     *                          Returns false if the string contains only allowed characters (including percent-encoded
     *                          characters)
     */
    private function containsUnallowedUriCharacters($string, $allowed)
    {
        $allowed = preg_quote($allowed, "/");

        $pattern = "/^([0-9a-zA-Z\\.\\-_~{$allowed}]|%[0-9a-fA-F]{2})*\$/";

        $matches_allowed = preg_match($pattern, $string);

        return (bool) !$matches_allowed;
    }

    /**
     * Returns the appropriate scheme string based upon __toString specification rules.
     *
     * @see Uri::__toString()
     *
     * @param string $scheme    The scheme to compile into a URI-friendly string
     *
     * @return string           The URI-friendly scheme string
     */
    private function schemeToString($scheme)
    {
        $scheme_string = "";

        if (!empty($scheme)) {
            $scheme_string .= $scheme . ":";
        }

        return $scheme_string;
    }

    /**
     * Returns the appropriate authority string based upon __toString specification rules.
     *
     * @see Uri::__toString()
     *
     * @param string $authority     The authority to compile into a URI-friendly string
     *
     * @return string               The URI-friendly authority string
     */
    private function authorityToString($authority)
    {
        $authority_string = "";

        if (!empty($authority)) {
            $authority_string .= "//" . $authority;
        }

        return $authority_string;
    }

    /**
     * Returns the appropriate path string based upon __toString specification rules.
     *
     * @see Uri::__toString()
     *
     * @param string $path          The path to compile into a URI-friendly string
     * @param string $authority     [optional] The authority of the URI
     *
     * @return string               The URI-friendly path string
     */
    private function pathToString($path, $authority = "")
    {
        $path_string        = "";
        $path_string_helper = new StringHelper($path);

        if (empty($authority)) {
            $collapsed_slashes = $path_string_helper->collapseStartingRepetition("/");

            $path_string .= $collapsed_slashes;
        } elseif (!empty($path)) {
            if (!$path_string_helper->startsWith("/")) {
                $path_string .= "/" . $path;
            } else {
                $path_string .= $path;
            }
        }

        return $path_string;
    }

    /**
     * Returns the appropriate query string based upon __toString specification rules.
     *
     * @see Uri::__toString()
     *
     * @param string $query     The query to compile into a URI-friendly string
     *
     * @return string           The URI-friendly query string
     */
    private function queryToString($query)
    {
        $query_string = "";

        if (!empty($query)) {
            $query_string .= "?" . $query;
        }

        return $query_string;
    }

    /**
     * Returns the appropriate fragment string based upon __toString specification rules.
     *
     * @see Uri::__toString()
     *
     * @param string $fragment  The fragment to compile into a URI-friendly string
     *
     * @return string           The URI-friendly fragment string
     */
    private function fragmentToString($fragment)
    {
        $fragment_string = "";

        if (!empty($fragment)) {
            $fragment_string .= "#" . $fragment;
        }

        return $fragment_string;
    }
}