Zend\Uri¶
Overview¶
Zend\Uri
is a component that aids in manipulating and validating
Uniform Resource Identifiers (URIs) [1]. Zend\Uri
exists primarily to service
other components, such as Zend\Http\
, but is also useful as a standalone
utility.
URIs always begin with a scheme, followed by a colon. The construction of
the many different schemes varies significantly. The Zend\Uri
component
provides the Zend\Uri\UriFactory
that returns a class implementing the
Zend\Uri\UriInterface
which specializes in the scheme if such a class is
registered with the Factory.
Creating a New URI¶
Zend\Uri\UriFactory
will build a new URI from scratch if only a scheme is
passed to Zend\Uri\UriFactory::factory()
.
Creating a New URI with ZendUriUriFactory::factory()
1 2 3 4 5 | // To create a new URI from scratch, pass only the scheme
// followed by a colon.
$uri = Zend\Uri\UriFactory::factory('http:');
// $uri instanceof Zend\Uri\UriInterface
|
To create a new URI from scratch, pass only the scheme followed by a colon to
Zend\Uri\UriFactory::factory()
[2]. If an unsupported scheme is passed and
no scheme-specific class is specified, a
Zend\Uri\Exception\InvalidArgumentException
will be thrown.
If the scheme or URI passed is supported, Zend\Uri\UriFactory::factory()
will return a class implementing Zend\Uri\UriInterface
that specializes
in the scheme to be created.
Creating a New Custom-Class URI¶
You can specify a custom class to be used when using the Zend\Uri\UriFactory
by registering your class with the Factory using
\Zend\Uri\UriFactory::registerScheme()
which takes the scheme as first
parameter. This enables you to create your own URI-class and instantiate new
URI objects based on your own custom classes.
The 2nd parameter passed to Zend\Uri\UriFactory::registerScheme()
must be a
string with the name of a class implementing Zend\Uri\UriInterface
. The
class must either be already loaded, or be loadable by the autoloader.
Creating a URI using a custom class
1 2 3 4 5 6 7 8 9 10 11 | // Create a new 'ftp' URI based on a custom class
use Zend\Uri\UriFactory
UriFactory::registerScheme('ftp', 'MyNamespace\MyClass');
$ftpUri = UriFactory::factory(
'ftp://user@ftp.example.com/path/file'
);
// $ftpUri is an instance of MyLibrary\MyClass, which implements
// Zend\Uri\UriInterface
|
Manipulating an Existing URI¶
To manipulate an existing URI, pass the entire URI as string to
Zend\Uri\UriFactory::factory()
.
Manipulating an Existing URI with Zend\Uri\UriFactory::factory()
1 2 3 4 | // To manipulate an existing URI, pass it in.
$uri = Zend\Uri\UriFactory::factory('http://www.zend.com');
// $uri instanceof Zend\Uri\UriInterface
|
The URI will be parsed and validated. If it is found to be invalid, a
Zend\Uri\Exception\InvalidArgumentException
will be thrown immediately.
Otherwise, Zend\Uri\UriFactory::factory()
will return a class implementing
Zend\Uri\UriInterface
that specializes in the scheme to be manipulated.
Common Instance Methods¶
The Zend\Uri\UriInterface
defines several instance methods that are useful
for working with any kind of URI.
Getting the Scheme of the URI¶
The scheme of the URI is the part of the URI that precedes the colon. For
example, the scheme of http://johndoe@example.com/my/path?query#token
is ‘http’.
Getting the Scheme from a Zend\Uri\UriInterface Object
1 2 3 | $uri = Zend\Uri\UriFactory::factory('mailto:john.doe@example.com');
$scheme = $uri->getScheme(); // "mailto"
|
The getScheme()
instance method returns only the scheme part of the URI
object.
Getting the Userinfo of the URI¶
The userinfo of the URI is the optional part of the URI that follows the
colon and comes before the host-part. For example, the userinfo of
http://johndoe@example.com/my/path?query#token
is ‘johndoe’.
Getting the Username from a Zend\Uri\UriInterface Object
1 2 3 | $uri = Zend\Uri\UriFactory::factory('mailto:john.doe@example.com');
$scheme = $uri->getUserinfo(); // "john.doe"
|
The getUserinfo()
method returns only the userinfo part of the URI
object.
Getting the host of the URI¶
The host of the URI is the optional part of the URI that follows the
user-part and comes before the path-part. For example, the host of
http://johndoe@example.com/my/path?query#token
is ‘example.com’.
Getting the host from a Zend\Uri\UriInterface Object
1 2 3 | $uri = Zend\Uri\UriFactory::factory('mailto:john.doe@example.com');
$scheme = $uri->getHost(); // "example.com"
|
The getHost()
method returns only the host part of the URI
object.
Getting the port of the URI¶
The port of the URI is the optional part of the URI that follows the
host-part and comes before the path-part. For example, the host of
http://johndoe@example.com:80/my/path?query#token
is ‘80’. The URI-class
can define default-ports that can be returned when no port is given in the
URI
.
Getting the port from a Zend\Uri\UriInterface Object
1 2 3 | $uri = Zend\Uri\UriFactory::factory('http://example.com:8080');
$scheme = $uri->getPort(); // "8080"
|
Getting a default port from a Zend\Uri\UriInterface Object
1 2 3 | $uri = Zend\Uri\UriFactory::factory('http://example.com');
$scheme = $uri->getPort(); // "80"
|
The getHost()
method returns only the port part of the URI
object.
Getting the path of the URI¶
The path of the URI is the mandatory part of the URI that follows the
port and comes before the query-part. For example, the path of
http://johndoe@example.com:80/my/path?query#token
is ‘/my/path’.
Getting the path from a Zend\Uri\UriInterface Object
1 2 3 | $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
$scheme = $uri->getPath(); // "/my/path"
|
The getPath()
method returns only the path of the URI object.
Getting the query-part of the URI¶
The query-part of the URI is the optional part of the URI that follows the
path and comes before the fragment. For example, the query of
http://johndoe@example.com:80/my/path?query#token
is ‘query’.
Getting the query from a Zend\Uri\UriInterface Object
1 2 3 | $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
$scheme = $uri->getQuery(); // "a=b&c=d"
|
The getQuery()
method returns only the query-part of the URI object.
Getting the query as array from a Zend\Uri\UriInterface Object
1 2 3 4 5 6 7 | $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
$scheme = $uri->getQueryAsArray();
// array(
// 'a' => 'b',
// 'c' => 'd',
// )
|
The query-part often contains key=value pairs and therefore can be split into
an associative array. This array can be retrieved using getQueryAsArray()
Getting the fragment-part of the URI¶
The fragment-part of the URI is the optional part of the URI that follows the
query. For example, the fragment of
http://johndoe@example.com:80/my/path?query#token
is ‘token’.
Getting the fragment from a Zend\Uri\UriInterface Object
1 2 3 | $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
$scheme = $uri->getFragment(); // "token"
|
The getFragment()
method returns only the fragment-part of the URI object.
Getting the Entire URI¶
Getting the Entire URI from a Zend\Uri\UriInterface Object
1 2 3 4 5 6 | $uri = Zend\Uri\UriFactory::factory('http://www.zend.com');
echo $uri->toString(); // "http://www.zend.com"
// Alternate method:
echo (string) $uri; // "http://www.zend.com"
|
The toString()
method returns the string representation of the entire URI.
The Zend\Uri\UriInterface
defines also a magic __toString()
method that
returns the string representation of the URI when the Object is cast to a
string.
Validating the URI¶
When using Zend\Uri\UriFactory::factory()
the given URI will always be
validated and a Zend\Uri\Exception\InvalidArgumentException
will be thrown
when the URI is invalid. However, after the Zend\Uri\UriInterface
is
instantiated for a new URI or an existing valid one, it is possible that the
URI can later become invalid after it is manipulated.
Validating a ZendUri* Object
1 2 3 | $uri = Zend\Uri\UriFactory::factory('http://www.zend.com');
$isValid = $uri->isValid(); // TRUE
|
The isValid()
instance method provides a means to check that the URI
object is still valid.
[1] | See http://www.ietf.org/rfc/rfc3986.txt for more information on URIs |
[2] | At the time of writing, Zend\Uri provides built-in support for
the following schemes: HTTP, HTTPS, MAILTO and FILE |