[Docs] Added base documentation

Author: froschdesign

doc/book/zend.uri.md

@@ -0,0 +1,270 @@
+# Zend\\Uri
+
+## Overview
+
+`Zend\Uri` is a component that aids in manipulating and validating [Uniform 
+Resource Identifiers](http://www.w3.org/Addressing/)
+([URIs](http://www.ietf.org/rfc/rfc3986.txt)). `Zend\Uri` exists primarily
+to service other components, such as `Zend\Http`, but is also useful as a
+standalone utility.
+
+*URI*s 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()
+
+```php
+// 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()`. 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.
+
+> ### Note
+At the time of writing, `Zend\Uri` provides built-in support for the following
+schemes: HTTP, HTTPS, MAILTO and FILE
+
+### 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
+
+```php
+// Create a new 'ftp' URI based on a custom class
+use Zend\Uri\UriFactory
+
+UriFactory::registerScheme('ftp', 'MyNamespace\MyClass');
+
+$ftpUri = UriFactory::factory(
+    'ftp://[email protected]/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()
+
+```php
+// 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://[email protected]/my/path?query#token` is
+'http'.
+
+#### Getting the Scheme from a Zend\\Uri\\UriInterface Object
+
+```php
+$uri = Zend\Uri\UriFactory::factory('mailto:[email protected]');
+
+$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://[email protected]/my/path?query#token` is 'johndoe'.
+
+#### Getting the Username from a Zend\Uri\UriInterface Object
+
+```php
+$uri = Zend\Uri\UriFactory::factory('mailto:[email protected]');
+
+$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://[email protected]/my/path?query#token` is 'example.com'.
+
+#### Getting the host from a Zend\\Uri\\UriInterface Object
+
+```php
+$uri = Zend\Uri\UriFactory::factory('mailto:[email protected]');
+
+$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://[email protected]: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
+
+```php
+$uri = Zend\Uri\UriFactory::factory('http://example.com:8080');
+
+$scheme = $uri->getPort();  // "8080"
+```
+
+#### Getting a default port from a Zend\\Uri\\UriInterface Object
+
+```php
+$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://[email protected]:80/my/path?query#token` is '/my/path'.
+
+#### Getting the path from a Zend\\Uri\\UriInterface Object
+
+```php
+$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://[email protected]:80/my/path?query#token` is 'quer'.
+
+#### Getting the query from a Zend\\Uri\\UriInterface Object
+
+```php
+$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
+
+```php
+$uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
+
+$scheme = $uri->getQueryAsArray();
+// [
+//  '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://[email protected]:80/my/path?query#token` is 'token'.
+
+#### Getting the fragment from a Zend\\Uri\\UriInterface Object
+
+```php
+$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
+
+```php
+$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
+
+```php
+$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.