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()

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

// 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()

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

$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

$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

$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

$uri = Zend\Uri\UriFactory::factory('http://example.com:8080');

$scheme = $uri->getPort();  // "8080"

Getting a default port from a Zend\Uri\UriInterface Object

$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

$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

$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

$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

$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

$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

$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