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