# Usage ## 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 referenced. > ### Supported schemes > > At the time of writing, zend-uri provides built-in support for the following > schemes only: 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 `UriFactory` using `Zend\Uri\UriFactory::registerScheme($scheme, $class)`. 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 The following registers the `ftp` scheme with a custom URI class: ```php use MyNamespace\MyClass; use Zend\Uri\UriFactory UriFactory::registerScheme('ftp', MyClass::class); $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 a string to `Zend\Uri\UriFactory::factory()`, and then manipulate the instance returned. ### Manipulating an Existing URI with Zend\\Uri\\UriFactory::factory() ```php use Zend\Uri\UriFactory; // To manipulate an existing URI, pass it in. $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'. ```php $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 (not the separator). ### 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'. ```php $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'. ```php $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'. ```php $uri = Zend\Uri\UriFactory::factory('http://example.com:8080'); $scheme = $uri->getPort(); // "8080" ``` Concrete URI instances can define default ports that can be returned when no port is given in the URI: ```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 a 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'. ```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 an 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'. ```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. The query string often contains key=value pairs and therefore can be split into an associative array. This array can be retrieved using `getQueryAsArray()`: ```php $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token'); $scheme = $uri->getQueryAsArray(); // [ // 'a' => 'b', // 'c' => 'd', // ] ``` ### Getting the fragment-part of the URI The fragment-part of the URI is an 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'. ```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 The `toString()` method returns the string representation of the entire *URI*. ```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 `Zend\Uri\UriInterface` defines also the 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. ```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.