HTMLPurifier_URI Class Reference

HTML Purifier's internal representation of a URI. More...

Collaboration diagram for HTMLPurifier_URI:

Public Member Functions
	__construct ($scheme, $userinfo, $host, $port, $path, $query, $fragment)
	getSchemeObj ($config, $context)
	Retrieves a scheme object corresponding to the URI's scheme/default. More...
	validate ($config, $context)
	Generic validation method applicable for all schemes. More...
	toString ()
	Convert URI back to string. More...
	isLocal ($config, $context)
	Returns true if this URL might be considered a 'local' URL given the current context. More...
	isBenign ($config, $context)
	Returns true if this URL should be considered a 'benign' URL, that is: More...

Data Fields
	$scheme
	string More...
	$userinfo
	string More...
	$host
	string More...
	$port
	int More...
	$path
	string More...
	$query
	string More...
	$fragment
	string More...

Detailed Description

HTML Purifier's internal representation of a URI.

Note

Internal data-structures are completely escaped. If the data needs to be used in a non-URI context (which is very unlikely), be sure to decode it first. The URI may not necessarily be well-formed until validate() is called.

Definition at line 11 of file URI.php.

Constructor & Destructor Documentation

__construct()

HTMLPurifier_URI::__construct	(		$scheme,
			$userinfo,
			$host,
			$port,
			$path,
			$query,
			$fragment
	)

Parameters

string	$scheme
string	$userinfo
string	$host
int	$port
string	$path
string	$query
string	$fragment

Note

Automatically normalizes scheme and port

Definition at line 58 of file URI.php.

References $fragment, $host, $path, $port, $query, $scheme, and $userinfo.

    {
        $this->scheme = is_null($scheme) || ctype_lower($scheme) ? $scheme : strtolower($scheme);
        $this->userinfo = $userinfo;
        $this->host = $host;
        $this->port = is_null($port) ? $port : (int)$port;
        $this->path = $path;
        $this->query = $query;
        $this->fragment = $fragment;
    }

Member Function Documentation

getSchemeObj()

HTMLPurifier_URI::getSchemeObj	(		$config,
			$context
	)

Retrieves a scheme object corresponding to the URI's scheme/default.

Parameters

HTMLPurifier_Config	$config
HTMLPurifier_Context	$context

Returns

HTMLPurifier_URIScheme Scheme object appropriate for validating this URI

Definition at line 75 of file URI.php.

References $config, $def, and HTMLPurifier_URISchemeRegistry\instance().

