Generic URI handler. More...

Public Member Functions
	__construct ($uri=null)
	Create a new URI object.

	isValid ()
	Check if the URI is valid.

	isValidRelative ()
	Check if the URI is a valid relative URI.

	isAbsolute ()
	Check if the URI is an absolute or relative URI.

	parse ($uri)
	Parse a URI string.

	toString ()
	Compose the URI into a string.

	normalize ()
	Normalize the URI.

	resolve ($baseUri)
	Convert a relative URI into an absolute URI using a base absolute URI as a reference.

	makeRelative ($baseUri)
	Convert the link to a relative link by substracting a base URI.

	getScheme ()
	Get the scheme part of the URI.

	getUserInfo ()
	Get the User-info (usually user:password) part.

	getHost ()
	Get the URI host.

	getPort ()
	Get the URI port.

	getPath ()
	Get the URI path.

	getQuery ()
	Get the URI query.

	getQueryAsArray ()
	Return the query string as an associative array of key => value pairs.

	getFragment ()
	Get the URI fragment.

	setScheme ($scheme)
	Set the URI scheme.

	setUserInfo ($userInfo)
	Set the URI User-info part (usually user:password)

	setHost ($host)
	Set the URI host.

	setPort ($port)
	Set the port part of the URI.

	setPath ($path)
	Set the path.

	setQuery ($query)
	Set the query string.

	setFragment ($fragment)
	Set the URI fragment part.

	__toString ()
	Magic method to convert the URI to a string.

Static Public Member Functions
static	setEscaper (Escaper $escaper)
	Set Escaper instance.

static	getEscaper ()
	Retrieve Escaper instance.

static	validateScheme ($scheme)
	Encoding and Validation Methods.

static	validateUserInfo ($userInfo)
	Check that the userInfo part of a URI is valid.

static	validateHost ($host, $allowed=self::HOST_ALL)
	Validate the host part.

static	validatePort ($port)
	Validate the port.

static	validatePath ($path)
	Validate the path.

static	validateQueryFragment ($input)
	Check if a URI query or fragment part is valid or not.

static	encodeUserInfo ($userInfo)
	URL-encode the user info part of a URI.

static	encodePath ($path)
	Encode the path.

static	encodeQueryFragment ($input)
	URL-encode a query string or fragment based on RFC-3986 guidelines.

static	parseScheme ($uriString)
	Extract only the scheme part out of a URI string.

