58.1. Zend_Uri

58.1.1. Overview

Zend_Uri is a component that aids in manipulating and validating Uniform Resource Identifiers (URIs). Zend_Uri exists primarily to service other components such as Zend_Http_Client 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 class provides a factory that returns a subclass of itself which specializes in each scheme. The subclass will be named Zend_Uri_<scheme>, where <scheme> is the scheme lowercased with the first letter capitalized. An exception to this rule is HTTPS, which is also handled by Zend_Uri_Http.

58.1.2. Creating a New URI

Zend_Uri will build a new URI from scratch if only a scheme is passed to Zend_Uri::factory().

Example 58.1. Creating a New URI with Zend_Uri::factory()

// To create a new URI from scratch, pass only the scheme.
$uri = Zend_Uri::factory('http');

// $uri instanceof Zend_Uri_Http

To create a new URI from scratch, pass only the scheme to Zend_Uri::factory()[ ] . If an unsupported scheme is passed, a Zend_Uri_Exception will be thrown.

If the scheme or URI passed is supported, Zend_Uri::factory() will return a subclass of itself that specializes in the scheme to be created.

58.1.3. Manipulating an Existing URI

To manipulate an existing URI, pass the entire URI to Zend_Uri::factory().

Example 58.2. Manipulating an Existing URI with Zend_Uri::factory()

// To manipulate an existing URI, pass it in.
$uri = Zend_Uri::factory('http://www.zend.com');

// $uri instanceof Zend_Uri_Http

The URI will be parsed and validated. If it is found to be invalid, a Zend_Uri_Exception will be thrown immediately. Otherwise, Zend_Uri::factory() will return a subclass of itself that specializes in the scheme to be manipulated.

58.1.4. URI Validation

The Zend_Uri::check() function can be used if only validation of an existing URI is needed.

Example 58.3. URI Validation with Zend_Uri::check()

// Validate whether a given URI is well formed
$valid = Zend_Uri::check('http://uri.in.question');

// $valid is TRUE for a valid URI, or FALSE otherwise.

Zend_Uri::check() returns a boolean, which is more convenient than using Zend_Uri::factory() and catching the exception.

58.1.4.1. Allowing "Unwise" characters in URIs

By default, Zend_Uri will not accept the following characters, defined by the RFC as "unwise" and invalid: "{", "}", "|", "\", "^", "`". However, many implementations do accept these characters as valid.

Zend_Uri can be set to accept these "unwise" characters by setting the 'allow_unwise' option to boolean TRUE using the Zend_Uri::setConfig() method:

Example 58.4. Allowing special characters in URIs

// Contains '|' symbol
// Normally, this would return false:
$valid = Zend_Uri::check('http://example.com/?q=this|that');

// However, you can allow "unwise" characters
Zend_Uri::setConfig(array('allow_unwise' => true));
// will return 'true'
$valid = Zend_Uri::check('http://example.com/?q=this|that');

// Reset the 'allow_unwise' value to the default FALSE
Zend_Uri::setConfig(array('allow_unwise' => false));

[Note] Note

Zend_Uri::setConfig() sets configuration options globally. It is recommended to reset the 'allow_unwise' option to 'false' like in the example above, unless you are certain you want to always allow unwise characters globally.

58.1.5. Common Instance Methods

Every instance of a Zend_Uri subclass (e.g. Zend_Uri_Http) has several instance methods that are useful for working with any kind of URI.

58.1.5.1. 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://www.zend.com is http.

Example 58.5. Getting the Scheme from a Zend_Uri_* Object

$uri = Zend_Uri::factory('http://www.zend.com');

$scheme = $uri->getScheme();  // "http"

The getScheme() instance method returns only the scheme part of the URI object.

58.1.5.2. Getting the Entire URI

Example 58.6. Getting the Entire URI from a Zend_Uri_* Object

$uri = Zend_Uri::factory('http://www.zend.com');

echo $uri->getUri();  // "http://www.zend.com"

The getUri() method returns the string representation of the entire URI.

58.1.5.3. Validating the URI

Zend_Uri::factory() will always validate any URI passed to it and will not instantiate a new Zend_Uri subclass if the given URI is found to be invalid. However, after the Zend_Uri subclass is instantiated for a new URI or a valid existing one, it is possible that the URI can then later become invalid after it is manipulated.

Example 58.7. Validating a Zend_Uri_* Object

$uri = Zend_Uri::factory('http://www.zend.com');

$isValid = $uri->valid();  // TRUE

The valid() instance method provides a means to check that the URI object is still valid.

blog comments powered by Disqus