Referenced by isBenign().

    {
        $registry = HTMLPurifier_URISchemeRegistry::instance();
        if ($this->scheme !== null) {
            $scheme_obj = $registry->getScheme($this->scheme, $config, $context);
            if (!$scheme_obj) {
                return false;
            } // invalid scheme, clean it out
        } else {
            // no scheme: retrieve the default one
            $def = $config->getDefinition('URI');
            $scheme_obj = $def->getDefaultScheme($config, $context);
            if (!$scheme_obj) {
                if ($def->defaultScheme !== null) {
                    // something funky happened to the default scheme object
                    trigger_error(
                        'Default scheme object "' . $def->defaultScheme . '" was not readable',
                        E_USER_WARNING
                    );
                } // suppress error if it's null
                return false;
            }
        }
        return $scheme_obj;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

isBenign()

HTMLPurifier_URI::isBenign	(		$config,
			$context
	)

Returns true if this URL should be considered a 'benign' URL, that is:

• It is a local URL (isLocal), and
• It has a equal or better level of security

  Parameters

  HTMLPurifier_Config	$config
  HTMLPurifier_Context	$context

  Returns

  bool

Definition at line 295 of file URI.php.

References $config, getSchemeObj(), and isLocal().

    {
        if (!$this->isLocal($config, $context)) {
            return false;
        }

        $scheme_obj = $this->getSchemeObj($config, $context);
        if (!$scheme_obj) {
            return false;
        } // conservative approach

        $current_scheme_obj = $config->getDefinition('URI')->getDefaultScheme($config, $context);
        if ($current_scheme_obj->secure) {
            if (!$scheme_obj->secure) {
                return false;
            }
        }
        return true;
    }

Here is the call graph for this function:

isLocal()

HTMLPurifier_URI::isLocal	(		$config,
			$context
	)

Returns true if this URL might be considered a 'local' URL given the current context.

This is true when the host is null, or when it matches the host supplied to the configuration.

Note that this does not do any scheme checking, so it is mostly only appropriate for metadata that doesn't care about protocol security. isBenign is probably what you actually want.

Parameters

HTMLPurifier_Config	$config
HTMLPurifier_Context	$context

Returns

bool

Definition at line 273 of file URI.php.

References $config.

Referenced by isBenign().

    {
        if ($this->host === null) {
            return true;
        }
        $uri_def = $config->getDefinition('URI');
        if ($uri_def->host === $this->host) {
            return true;
        }
        return false;
    }

Here is the caller graph for this function:

toString()

HTMLPurifier_URI::toString

(

)

Convert URI back to string.

Returns

string URI appropriate for output

Definition at line 219 of file URI.php.

References $authority, $fragment, $host, $path, $port, $query, and $result.

    {
        // reconstruct authority
        $authority = null;
        // there is a rendering difference between a null authority
        // (http:foo-bar) and an empty string authority
        // (http:///foo-bar).
        if (!is_null($this->host)) {
            $authority = '';
            if (!is_null($this->userinfo)) {
                $authority .= $this->userinfo . '@';
            }
            $authority .= $this->host;
            if (!is_null($this->port)) {
                $authority .= ':' . $this->port;
            }
        }

        // Reconstruct the result
        // One might wonder about parsing quirks from browsers after
        // this reconstruction.  Unfortunately, parsing behavior depends
        // on what *scheme* was employed (file:///foo is handled *very*
        // differently than http:///foo), so unfortunately we have to
        // defer to the schemes to do the right thing.
        $result = '';
        if (!is_null($this->scheme)) {
            $result .= $this->scheme . ':';
        }
        if (!is_null($authority)) {
            $result .= '//' . $authority;
        }
        $result .= $this->path;
        if (!is_null($this->query)) {
            $result .= '?' . $this->query;
        }
        if (!is_null($this->fragment)) {
            $result .= '#' . $this->fragment;
        }

        return $result;
    }

validate()

HTMLPurifier_URI::validate	(		$config,
			$context
	)

Generic validation method applicable for all schemes.

May modify this URI in order to get it into a compliant form.

Parameters

HTMLPurifier_Config	$config
HTMLPurifier_Context	$context

Returns

bool True if validation/filtering succeeds, false if failure

Definition at line 108 of file URI.php.

References $config, and $def.

    {
        // ABNF definitions from RFC 3986
        $chars_sub_delims = '!$&\'()*+,;=';
        $chars_gen_delims = ':/?#[]@';
        $chars_pchar = $chars_sub_delims . ':@';

        // validate host
        if (!is_null($this->host)) {
            $host_def = new HTMLPurifier_AttrDef_URI_Host();
            $this->host = $host_def->validate($this->host, $config, $context);
            if ($this->host === false) {
                $this->host = null;
            }
        }

        // validate scheme
        // NOTE: It's not appropriate to check whether or not this
        // scheme is in our registry, since a URIFilter may convert a
        // URI that we don't allow into one we do.  So instead, we just
        // check if the scheme can be dropped because there is no host
        // and it is our default scheme.
        if (!is_null($this->scheme) && is_null($this->host) || $this->host === '') {
            // support for relative paths is pretty abysmal when the
            // scheme is present, so axe it when possible
            $def = $config->getDefinition('URI');
            if ($def->defaultScheme === $this->scheme) {
                $this->scheme = null;
            }
        }

        // validate username
        if (!is_null($this->userinfo)) {
            $encoder = new HTMLPurifier_PercentEncoder($chars_sub_delims . ':');
            $this->userinfo = $encoder->encode($this->userinfo);
        }

        // validate port
        if (!is_null($this->port)) {
            if ($this->port < 1 || $this->port > 65535) {
                $this->port = null;
            }
        }

        // validate path
        $segments_encoder = new HTMLPurifier_PercentEncoder($chars_pchar . '/');
        if (!is_null($this->host)) { // this catches $this->host === ''
            // path-abempty (hier and relative)
            // http://www.example.com/my/path
            // //www.example.com/my/path (looks odd, but works, and
            //                            recognized by most browsers)
            // (this set is valid or invalid on a scheme by scheme
            // basis, so we'll deal with it later)
            // file:///my/path
            // ///my/path
            $this->path = $segments_encoder->encode($this->path);
        } elseif ($this->path !== '') {
            if ($this->path[0] === '/') {
                // path-absolute (hier and relative)
                // http:/my/path
                // /my/path
                if (strlen($this->path) >= 2 && $this->path[1] === '/') {
                    // This could happen if both the host gets stripped
                    // out
                    // http://my/path
                    // //my/path
                    $this->path = '';
                } else {
                    $this->path = $segments_encoder->encode($this->path);
                }
            } elseif (!is_null($this->scheme)) {
                // path-rootless (hier)
                // http:my/path
                // Short circuit evaluation means we don't need to check nz
                $this->path = $segments_encoder->encode($this->path);
            } else {
                // path-noscheme (relative)
                // my/path
                // (once again, not checking nz)
                $segment_nc_encoder = new HTMLPurifier_PercentEncoder($chars_sub_delims . '@');
                $c = strpos($this->path, '/');
                if ($c !== false) {
                    $this->path =
                        $segment_nc_encoder->encode(substr($this->path, 0, $c)) .
                        $segments_encoder->encode(substr($this->path, $c));
                } else {
                    $this->path = $segment_nc_encoder->encode($this->path);
                }
            }
        } else {
            // path-empty (hier and relative)
            $this->path = ''; // just to be safe
        }

        // qf = query and fragment
        $qf_encoder = new HTMLPurifier_PercentEncoder($chars_pchar . '/?');

        if (!is_null($this->query)) {
            $this->query = $qf_encoder->encode($this->query);
        }

        if (!is_null($this->fragment)) {
            $this->fragment = $qf_encoder->encode($this->fragment);
        }
        return true;
    }

Field Documentation

$fragment

HTMLPurifier_URI::$fragment

string

Definition at line 46 of file URI.php.

Referenced by __construct(), and toString().

$host

HTMLPurifier_URI::$host

string

Definition at line 26 of file URI.php.

Referenced by __construct(), and toString().

$path

HTMLPurifier_URI::$path

string

Definition at line 36 of file URI.php.

Referenced by __construct(), and toString().

$port

HTMLPurifier_URI::$port

int

Definition at line 31 of file URI.php.

Referenced by __construct(), and toString().

$query

HTMLPurifier_URI::$query

string

Definition at line 41 of file URI.php.

Referenced by __construct(), and toString().

$scheme

HTMLPurifier_URI::$scheme

string

Definition at line 16 of file URI.php.

Referenced by __construct().

$userinfo

HTMLPurifier_URI::$userinfo

string

Definition at line 21 of file URI.php.

Referenced by __construct().

---

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

• libs/composer/vendor/ezyang/htmlpurifier/library/HTMLPurifier/URI.php