static	removePathDotSegments ($path)
	Remove any extra dot segments (/../, /.

static	merge ($baseUri, $relativeUri)
	Merge a base URI and a relative URI into a new URI object.

Public Attributes
const	CHAR_UNRESERVED = 'a-zA-Z0-9_\-\.~'
	Character classes defined in RFC-3986.

const	CHAR_GEN_DELIMS = ':\/\?#\[\]@'

const	CHAR_SUB_DELIMS = '!\$&\'\*\+,;='

const	CHAR_RESERVED = ':\/\?#\[\]@!\$&\'\*\+,;='

const	CHAR_QUERY_DELIMS = '!\$\'\*\,'
	Not in the spec - those characters have special meaning in urlencoded query parameters.

const	HOST_IPV4 = 0x01
	Host part types represented as binary masks The binary mask consists of 5 bits in the following order: <RegName> \| <DNS> \| <IPvFuture> \| <IPv6> \| <IPv4> Place 1 or 0 in the different positions for enable or disable the part.

const	HOST_IPV6 = 0x02

const	HOST_IPVFUTURE = 0x04

const	HOST_IPVANY = 0x07

const	HOST_DNS = 0x08

const	HOST_DNS_OR_IPV4 = 0x09

const	HOST_DNS_OR_IPV6 = 0x0A

const	HOST_DNS_OR_IPV4_OR_IPV6 = 0x0B

const	HOST_DNS_OR_IPVANY = 0x0F

const	HOST_REGNAME = 0x10

const	HOST_DNS_OR_IPV4_OR_IPV6_OR_REGNAME = 0x1B

const	HOST_ALL = 0x1F

Protected Member Functions
	reset ()
	Reset URI parts.

Static Protected Member Functions
static	isValidIpAddress ($host, $allowed)
	Check if a host name is a valid IP address, depending on allowed IP address types.

static	isValidDnsHostname ($host)
	Check if an address is a valid DNS hostname.

static	isValidRegName ($host)
	Check if an address is a valid registered name (as defined by RFC-3986) address.

static	normalizeScheme ($scheme)
	Part normalization methods.

static	normalizeHost ($host)
	Normalize the host part.

static	normalizePort ($port, $scheme=null)
	Normalize the port.

static	normalizePath ($path)
	Normalize the path.

static	normalizeQuery ($query)
	Normalize the query part.

static	normalizeFragment ($fragment)
	Normalize the fragment part.

static	decodeUrlEncodedChars ($input, $allowed= '')
	Decode all percent encoded characters which are allowed to be represented literally.

Protected Attributes
	$scheme

	$userInfo

	$host

	$port

	$path

	$query

	$fragment

	$validHostTypes = self::HOST_ALL

Static Protected Attributes
static	$validSchemes = []

static	$defaultPorts = []

static	$escaper

Detailed Description

Generic URI handler.

Constructor & Destructor Documentation

__construct ( $uri = null )

Create a new URI object.

Parameters

Uri | string | null $uri

Exceptions

Exception\InvalidArgumentException

Implements UriInterface.

Member Function Documentation

__toString ( )

Magic method to convert the URI to a string.

Returns: string

Implements UriInterface.

static decodeUrlEncodedChars	(	$input,
		$allowed = `''`
	)

staticprotected

Decode all percent encoded characters which are allowed to be represented literally.

Will not decode any characters which are not listed in the 'allowed' list

Parameters

string	$input
string	$allowed	Pattern of allowed characters

Returns: mixed

static encodePath ( $path )

static

Encode the path.

Will replace all characters which are not strictly allowed in the path part with percent-encoded representation

Parameters

string $path

Exceptions

Exception\InvalidArgumentException

Returns: string

static encodeQueryFragment ( $input )

static

URL-encode a query string or fragment based on RFC-3986 guidelines.

Note that query and fragment encoding allows more unencoded characters than the usual rawurlencode() function would usually return - for example '/' and ':' are allowed as literals.

Parameters

string $input

Returns: string

Exceptions

Exception\InvalidArgumentException

static encodeUserInfo ( $userInfo )

static

URL-encode the user info part of a URI.

Parameters

string $userInfo

Returns: string

Exceptions

Exception\InvalidArgumentException

static getEscaper ( )

static

Retrieve Escaper instance.

Lazy-loads one if none provided

Returns: Escaper

getFragment ( )

Get the URI fragment.

Returns: string|null

Implements UriInterface.

getHost ( )

Get the URI host.

Returns: string|null

Implements UriInterface.

getPath ( )

Get the URI path.

Returns: string|null

Implements UriInterface.

getPort ( )

Get the URI port.

Returns: int|null

Implements UriInterface.

getQuery ( )

Get the URI query.

Returns: string|null

Implements UriInterface.

getQueryAsArray ( )

Return the query string as an associative array of key => value pairs.

This is an extension to RFC-3986 but is quite useful when working with most common URI types

Returns: array

Implements UriInterface.

getScheme ( )

Get the scheme part of the URI.

Returns: string|null

Implements UriInterface.

getUserInfo ( )

Get the User-info (usually user:password) part.

Returns: string|null

Implements UriInterface.

isAbsolute ( )

Check if the URI is an absolute or relative URI.

Returns: bool

Implements UriInterface.

isValid ( )

Check if the URI is valid.

Note that a relative URI may still be valid

Returns: bool

Implements UriInterface.

static isValidDnsHostname ( $host )

staticprotected

Check if an address is a valid DNS hostname.

Parameters

string $host

Returns: bool

static isValidIpAddress	(	$host,
		$allowed
	)

staticprotected

Check if a host name is a valid IP address, depending on allowed IP address types.

Parameters

string	$host
int	$allowed	allowed address types

Returns: bool

static isValidRegName ( $host )

staticprotected

Check if an address is a valid registered name (as defined by RFC-3986) address.

Parameters

string $host

Returns: bool

isValidRelative ( )

Check if the URI is a valid relative URI.

Returns: bool

Implements UriInterface.

makeRelative ( $baseUri )

Convert the link to a relative link by substracting a base URI.

This is the opposite of resolving a relative link - i.e. creating a relative reference link from an original URI and a base URI.

If the two URIs do not intersect (e.g. the original URI is not in any way related to the base URI) the URI will not be modified.

Parameters

Uri | string $baseUri

Returns: Uri

Implements UriInterface.

static merge	(	$baseUri,
		$relativeUri
	)

static

Merge a base URI and a relative URI into a new URI object.

This convenience method wraps ::resolve() to allow users to quickly create new absolute URLs without the need to instantiate and clone URI objects.

If objects are passed in, none of the passed objects will be modified.

Parameters

Uri \| string	$baseUri
Uri \| string	$relativeUri

Returns: Uri

normalize ( )

Normalize the URI.

Normalizing a URI includes removing any redundant parent directory or current directory references from the path (e.g. foo/bar/../baz becomes foo/baz), normalizing the scheme case, decoding any over-encoded characters etc.

Eventually, two normalized URLs pointing to the same resource should be equal even if they were originally represented by two different strings

Returns: Uri

Implements UriInterface.

static normalizeFragment ( $fragment )

staticprotected

Normalize the fragment part.

Currently this is exactly the same as normalizeQuery().

Parameters

string $fragment

Returns: string

static normalizeHost ( $host )

staticprotected

Normalize the host part.

By default this converts host names to lower case

Parameters

string $host

Returns: string

static normalizePath ( $path )

staticprotected

Normalize the path.

This involves removing redundant dot segments, decoding any over-encoded characters and encoding everything that needs to be encoded and is not

Parameters

string $path

Returns: string

static normalizePort	(	$port,
		$scheme = `null`
	)

staticprotected

Normalize the port.

If the class defines a default port for the current scheme, and the current port is default, it will be unset.

Parameters

int	$port
string	$scheme

Returns: int|null

static normalizeQuery ( $query )

staticprotected

Normalize the query part.

This involves decoding everything that doesn't need to be encoded, and encoding everything else

Parameters

string $query

Returns: string

static normalizeScheme ( $scheme )

staticprotected

Part normalization methods.

These are called by normalize() using static::_normalize*() so they may be extended or overridden by extending classes to implement additional scheme specific normalization rules Normalize the scheme

Usually this means simply converting the scheme to lower case

Parameters

string $scheme

Returns: string

parse ( $uri )

Parse a URI string.

Parameters

string $uri

Returns: Uri

Implements UriInterface.

static parseScheme ( $uriString )

static

Extract only the scheme part out of a URI string.

This is used by the parse() method, but is useful as a standalone public method if one wants to test a URI string for it's scheme before doing anything with it.

Will return the scheme if found, or NULL if no scheme found (URI may still be valid, but not full)

Parameters

string $uriString

Exceptions

Exception\InvalidArgumentException

Returns: string|null

static removePathDotSegments ( $path )

static

Remove any extra dot segments (/../, /.

/) from a path

Algorithm is adapted from RFC-3986 section 5.2.4 (todo 59. string $path string

reset ( )

protected

Reset URI parts.

resolve ( $baseUri )

Convert a relative URI into an absolute URI using a base absolute URI as a reference.

This is similar to merge() - only it uses the supplied URI as the base reference instead of using the current URI as the base reference.

Merging algorithm is adapted from RFC-3986 section 5.2 (Uri|string $baseUri Exception Uri

static setEscaper ( Escaper $escaper )

static

Set Escaper instance.

Parameters

Escaper $escaper

setFragment ( $fragment )

Set the URI fragment part.

Parameters

string $fragment

Returns: Uri

Exceptions

Exception\InvalidUriPartException If the schema definition does not have this part

Implements UriInterface.

setHost ( $host )

Set the URI host.

Note that the generic syntax for URIs allows using host names which are not necessarily IPv4 addresses or valid DNS host names. For example, IPv6 addresses are allowed as well, and also an abstract "registered name" which may be any name composed of a valid set of characters, including, for example, tilda (~) and underscore (_) which are not allowed in DNS names.

Subclasses of Uri may impose more strict validation of host names - for example the HTTP RFC clearly states that only IPv4 and valid DNS names are allowed in HTTP URIs.

Parameters

string $host

Exceptions

Exception\InvalidUriPartException

Returns: Uri

Implements UriInterface.

setPath ( $path )

Set the path.

Parameters

string $path

Returns: Uri

Implements UriInterface.

setPort ( $port )

Set the port part of the URI.

Parameters

int $port

Returns: Uri

Implements UriInterface.

setQuery ( $query )

Set the query string.

If an array is provided, will encode this array of parameters into a query string. Array values will be represented in the query string using PHP's common square bracket notation.

Parameters

string | array $query

Returns: Uri

Implements UriInterface.

setScheme ( $scheme )

Set the URI scheme.

If the scheme is not valid according to the generic scheme syntax or is not acceptable by the specific URI class (e.g. 'http' or 'https' are the only acceptable schemes for the Zend class) an exception will be thrown.

You can check if a scheme is valid before setting it using the validateScheme() method.

Parameters

string $scheme

Exceptions

Exception\InvalidUriPartException

Returns: Uri

Implements UriInterface.

setUserInfo ( $userInfo )

Set the URI User-info part (usually user:password)

Parameters

string $userInfo

Returns: Uri

Exceptions

Exception\InvalidUriPartException If the schema definition does not have this part

Implements UriInterface.

toString ( )

Compose the URI into a string.

Returns: string

Exceptions

Exception\InvalidUriException

Implements UriInterface.

static validateHost	(	$host,
		$allowed = `self::HOST_ALL`
	)

static

Validate the host part.

Users may control which host types to allow by passing a second parameter with a bitmask of HOST_* constants which are allowed. If not specified, all address types will be allowed.

Note that the generic URI syntax allows different host representations, including IPv4 addresses, IPv6 addresses and future IP address formats enclosed in square brackets, and registered names which may be DNS names or even more complex names. This is different (and is much more loose) from what is commonly accepted as valid HTTP URLs for example.

Parameters

string	$host
int	$allowed	bitmask of allowed host types

Returns: bool

static validatePath ( $path )

static

Validate the path.

Parameters

string $path

Returns: bool

static validatePort ( $port )

static

Validate the port.

Valid values include numbers between 1 and 65535, and empty values

Parameters

int $port

Returns: bool

static validateQueryFragment ( $input )

static

Check if a URI query or fragment part is valid or not.

Query and Fragment parts are both restricted by the same syntax rules, so the same validation method can be used for both.

You can encode a query or fragment part to ensure it is valid by passing it through the encodeQueryFragment() method.

Parameters

string $input

Returns: bool

static validateScheme ( $scheme )

static

Encoding and Validation Methods.

Check if a scheme is valid or not

Will check $scheme to be valid against the generic scheme syntax defined in RFC-3986. If the class also defines specific acceptable schemes, will also check that $scheme is one of them.

Parameters

string $scheme

Returns: bool

static validateUserInfo ( $userInfo )

static

Check that the userInfo part of a URI is valid.

Parameters

string $userInfo

Returns: bool

Member Data Documentation

$defaultPorts = []

staticprotected

$escaper

staticprotected

$fragment

protected

$host

protected

$path

protected

$port

protected

$query

protected

$scheme

protected

$userInfo

protected

$validHostTypes = self::HOST_ALL

protected

$validSchemes = []

staticprotected

const CHAR_GEN_DELIMS = ':\/\?#\[\]@'

const CHAR_QUERY_DELIMS = '!\$\'\*\,'

Not in the spec - those characters have special meaning in urlencoded query parameters.

const CHAR_RESERVED = ':\/\?#\[\]@!\$&\'\*\+,;='

const CHAR_SUB_DELIMS = '!\$&\'\*\+,;='

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

Character classes defined in RFC-3986.

const HOST_ALL = 0x1F

const HOST_DNS = 0x08

const HOST_DNS_OR_IPV4 = 0x09

const HOST_DNS_OR_IPV4_OR_IPV6 = 0x0B

const HOST_DNS_OR_IPV4_OR_IPV6_OR_REGNAME = 0x1B

const HOST_DNS_OR_IPV6 = 0x0A

const HOST_DNS_OR_IPVANY = 0x0F

const HOST_IPV4 = 0x01

Host part types represented as binary masks The binary mask consists of 5 bits in the following order: <RegName> | <DNS> | <IPvFuture> | <IPv6> | <IPv4> Place 1 or 0 in the different positions for enable or disable the part.

Finally use a hexadecimal representation.

const HOST_IPV6 = 0x02

const HOST_IPVANY = 0x07

const HOST_IPVFUTURE = 0x04

const HOST_REGNAME = 0x10

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation