Uri
in package
implements
UriInterface
Generic URI handler
Table of Contents
Interfaces
- UriInterface
- Interface defining a URI
Constants
- CHAR_GEN_DELIMS = ':\/\?#\[\]@'
- CHAR_QUERY_DELIMS = '!\$\'\(\)\*\,'
- Not in the spec - those characters have special meaning in urlencoded query parameters
- CHAR_RESERVED = ':\/\?#\[\]@!\$&\'\(\)\*\+,;='
- CHAR_SUB_DELIMS = '!\$&\'\(\)\*\+,;='
- CHAR_UNRESERVED = 'a-zA-Z0-9_\-\.~'
- Character classes defined in RFC-3986
- HOST_ALL = 0x1f
- HOST_DNS = 0x8
- HOST_DNS_OR_IPV4 = 0x9
- HOST_DNS_OR_IPV4_OR_IPV6 = 0xb
- HOST_DNS_OR_IPV4_OR_IPV6_OR_REGNAME = 0x1b
- HOST_DNS_OR_IPV6 = 0xa
- HOST_DNS_OR_IPVANY = 0xf
- HOST_IPV4 = 0x1
- 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.
- HOST_IPV6 = 0x2
- HOST_IPVANY = 0x7
- HOST_IPVFUTURE = 0x4
- HOST_REGNAME = 0x10
Properties
- $defaultPorts : array<string|int, mixed>
- List of default ports per scheme
- $escaper : Escaper
- $fragment : string
- URI fragment|null
- $host : string|null
- URI hostname
- $path : string|null
- URI path
- $port : int|null
- URI port
- $query : string|null
- URI query string
- $scheme : string|null
- URI scheme
- $userInfo : string|null
- URI userInfo part (usually user:password in HTTP URLs)
- $validHostTypes : int
- Which host part types are valid for this URI?
- $validSchemes : array<string|int, mixed>
- Array of valid schemes.
Methods
- __construct() : mixed
- Create a new URI object
- __toString() : string
- Magic method to convert the URI to a string
- encodePath() : string
- Encode the path
- encodeQueryFragment() : string
- URL-encode a query string or fragment based on RFC-3986 guidelines.
- encodeUserInfo() : string
- URL-encode the user info part of a URI
- getEscaper() : Escaper
- Retrieve Escaper instance
- getFragment() : string|null
- Get the URI fragment
- getHost() : string|null
- Get the URI host
- getPath() : string|null
- Get the URI path
- getPort() : int|null
- Get the URI port
- getQuery() : string|null
- Get the URI query
- getQueryAsArray() : array<string|int, mixed>
- Return the query string as an associative array of key => value pairs
- getScheme() : string|null
- Get the scheme part of the URI
- getUserInfo() : string|null
- Get the User-info (usually user:password) part
- isAbsolute() : bool
- Check if the URI is an absolute or relative URI
- isValid() : bool
- Check if the URI is valid
- isValidRelative() : bool
- Check if the URI is a valid relative URI
- makeRelative() : Uri
- Convert the link to a relative link by substracting a base URI
- merge() : Uri
- Merge a base URI and a relative URI into a new URI object
- normalize() : Uri
- Normalize the URI
- parse() : Uri
- Parse a URI string
- parseScheme() : string|null
- Extract only the scheme part out of a URI string.
- removePathDotSegments() : string
- Remove any extra dot segments (/../, /./) from a path
- resolve() : Uri
- Convert a relative URI into an absolute URI using a base absolute URI as a reference.
- setEscaper() : mixed
- Set Escaper instance
- setFragment() : Uri
- Set the URI fragment part
- setHost() : Uri
- Set the URI host
- setPath() : Uri
- Set the path
- setPort() : Uri
- Set the port part of the URI
- setQuery() : Uri
- Set the query string
- setScheme() : Uri
- Set the URI scheme
- setUserInfo() : Uri
- Set the URI User-info part (usually user:password)
- toString() : string
- Compose the URI into a string
- validateHost() : bool
- Validate the host part
- validatePath() : bool
- Validate the path
- validatePort() : bool
- Validate the port
- validateQueryFragment() : bool
- Check if a URI query or fragment part is valid or not
- validateScheme() : bool
- Check if a scheme is valid or not
- validateUserInfo() : bool
- Check that the userInfo part of a URI is valid
- decodeUrlEncodedChars() : mixed
- Decode all percent encoded characters which are allowed to be represented literally
- isValidDnsHostname() : bool
- Check if an address is a valid DNS hostname
- isValidIpAddress() : bool
- Check if a host name is a valid IP address, depending on allowed IP address types
- isValidRegName() : bool
- Check if an address is a valid registered name (as defined by RFC-3986) address
- normalizeFragment() : string
- Normalize the fragment part
- normalizeHost() : string
- Normalize the host part
- normalizePath() : string
- Normalize the path
- normalizePort() : int|null
- Normalize the port
- normalizeQuery() : string
- Normalize the query part
- normalizeScheme() : string
- Normalize the scheme
- reset() : mixed
- Reset URI parts
Constants
CHAR_GEN_DELIMS
public
mixed
CHAR_GEN_DELIMS
= ':\/\?#\[\]@'
CHAR_QUERY_DELIMS
Not in the spec - those characters have special meaning in urlencoded query parameters
public
mixed
CHAR_QUERY_DELIMS
= '!\$\'\(\)\*\,'
CHAR_RESERVED
public
mixed
CHAR_RESERVED
= ':\/\?#\[\]@!\$&\'\(\)\*\+,;='
CHAR_SUB_DELIMS
public
mixed
CHAR_SUB_DELIMS
= '!\$&\'\(\)\*\+,;='
CHAR_UNRESERVED
Character classes defined in RFC-3986
public
mixed
CHAR_UNRESERVED
= 'a-zA-Z0-9_\-\.~'
HOST_ALL
public
mixed
HOST_ALL
= 0x1f
HOST_DNS
public
mixed
HOST_DNS
= 0x8
HOST_DNS_OR_IPV4
public
mixed
HOST_DNS_OR_IPV4
= 0x9
HOST_DNS_OR_IPV4_OR_IPV6
public
mixed
HOST_DNS_OR_IPV4_OR_IPV6
= 0xb
HOST_DNS_OR_IPV4_OR_IPV6_OR_REGNAME
public
mixed
HOST_DNS_OR_IPV4_OR_IPV6_OR_REGNAME
= 0x1b
HOST_DNS_OR_IPV6
public
mixed
HOST_DNS_OR_IPV6
= 0xa
HOST_DNS_OR_IPVANY
public
mixed
HOST_DNS_OR_IPVANY
= 0xf
HOST_IPV4
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.
public
mixed
HOST_IPV4
= 0x1
Finally use a hexadecimal representation.
HOST_IPV6
public
mixed
HOST_IPV6
= 0x2
HOST_IPVANY
public
mixed
HOST_IPVANY
= 0x7
HOST_IPVFUTURE
public
mixed
HOST_IPVFUTURE
= 0x4
HOST_REGNAME
public
mixed
HOST_REGNAME
= 0x10
Properties
$defaultPorts
List of default ports per scheme
protected
static array<string|int, mixed>
$defaultPorts
= []
Inheriting URI classes may set this, and the normalization methods will automatically remove the port if it is equal to the default port for the current scheme
$escaper
protected
static Escaper
$escaper
$fragment
URI fragment|null
protected
string
$fragment
$host
URI hostname
protected
string|null
$host
$path
URI path
protected
string|null
$path
$port
URI port
protected
int|null
$port
$query
URI query string
protected
string|null
$query
$scheme
URI scheme
protected
string|null
$scheme
$userInfo
URI userInfo part (usually user:password in HTTP URLs)
protected
string|null
$userInfo
$validHostTypes
Which host part types are valid for this URI?
protected
int
$validHostTypes
= self::HOST_ALL
$validSchemes
Array of valid schemes.
protected
static array<string|int, mixed>
$validSchemes
= []
Subclasses of this class that only accept specific schemes may set the list of accepted schemes here. If not empty, when setScheme() is called it will only accept the schemes listed here.
Methods
__construct()
Create a new URI object
public
__construct([Uri|string|null $uri = null ]) : mixed
Parameters
- $uri : Uri|string|null = null
Tags
__toString()
Magic method to convert the URI to a string
public
__toString() : string
Return values
stringencodePath()
Encode the path
public
static encodePath(string $path) : string
Will replace all characters which are not strictly allowed in the path part with percent-encoded representation
Parameters
- $path : string
Tags
Return values
stringencodeQueryFragment()
URL-encode a query string or fragment based on RFC-3986 guidelines.
public
static encodeQueryFragment(string $input) : string
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
- $input : string
Tags
Return values
stringencodeUserInfo()
URL-encode the user info part of a URI
public
static encodeUserInfo(string $userInfo) : string
Parameters
- $userInfo : string
Tags
Return values
stringgetEscaper()
Retrieve Escaper instance
public
static getEscaper() : Escaper
Lazy-loads one if none provided
Return values
EscapergetFragment()
Get the URI fragment
public
getFragment() : string|null
Return values
string|nullgetHost()
Get the URI host
public
getHost() : string|null
Return values
string|nullgetPath()
Get the URI path
public
getPath() : string|null
Return values
string|nullgetPort()
Get the URI port
public
getPort() : int|null
Return values
int|nullgetQuery()
Get the URI query
public
getQuery() : string|null
Return values
string|nullgetQueryAsArray()
Return the query string as an associative array of key => value pairs
public
getQueryAsArray() : array<string|int, mixed>
This is an extension to RFC-3986 but is quite useful when working with most common URI types
Return values
array<string|int, mixed>getScheme()
Get the scheme part of the URI
public
getScheme() : string|null
Return values
string|nullgetUserInfo()
Get the User-info (usually user:password) part
public
getUserInfo() : string|null
Return values
string|nullisAbsolute()
Check if the URI is an absolute or relative URI
public
isAbsolute() : bool
Return values
boolisValid()
Check if the URI is valid
public
isValid() : bool
Note that a relative URI may still be valid
Return values
boolisValidRelative()
Check if the URI is a valid relative URI
public
isValidRelative() : bool
Return values
boolmakeRelative()
Convert the link to a relative link by substracting a base URI
public
makeRelative(Uri|string $baseUri) : 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
- $baseUri : Uri|string
Return values
Urimerge()
Merge a base URI and a relative URI into a new URI object
public
static merge(Uri|string $baseUri, Uri|string $relativeUri) : Uri
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
Return values
Urinormalize()
Normalize the URI
public
normalize() : 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
Return values
Uriparse()
Parse a URI string
public
parse(string $uri) : Uri
Parameters
- $uri : string
Return values
UriparseScheme()
Extract only the scheme part out of a URI string.
public
static parseScheme(string $uriString) : string|null
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
- $uriString : string
Tags
Return values
string|nullremovePathDotSegments()
Remove any extra dot segments (/../, /./) from a path
public
static removePathDotSegments(string $path) : string
Algorithm is adapted from RFC-3986 section 5.2.4 (@link http://tools.ietf.org/html/rfc3986#section-5.2.4)
Parameters
- $path : string
Tags
Return values
stringresolve()
Convert a relative URI into an absolute URI using a base absolute URI as a reference.
public
resolve(Uri|string $baseUri) : Uri
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 (@link http://tools.ietf.org/html/rfc3986#section-5.2)
Parameters
- $baseUri : Uri|string
Tags
Return values
UrisetEscaper()
Set Escaper instance
public
static setEscaper(Escaper $escaper) : mixed
Parameters
- $escaper : Escaper
setFragment()
Set the URI fragment part
public
setFragment(string|null $fragment) : Uri
Parameters
- $fragment : string|null
Tags
Return values
UrisetHost()
Set the URI host
public
setHost(string|null $host) : Uri
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
- $host : string|null
Tags
Return values
UrisetPath()
Set the path
public
setPath(string|null $path) : Uri
Parameters
- $path : string|null
Return values
UrisetPort()
Set the port part of the URI
public
setPort(int|null $port) : Uri
Parameters
- $port : int|null
Return values
UrisetQuery()
Set the query string
public
setQuery(string|array<string|int, mixed>|null $query) : Uri
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
- $query : string|array<string|int, mixed>|null
Return values
UrisetScheme()
Set the URI scheme
public
setScheme(string|null $scheme) : Uri
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 Laminas\Uri\Http class) an exception will be thrown.
You can check if a scheme is valid before setting it using the validateScheme() method.
Parameters
- $scheme : string|null
Tags
Return values
UrisetUserInfo()
Set the URI User-info part (usually user:password)
public
setUserInfo(string|null $userInfo) : Uri
Parameters
- $userInfo : string|null
Tags
Return values
UritoString()
Compose the URI into a string
public
toString() : string
Tags
Return values
stringvalidateHost()
Validate the host part
public
static validateHost(string $host[, int $allowed = self::HOST_ALL ]) : bool
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
- $host : string
- $allowed : int = self::HOST_ALL
-
bitmask of allowed host types
Return values
boolvalidatePath()
Validate the path
public
static validatePath(string $path) : bool
Parameters
- $path : string
Return values
boolvalidatePort()
Validate the port
public
static validatePort(int $port) : bool
Valid values include numbers between 1 and 65535, and empty values
Parameters
- $port : int
Return values
boolvalidateQueryFragment()
Check if a URI query or fragment part is valid or not
public
static validateQueryFragment(string $input) : bool
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
- $input : string
Return values
boolvalidateScheme()
Check if a scheme is valid or not
public
static validateScheme(string $scheme) : bool
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
- $scheme : string
Return values
boolvalidateUserInfo()
Check that the userInfo part of a URI is valid
public
static validateUserInfo(string $userInfo) : bool
Parameters
- $userInfo : string
Return values
booldecodeUrlEncodedChars()
Decode all percent encoded characters which are allowed to be represented literally
protected
static decodeUrlEncodedChars(string $input[, string $allowed = '' ]) : mixed
Will not decode any characters which are not listed in the 'allowed' list
Parameters
- $input : string
- $allowed : string = ''
-
Pattern of allowed characters
isValidDnsHostname()
Check if an address is a valid DNS hostname
protected
static isValidDnsHostname(string $host) : bool
Parameters
- $host : string
Return values
boolisValidIpAddress()
Check if a host name is a valid IP address, depending on allowed IP address types
protected
static isValidIpAddress(string $host, int $allowed) : bool
Parameters
- $host : string
- $allowed : int
-
allowed address types
Return values
boolisValidRegName()
Check if an address is a valid registered name (as defined by RFC-3986) address
protected
static isValidRegName(string $host) : bool
Parameters
- $host : string
Return values
boolnormalizeFragment()
Normalize the fragment part
protected
static normalizeFragment(string $fragment) : string
Currently this is exactly the same as normalizeQuery().
Parameters
- $fragment : string
Return values
stringnormalizeHost()
Normalize the host part
protected
static normalizeHost(string $host) : string
By default this converts host names to lower case
Parameters
- $host : string
Return values
stringnormalizePath()
Normalize the path
protected
static normalizePath(string $path) : string
This involves removing redundant dot segments, decoding any over-encoded characters and encoding everything that needs to be encoded and is not
Parameters
- $path : string
Return values
stringnormalizePort()
Normalize the port
protected
static normalizePort(int $port[, string $scheme = null ]) : int|null
If the class defines a default port for the current scheme, and the current port is default, it will be unset.
Parameters
- $port : int
- $scheme : string = null
Return values
int|nullnormalizeQuery()
Normalize the query part
protected
static normalizeQuery(string $query) : string
This involves decoding everything that doesn't need to be encoded, and encoding everything else
Parameters
- $query : string
Return values
stringnormalizeScheme()
Normalize the scheme
protected
static normalizeScheme(string $scheme) : string
Usually this means simply converting the scheme to lower case
Parameters
- $scheme : string
Return values
stringreset()
Reset URI parts
protected
reset() : mixed