HumHub Documentation (unofficial)

Mailto extends Uri
in package

"Mailto" URI handler

The 'mailto:...' scheme is loosely defined in RFC-1738

Table of Contents

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
$emailValidator  : ValidatorInterface
Validator for use when validating email address
$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<int, string>
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
getEmail()  : string
Get the email address
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
getValidator()  : ValidatorInterface
Retrieve validator for use with validating email address
isAbsolute()  : bool
Check if the URI is an absolute or relative URI
isValid()  : bool
Check if the URI is a valid Mailto URI
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.
setEmail()  : Mailto
Set the email address
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)
setValidator()  : Mailto
Set validator to use when validating email address
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

$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<int, string> $validSchemes = ['mailto']

Methods

__construct()

Create a new URI object

public __construct([Uri|string|null $uri = null ]) : mixed
Parameters
$uri : Uri|string|null = null
Tags
throws
InvalidArgumentException

__toString()

Magic method to convert the URI to a string

public __toString() : string
Return values
string

encodePath()

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
throws
InvalidArgumentException
Return values
string

encodeQueryFragment()

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
throws
InvalidArgumentException
Return values
string

encodeUserInfo()

URL-encode the user info part of a URI

public static encodeUserInfo(string $userInfo) : string
Parameters
$userInfo : string
Tags
throws
InvalidArgumentException
Return values
string

getEmail()

Get the email address

public getEmail() : string

This is infact equivalent to getPath() - but provides a more clear interface

Return values
string

getEscaper()

Retrieve Escaper instance

public static getEscaper() : Escaper

Lazy-loads one if none provided

Return values
Escaper

getFragment()

Get the URI fragment

public getFragment() : string|null
Return values
string|null

getHost()

Get the URI host

public getHost() : string|null
Return values
string|null

getPath()

Get the URI path

public getPath() : string|null
Return values
string|null

getPort()

Get the URI port

public getPort() : int|null
Return values
int|null

getQuery()

Get the URI query

public getQuery() : string|null
Return values
string|null

getQueryAsArray()

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|null

getUserInfo()

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

public getUserInfo() : string|null
Return values
string|null

getValidator()

Retrieve validator for use with validating email address

public getValidator() : ValidatorInterface

If none is currently set, an EmailValidator instance with default options will be used.

Return values
ValidatorInterface

isAbsolute()

Check if the URI is an absolute or relative URI

public isAbsolute() : bool
Return values
bool

isValid()

Check if the URI is a valid Mailto URI

public isValid() : bool

This applies additional specific validation rules beyond the ones required by the generic URI syntax

Tags
see
Uri::isValid()
Return values
bool

isValidRelative()

Check if the URI is a valid relative URI

public isValidRelative() : bool
Return values
bool

makeRelative()

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
Uri

merge()

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
$baseUri : Uri|string
$relativeUri : Uri|string
Return values
Uri

normalize()

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
Uri

parse()

Parse a URI string

public parse(string $uri) : Uri
Parameters
$uri : string
Return values
Uri

parseScheme()

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
throws
InvalidArgumentException
Return values
string|null

removePathDotSegments()

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
todo

consider optimizing

Return values
string

resolve()

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
throws
InvalidArgumentException
Return values
Uri

setEmail()

Set the email address

public setEmail(string $email) : Mailto

This is in fact equivalent to setPath() - but provides a more clear interface

Parameters
$email : string
Return values
Mailto

setEscaper()

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
throws
InvalidUriPartException

If the schema definition does not have this part.

Return values
Uri

setHost()

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
throws
InvalidUriPartException
Return values
Uri

setPath()

Set the path

public setPath(string|null $path) : Uri
Parameters
$path : string|null
Return values
Uri

setPort()

Set the port part of the URI

public setPort(int|null $port) : Uri
Parameters
$port : int|null
Return values
Uri

setQuery()

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
Uri

setScheme()

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
throws
InvalidUriPartException
Return values
Uri

setUserInfo()

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

public setUserInfo(string|null $userInfo) : Uri
Parameters
$userInfo : string|null
Tags
throws
InvalidUriPartException

If the schema definition does not have this part.

Return values
Uri

toString()

Compose the URI into a string

public toString() : string
Tags
throws
InvalidUriException
Return values
string

validateHost()

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
bool

validatePath()

Validate the path

public static validatePath(string $path) : bool
Parameters
$path : string
Return values
bool

validatePort()

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
bool

validateQueryFragment()

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
bool

validateScheme()

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
bool

validateUserInfo()

Check that the userInfo part of a URI is valid

public static validateUserInfo(string $userInfo) : bool
Parameters
$userInfo : string
Return values
bool

decodeUrlEncodedChars()

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
bool

isValidIpAddress()

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
bool

isValidRegName()

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
bool

normalizeFragment()

Normalize the fragment part

protected static normalizeFragment(string $fragment) : string

Currently this is exactly the same as normalizeQuery().

Parameters
$fragment : string
Return values
string

normalizeHost()

Normalize the host part

protected static normalizeHost(string $host) : string

By default this converts host names to lower case

Parameters
$host : string
Return values
string

normalizePath()

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
string

normalizePort()

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|null

normalizeQuery()

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
string

normalizeScheme()

Normalize the scheme

protected static normalizeScheme(string $scheme) : string

Usually this means simply converting the scheme to lower case

Parameters
$scheme : string
Return values
string

reset()

Reset URI parts

protected reset() : mixed

        
On this page

Search results