UriInterface.php 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323
  1. <?php
  2. namespace Psr\Http\Message;
  3. /**
  4. * Value object representing a URI.
  5. *
  6. * This interface is meant to represent URIs according to RFC 3986 and to
  7. * provide methods for most common operations. Additional functionality for
  8. * working with URIs can be provided on top of the interface or externally.
  9. * Its primary use is for HTTP requests, but may also be used in other
  10. * contexts.
  11. *
  12. * Instances of this interface are considered immutable; all methods that
  13. * might change state MUST be implemented such that they retain the internal
  14. * state of the current instance and return an instance that contains the
  15. * changed state.
  16. *
  17. * Typically the Host header will be also be present in the request message.
  18. * For server-side requests, the scheme will typically be discoverable in the
  19. * server parameters.
  20. *
  21. * @link http://tools.ietf.org/html/rfc3986 (the URI specification)
  22. */
  23. interface UriInterface
  24. {
  25. /**
  26. * Retrieve the scheme component of the URI.
  27. *
  28. * If no scheme is present, this method MUST return an empty string.
  29. *
  30. * The value returned MUST be normalized to lowercase, per RFC 3986
  31. * Section 3.1.
  32. *
  33. * The trailing ":" character is not part of the scheme and MUST NOT be
  34. * added.
  35. *
  36. * @see https://tools.ietf.org/html/rfc3986#section-3.1
  37. * @return string The URI scheme.
  38. */
  39. public function getScheme();
  40. /**
  41. * Retrieve the authority component of the URI.
  42. *
  43. * If no authority information is present, this method MUST return an empty
  44. * string.
  45. *
  46. * The authority syntax of the URI is:
  47. *
  48. * <pre>
  49. * [user-info@]host[:port]
  50. * </pre>
  51. *
  52. * If the port component is not set or is the standard port for the current
  53. * scheme, it SHOULD NOT be included.
  54. *
  55. * @see https://tools.ietf.org/html/rfc3986#section-3.2
  56. * @return string The URI authority, in "[user-info@]host[:port]" format.
  57. */
  58. public function getAuthority();
  59. /**
  60. * Retrieve the user information component of the URI.
  61. *
  62. * If no user information is present, this method MUST return an empty
  63. * string.
  64. *
  65. * If a user is present in the URI, this will return that value;
  66. * additionally, if the password is also present, it will be appended to the
  67. * user value, with a colon (":") separating the values.
  68. *
  69. * The trailing "@" character is not part of the user information and MUST
  70. * NOT be added.
  71. *
  72. * @return string The URI user information, in "username[:password]" format.
  73. */
  74. public function getUserInfo();
  75. /**
  76. * Retrieve the host component of the URI.
  77. *
  78. * If no host is present, this method MUST return an empty string.
  79. *
  80. * The value returned MUST be normalized to lowercase, per RFC 3986
  81. * Section 3.2.2.
  82. *
  83. * @see http://tools.ietf.org/html/rfc3986#section-3.2.2
  84. * @return string The URI host.
  85. */
  86. public function getHost();
  87. /**
  88. * Retrieve the port component of the URI.
  89. *
  90. * If a port is present, and it is non-standard for the current scheme,
  91. * this method MUST return it as an integer. If the port is the standard port
  92. * used with the current scheme, this method SHOULD return null.
  93. *
  94. * If no port is present, and no scheme is present, this method MUST return
  95. * a null value.
  96. *
  97. * If no port is present, but a scheme is present, this method MAY return
  98. * the standard port for that scheme, but SHOULD return null.
  99. *
  100. * @return null|int The URI port.
  101. */
  102. public function getPort();
  103. /**
  104. * Retrieve the path component of the URI.
  105. *
  106. * The path can either be empty or absolute (starting with a slash) or
  107. * rootless (not starting with a slash). Implementations MUST support all
  108. * three syntaxes.
  109. *
  110. * Normally, the empty path "" and absolute path "/" are considered equal as
  111. * defined in RFC 7230 Section 2.7.3. But this method MUST NOT automatically
  112. * do this normalization because in contexts with a trimmed base path, e.g.
  113. * the front controller, this difference becomes significant. It's the task
  114. * of the user to handle both "" and "/".
  115. *
  116. * The value returned MUST be percent-encoded, but MUST NOT double-encode
  117. * any characters. To determine what characters to encode, please refer to
  118. * RFC 3986, Sections 2 and 3.3.
  119. *
  120. * As an example, if the value should include a slash ("/") not intended as
  121. * delimiter between path segments, that value MUST be passed in encoded
  122. * form (e.g., "%2F") to the instance.
  123. *
  124. * @see https://tools.ietf.org/html/rfc3986#section-2
  125. * @see https://tools.ietf.org/html/rfc3986#section-3.3
  126. * @return string The URI path.
  127. */
  128. public function getPath();
  129. /**
  130. * Retrieve the query string of the URI.
  131. *
  132. * If no query string is present, this method MUST return an empty string.
  133. *
  134. * The leading "?" character is not part of the query and MUST NOT be
  135. * added.
  136. *
  137. * The value returned MUST be percent-encoded, but MUST NOT double-encode
  138. * any characters. To determine what characters to encode, please refer to
  139. * RFC 3986, Sections 2 and 3.4.
  140. *
  141. * As an example, if a value in a key/value pair of the query string should
  142. * include an ampersand ("&") not intended as a delimiter between values,
  143. * that value MUST be passed in encoded form (e.g., "%26") to the instance.
  144. *
  145. * @see https://tools.ietf.org/html/rfc3986#section-2
  146. * @see https://tools.ietf.org/html/rfc3986#section-3.4
  147. * @return string The URI query string.
  148. */
  149. public function getQuery();
  150. /**
  151. * Retrieve the fragment component of the URI.
  152. *
  153. * If no fragment is present, this method MUST return an empty string.
  154. *
  155. * The leading "#" character is not part of the fragment and MUST NOT be
  156. * added.
  157. *
  158. * The value returned MUST be percent-encoded, but MUST NOT double-encode
  159. * any characters. To determine what characters to encode, please refer to
  160. * RFC 3986, Sections 2 and 3.5.
  161. *
  162. * @see https://tools.ietf.org/html/rfc3986#section-2
  163. * @see https://tools.ietf.org/html/rfc3986#section-3.5
  164. * @return string The URI fragment.
  165. */
  166. public function getFragment();
  167. /**
  168. * Return an instance with the specified scheme.
  169. *
  170. * This method MUST retain the state of the current instance, and return
  171. * an instance that contains the specified scheme.
  172. *
  173. * Implementations MUST support the schemes "http" and "https" case
  174. * insensitively, and MAY accommodate other schemes if required.
  175. *
  176. * An empty scheme is equivalent to removing the scheme.
  177. *
  178. * @param string $scheme The scheme to use with the new instance.
  179. * @return static A new instance with the specified scheme.
  180. * @throws \InvalidArgumentException for invalid or unsupported schemes.
  181. */
  182. public function withScheme($scheme);
  183. /**
  184. * Return an instance with the specified user information.
  185. *
  186. * This method MUST retain the state of the current instance, and return
  187. * an instance that contains the specified user information.
  188. *
  189. * Password is optional, but the user information MUST include the
  190. * user; an empty string for the user is equivalent to removing user
  191. * information.
  192. *
  193. * @param string $user The user name to use for authority.
  194. * @param null|string $password The password associated with $user.
  195. * @return static A new instance with the specified user information.
  196. */
  197. public function withUserInfo($user, $password = null);
  198. /**
  199. * Return an instance with the specified host.
  200. *
  201. * This method MUST retain the state of the current instance, and return
  202. * an instance that contains the specified host.
  203. *
  204. * An empty host value is equivalent to removing the host.
  205. *
  206. * @param string $host The hostname to use with the new instance.
  207. * @return static A new instance with the specified host.
  208. * @throws \InvalidArgumentException for invalid hostnames.
  209. */
  210. public function withHost($host);
  211. /**
  212. * Return an instance with the specified port.
  213. *
  214. * This method MUST retain the state of the current instance, and return
  215. * an instance that contains the specified port.
  216. *
  217. * Implementations MUST raise an exception for ports outside the
  218. * established TCP and UDP port ranges.
  219. *
  220. * A null value provided for the port is equivalent to removing the port
  221. * information.
  222. *
  223. * @param null|int $port The port to use with the new instance; a null value
  224. * removes the port information.
  225. * @return static A new instance with the specified port.
  226. * @throws \InvalidArgumentException for invalid ports.
  227. */
  228. public function withPort($port);
  229. /**
  230. * Return an instance with the specified path.
  231. *
  232. * This method MUST retain the state of the current instance, and return
  233. * an instance that contains the specified path.
  234. *
  235. * The path can either be empty or absolute (starting with a slash) or
  236. * rootless (not starting with a slash). Implementations MUST support all
  237. * three syntaxes.
  238. *
  239. * If the path is intended to be domain-relative rather than path relative then
  240. * it must begin with a slash ("/"). Paths not starting with a slash ("/")
  241. * are assumed to be relative to some base path known to the application or
  242. * consumer.
  243. *
  244. * Users can provide both encoded and decoded path characters.
  245. * Implementations ensure the correct encoding as outlined in getPath().
  246. *
  247. * @param string $path The path to use with the new instance.
  248. * @return static A new instance with the specified path.
  249. * @throws \InvalidArgumentException for invalid paths.
  250. */
  251. public function withPath($path);
  252. /**
  253. * Return an instance with the specified query string.
  254. *
  255. * This method MUST retain the state of the current instance, and return
  256. * an instance that contains the specified query string.
  257. *
  258. * Users can provide both encoded and decoded query characters.
  259. * Implementations ensure the correct encoding as outlined in getQuery().
  260. *
  261. * An empty query string value is equivalent to removing the query string.
  262. *
  263. * @param string $query The query string to use with the new instance.
  264. * @return static A new instance with the specified query string.
  265. * @throws \InvalidArgumentException for invalid query strings.
  266. */
  267. public function withQuery($query);
  268. /**
  269. * Return an instance with the specified URI fragment.
  270. *
  271. * This method MUST retain the state of the current instance, and return
  272. * an instance that contains the specified URI fragment.
  273. *
  274. * Users can provide both encoded and decoded fragment characters.
  275. * Implementations ensure the correct encoding as outlined in getFragment().
  276. *
  277. * An empty fragment value is equivalent to removing the fragment.
  278. *
  279. * @param string $fragment The fragment to use with the new instance.
  280. * @return static A new instance with the specified fragment.
  281. */
  282. public function withFragment($fragment);
  283. /**
  284. * Return the string representation as a URI reference.
  285. *
  286. * Depending on which components of the URI are present, the resulting
  287. * string is either a full URI or relative reference according to RFC 3986,
  288. * Section 4.1. The method concatenates the various components of the URI,
  289. * using the appropriate delimiters:
  290. *
  291. * - If a scheme is present, it MUST be suffixed by ":".
  292. * - If an authority is present, it MUST be prefixed by "//".
  293. * - The path can be concatenated without delimiters. But there are two
  294. * cases where the path has to be adjusted to make the URI reference
  295. * valid as PHP does not allow to throw an exception in __toString():
  296. * - If the path is rootless and an authority is present, the path MUST
  297. * be prefixed by "/".
  298. * - If the path is starting with more than one "/" and no authority is
  299. * present, the starting slashes MUST be reduced to one.
  300. * - If a query is present, it MUST be prefixed by "?".
  301. * - If a fragment is present, it MUST be prefixed by "#".
  302. *
  303. * @see http://tools.ietf.org/html/rfc3986#section-4.1
  304. * @return string
  305. */
  306. public function __toString();
  307. }