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