interface/modules/zend_modules/library/Zend/Uri/UriInterface.php

   1 <?php
   2 /**
   3  * Zend Framework (http://framework.zend.com/)
   4  *
   5  * @link      http://github.com/zendframework/zf2 for the canonical source repository
   6  * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
   7  * @license   http://framework.zend.com/license/new-bsd New BSD License
   8  */
   9
  10 namespace Zend\Uri;
  11
  12 /**
  13  * Interface defining a URI
  14  */
  15 interface UriInterface
  16 {
  17     /**
  18      * Create a new URI object
  19      *
  20      * @param  Uri|string|null $uri
  21      * @throws Exception\InvalidArgumentException
  22      */
  23     public function __construct($uri = null);
  24
  25     /**
  26      * Check if the URI is valid
  27      *
  28      * Note that a relative URI may still be valid
  29      *
  30      * @return bool
  31      */
  32     public function isValid();
  33
  34     /**
  35      * Check if the URI is a valid relative URI
  36      *
  37      * @return bool
  38      */
  39     public function isValidRelative();
  40
  41     /**
  42      * Check if the URI is an absolute or relative URI
  43      *
  44      * @return bool
  45      */
  46     public function isAbsolute();
  47
  48     /**
  49      * Parse a URI string
  50      *
  51      * @param  string $uri
  52      * @return Uri
  53      */
  54     public function parse($uri);
  55
  56     /**
  57      * Compose the URI into a string
  58      *
  59      * @return string
  60      * @throws Exception\InvalidUriException
  61      */
  62     public function toString();
  63
  64     /**
  65      * Normalize the URI
  66      *
  67      * Normalizing a URI includes removing any redundant parent directory or
  68      * current directory references from the path (e.g. foo/bar/../baz becomes
  69      * foo/baz), normalizing the scheme case, decoding any over-encoded
  70      * characters etc.
  71      *
  72      * Eventually, two normalized URLs pointing to the same resource should be
  73      * equal even if they were originally represented by two different strings
  74      *
  75      * @return Uri
  76      */
  77     public function normalize();
  78
  79     /**
  80      * Convert the link to a relative link by substracting a base URI
  81      *
  82      *  This is the opposite of resolving a relative link - i.e. creating a
  83      *  relative reference link from an original URI and a base URI.
  84      *
  85      *  If the two URIs do not intersect (e.g. the original URI is not in any
  86      *  way related to the base URI) the URI will not be modified.
  87      *
  88      * @param  Uri|string $baseUri
  89      * @return Uri
  90      */
  91     public function makeRelative($baseUri);
  92
  93     /**
  94      * Get the scheme part of the URI
  95      *
  96      * @return string|null
  97      */
  98     public function getScheme();
  99
 100     /**
 101      * Get the User-info (usually user:password) part
 102      *
 103      * @return string|null
 104      */
 105     public function getUserInfo();
 106
 107     /**
 108      * Get the URI host
 109      *
 110      * @return string|null
 111      */
 112     public function getHost();
 113
 114     /**
 115      * Get the URI port
 116      *
 117      * @return int|null
 118      */
 119     public function getPort();
 120
 121     /**
 122      * Get the URI path
 123      *
 124      * @return string|null
 125      */
 126     public function getPath();
 127
 128     /**
 129      * Get the URI query
 130      *
 131      * @return string|null
 132      */
 133     public function getQuery();
 134
 135     /**
 136      * Return the query string as an associative array of key => value pairs
 137      *
 138      * This is an extension to RFC-3986 but is quite useful when working with
 139      * most common URI types
 140      *
 141      * @return array
 142      */
 143     public function getQueryAsArray();
 144
 145     /**
 146      * Get the URI fragment
 147      *
 148      * @return string|null
 149      */
 150     public function getFragment();
 151
 152     /**
 153      * Set the URI scheme
 154      *
 155      * If the scheme is not valid according to the generic scheme syntax or
 156      * is not acceptable by the specific URI class (e.g. 'http' or 'https' are
 157      * the only acceptable schemes for the Zend\Uri\Http class) an exception
 158      * will be thrown.
 159      *
 160      * You can check if a scheme is valid before setting it using the
 161      * validateScheme() method.
 162      *
 163      * @param  string $scheme
 164      * @throws Exception\InvalidUriPartException
 165      * @return Uri
 166      */
 167     public function setScheme($scheme);
 168
 169     /**
 170      * Set the URI User-info part (usually user:password)
 171      *
 172      * @param  string $userInfo
 173      * @return Uri
 174      * @throws Exception\InvalidUriPartException If the schema definition
 175      * does not have this part
 176      */
 177     public function setUserInfo($userInfo);
 178
 179     /**
 180      * Set the URI host
 181      *
 182      * Note that the generic syntax for URIs allows using host names which
 183      * are not necessarily IPv4 addresses or valid DNS host names. For example,
 184      * IPv6 addresses are allowed as well, and also an abstract "registered name"
 185      * which may be any name composed of a valid set of characters, including,
 186      * for example, tilda (~) and underscore (_) which are not allowed in DNS
 187      * names.
 188      *
 189      * Subclasses of Uri may impose more strict validation of host names - for
 190      * example the HTTP RFC clearly states that only IPv4 and valid DNS names
 191      * are allowed in HTTP URIs.
 192      *
 193      * @param  string $host
 194      * @throws Exception\InvalidUriPartException
 195      * @return Uri
 196      */
 197     public function setHost($host);
 198
 199     /**
 200      * Set the port part of the URI
 201      *
 202      * @param  int $port
 203      * @return Uri
 204      */
 205     public function setPort($port);
 206
 207     /**
 208      * Set the path
 209      *
 210      * @param  string $path
 211      * @return Uri
 212      */
 213     public function setPath($path);
 214
 215     /**
 216      * Set the query string
 217      *
 218      * If an array is provided, will encode this array of parameters into a
 219      * query string. Array values will be represented in the query string using
 220      * PHP's common square bracket notation.
 221      *
 222      * @param  string|array $query
 223      * @return Uri
 224      */
 225     public function setQuery($query);
 226
 227     /**
 228      * Set the URI fragment part
 229      *
 230      * @param  string $fragment
 231      * @return Uri
 232      * @throws Exception\InvalidUriPartException If the schema definition
 233      * does not have this part
 234      */
 235     public function setFragment($fragment);
 236
 237     /**
 238      * Magic method to convert the URI to a string
 239      *
 240      * @return string
 241      */
 242     public function __toString();
 243 }