vendor/zendframework/zend-uri/doc/book/usage.md

   1 # Usage
   2
   3 ## Creating a New URI
   4
   5 `Zend\Uri\UriFactory` will build a new URI from scratch if only a scheme is
   6 passed to `Zend\Uri\UriFactory::factory()`.
   7
   8 ### Creating a New URI with ZendUriUriFactory::factory()
   9
  10 ```php
  11 // To create a new URI from scratch, pass only the scheme
  12 // followed by a colon.
  13 $uri = Zend\Uri\UriFactory::factory('http:');
  14
  15 // $uri instanceof Zend\Uri\UriInterface
  16 ```
  17
  18 To create a new URI from scratch, pass only the scheme followed by a colon to
  19 `Zend\Uri\UriFactory::factory()`. If an unsupported scheme is passed and no
  20 scheme-specific class is specified, a
  21 `Zend\Uri\Exception\InvalidArgumentException` will be thrown.
  22
  23 If the scheme or URI passed is supported, `Zend\Uri\UriFactory::factory()` will
  24 return a class implementing `Zend\Uri\UriInterface` that specializes in the
  25 scheme referenced.
  26
  27 > ### Supported schemes
  28 >
  29 > At the time of writing, zend-uri provides built-in support for the following
  30 > schemes only: HTTP, HTTPS, MAILTO and FILE.
  31
  32 ### Creating a New Custom-Class URI
  33
  34 You can specify a custom class to be used when using the `Zend\Uri\UriFactory`
  35 by registering your class with the `UriFactory` using
  36 `Zend\Uri\UriFactory::registerScheme($scheme, $class)`.  This enables you to
  37 create your own URI class and instantiate new URI objects based on your own
  38 custom classes.
  39
  40 The 2nd parameter passed to `Zend\Uri\UriFactory::registerScheme()` must be a
  41 string with the name of a class implementing `Zend\Uri\UriInterface`. The class
  42 must either be already loaded, or be loadable by the autoloader.
  43
  44 #### Creating a URI using a custom class
  45
  46 The following registers the `ftp` scheme with a custom URI class:
  47
  48 ```php
  49 use MyNamespace\MyClass;
  50 use Zend\Uri\UriFactory
  51
  52 UriFactory::registerScheme('ftp', MyClass::class);
  53
  54 $ftpUri = UriFactory::factory(
  55     'ftp://user@ftp.example.com/path/file'
  56 );
  57
  58 // $ftpUri is an instance of MyLibrary\MyClass, which implements
  59 // Zend\Uri\UriInterface
  60 ```
  61
  62 ## Manipulating an Existing URI
  63
  64 To manipulate an existing URI, pass the entire URI as a string to
  65 `Zend\Uri\UriFactory::factory()`, and then manipulate the instance returned.
  66
  67 ### Manipulating an Existing URI with Zend\\Uri\\UriFactory::factory()
  68
  69 ```php
  70 use Zend\Uri\UriFactory;
  71
  72 // To manipulate an existing URI, pass it in.
  73 $uri = UriFactory::factory('http://www.zend.com');
  74
  75 // $uri instanceof Zend\Uri\UriInterface
  76 ```
  77
  78 The URI will be parsed and validated. If it is found to be invalid, a
  79 `Zend\Uri\Exception\InvalidArgumentException` will be thrown immediately.
  80 Otherwise, `Zend\Uri\UriFactory::factory()` will return a class implementing
  81 `Zend\Uri\UriInterface` that specializes in the scheme to be manipulated.
  82
  83 ## Common Instance Methods
  84
  85 The `Zend\Uri\UriInterface` defines several instance methods that are useful for
  86 working with any kind of URI.
  87
  88 ### Getting the Scheme of the URI
  89
  90 The scheme of the URI is the part of the URI that precedes the colon. For
  91 example, the scheme of `http://johndoe@example.com/my/path?query#token` is
  92 'http'.
  93
  94 ```php
  95 $uri = Zend\Uri\UriFactory::factory('mailto:john.doe@example.com');
  96
  97 $scheme = $uri->getScheme();  // "mailto"
  98 ```
  99
 100 The `getScheme()` instance method returns only the scheme part of the URI
 101 object (not the separator).
 102
 103 ### Getting the Userinfo of the URI
 104
 105 The userinfo of the URI is the optional part of the URI that follows the
 106 colon and comes before the host-part. For example, the userinfo of
 107 `http://johndoe@example.com/my/path?query#token` is 'johndoe'.
 108
 109 ```php
 110 $uri = Zend\Uri\UriFactory::factory('mailto:john.doe@example.com');
 111
 112 $scheme = $uri->getUserinfo();  // "john.doe"
 113 ```
 114
 115 The `getUserinfo()` method returns only the userinfo part of the URI object.
 116
 117 ### Getting the host of the URI
 118
 119 The host of the URI is the optional part of the URI that follows the
 120 user-part and comes before the path-part. For example, the host of
 121 `http://johndoe@example.com/my/path?query#token` is 'example.com'.
 122
 123 ```php
 124 $uri = Zend\Uri\UriFactory::factory('mailto:john.doe@example.com');
 125
 126 $scheme = $uri->getHost();  // "example.com"
 127 ```
 128
 129 The `getHost()` method returns only the host part of the URI object.
 130
 131 ### Getting the port of the URI
 132
 133 The port of the URI is the optional part of the URI that follows the host-part
 134 and comes before the path-part. For example, the host of
 135 `http://johndoe@example.com:80/my/path?query#token` is '80'.
 136
 137 ```php
 138 $uri = Zend\Uri\UriFactory::factory('http://example.com:8080');
 139
 140 $scheme = $uri->getPort();  // "8080"
 141 ```
 142
 143 Concrete URI instances can define default ports that can be returned when no
 144 port is given in the URI:
 145
 146 ```php
 147 $uri = Zend\Uri\UriFactory::factory('http://example.com');
 148
 149 $scheme = $uri->getPort();  // "80"
 150 ```
 151
 152 The `getHost()` method returns only the port part of the URI object.
 153
 154 ### Getting the path of the URI
 155
 156 The path of the URI is a mandatory part of the URI that follows the port
 157 and comes before the query-part. For example, the path of
 158 `http://johndoe@example.com:80/my/path?query#token` is '/my/path'.
 159
 160 ```php
 161 $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
 162
 163 $scheme = $uri->getPath();  // "/my/path"
 164 ```
 165
 166 The `getPath()` method returns only the path of the URI object.
 167
 168 ### Getting the query-part of the URI
 169
 170 The query-part of the URI is an optional part of the URI that follows the
 171 path and comes before the fragment. For example, the query of
 172 `http://johndoe@example.com:80/my/path?query#token` is 'query'.
 173
 174 ```php
 175 $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
 176
 177 $scheme = $uri->getQuery();  // "a=b&c=d"
 178 ```
 179
 180 The `getQuery()` method returns only the query-part of the URI object.
 181
 182 The query string often contains key=value pairs and therefore can be split into an
 183 associative array. This array can be retrieved using `getQueryAsArray()`:
 184
 185 ```php
 186 $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
 187
 188 $scheme = $uri->getQueryAsArray();
 189 // [
 190 //  'a' => 'b',
 191 //  'c' => 'd',
 192 // ]
 193 ```
 194
 195 ### Getting the fragment-part of the URI
 196
 197 The fragment-part of the URI is an optional part of the URI that follows
 198 the query. For example, the fragment of
 199 `http://johndoe@example.com:80/my/path?query#token` is 'token'.
 200
 201 ```php
 202 $uri = Zend\Uri\UriFactory::factory('http://example.com:80/my/path?a=b&c=d#token');
 203
 204 $scheme = $uri->getFragment();  // "token"
 205 ```
 206
 207 The `getFragment()` method returns only the fragment-part of the URI object.
 208
 209 ### Getting the Entire URI
 210
 211 The `toString()` method returns the string representation of the entire *URI*.
 212
 213 ```php
 214 $uri = Zend\Uri\UriFactory::factory('http://www.zend.com');
 215
 216 echo $uri->toString();  // "http://www.zend.com"
 217
 218 // Alternate method:
 219 echo (string) $uri;     // "http://www.zend.com"
 220 ```
 221
 222 The `Zend\Uri\UriInterface` defines also the magic `__toString()` method that
 223 returns the string representation of the URI when the object is cast to a
 224 string.
 225
 226 ## Validating the URI
 227
 228 When using `Zend\Uri\UriFactory::factory()`, the given URI will always be
 229 validated and a `Zend\Uri\Exception\InvalidArgumentException` will be thrown
 230 when the URI is invalid. However, after the `Zend\Uri\UriInterface` is
 231 instantiated for a new URI or an existing valid one, it is possible that the URI
 232 can later become invalid after it is manipulated.
 233
 234 ```php
 235 $uri = Zend\Uri\UriFactory::factory('http://www.zend.com');
 236
 237 $isValid = $uri->isValid();  // TRUE
 238 ```
 239
 240 The `isValid()` instance method provides a means to check that the URI object
 241 is still valid.