vendor/zendframework/zend-uri/src/UriInterface.php

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