Verzeichnisstruktur phpBB-3.3.15


Veröffentlicht
28.08.2024

So funktioniert es


Auf das letzte Element klicken. Dies geht jeweils ein Schritt zurück

Auf das Icon klicken, dies öffnet das Verzeichnis. Nochmal klicken schließt das Verzeichnis.
Auf den Verzeichnisnamen klicken, dies zeigt nur das Verzeichnis mit Inhalt an

(Beispiel Datei-Icons)

Auf das Icon klicken um den Quellcode anzuzeigen

UriInterface.php

Zuletzt modifiziert: 02.04.2025, 15:03 - Dateigröße: 12.39 KiB


001  <?php
002   
003  declare(strict_types=1);
004   
005  namespace Psr\Http\Message;
006   
007  /**
008   * Value object representing a URI.
009   *
010   * This interface is meant to represent URIs according to RFC 3986 and to
011   * provide methods for most common operations. Additional functionality for
012   * working with URIs can be provided on top of the interface or externally.
013   * Its primary use is for HTTP requests, but may also be used in other
014   * contexts.
015   *
016   * Instances of this interface are considered immutable; all methods that
017   * might change state MUST be implemented such that they retain the internal
018   * state of the current instance and return an instance that contains the
019   * changed state.
020   *
021   * Typically the Host header will be also be present in the request message.
022   * For server-side requests, the scheme will typically be discoverable in the
023   * server parameters.
024   *
025   * @link http://tools.ietf.org/html/rfc3986 (the URI specification)
026   */
027  interface UriInterface
028  {
029      /**
030       * Retrieve the scheme component of the URI.
031       *
032       * If no scheme is present, this method MUST return an empty string.
033       *
034       * The value returned MUST be normalized to lowercase, per RFC 3986
035       * Section 3.1.
036       *
037       * The trailing ":" character is not part of the scheme and MUST NOT be
038       * added.
039       *
040       * @see https://tools.ietf.org/html/rfc3986#section-3.1
041       * @return string The URI scheme.
042       */
043      public function getScheme();
044   
045      /**
046       * Retrieve the authority component of the URI.
047       *
048       * If no authority information is present, this method MUST return an empty
049       * string.
050       *
051       * The authority syntax of the URI is:
052       *
053       * <pre>
054       * [user-info@]host[:port]
055       * </pre>
056       *
057       * If the port component is not set or is the standard port for the current
058       * scheme, it SHOULD NOT be included.
059       *
060       * @see https://tools.ietf.org/html/rfc3986#section-3.2
061       * @return string The URI authority, in "[user-info@]host[:port]" format.
062       */
063      public function getAuthority();
064   
065      /**
066       * Retrieve the user information component of the URI.
067       *
068       * If no user information is present, this method MUST return an empty
069       * string.
070       *
071       * If a user is present in the URI, this will return that value;
072       * additionally, if the password is also present, it will be appended to the
073       * user value, with a colon (":") separating the values.
074       *
075       * The trailing "@" character is not part of the user information and MUST
076       * NOT be added.
077       *
078       * @return string The URI user information, in "username[:password]" format.
079       */
080      public function getUserInfo();
081   
082      /**
083       * Retrieve the host component of the URI.
084       *
085       * If no host is present, this method MUST return an empty string.
086       *
087       * The value returned MUST be normalized to lowercase, per RFC 3986
088       * Section 3.2.2.
089       *
090       * @see http://tools.ietf.org/html/rfc3986#section-3.2.2
091       * @return string The URI host.
092       */
093      public function getHost();
094   
095      /**
096       * Retrieve the port component of the URI.
097       *
098       * If a port is present, and it is non-standard for the current scheme,
099       * this method MUST return it as an integer. If the port is the standard port
100       * used with the current scheme, this method SHOULD return null.
101       *
102       * If no port is present, and no scheme is present, this method MUST return
103       * a null value.
104       *
105       * If no port is present, but a scheme is present, this method MAY return
106       * the standard port for that scheme, but SHOULD return null.
107       *
108       * @return null|int The URI port.
109       */
110      public function getPort();
111   
112      /**
113       * Retrieve the path component of the URI.
114       *
115       * The path can either be empty or absolute (starting with a slash) or
116       * rootless (not starting with a slash). Implementations MUST support all
117       * three syntaxes.
118       *
119       * Normally, the empty path "" and absolute path "/" are considered equal as
120       * defined in RFC 7230 Section 2.7.3. But this method MUST NOT automatically
121       * do this normalization because in contexts with a trimmed base path, e.g.
122       * the front controller, this difference becomes significant. It's the task
123       * of the user to handle both "" and "/".
124       *
125       * The value returned MUST be percent-encoded, but MUST NOT double-encode
126       * any characters. To determine what characters to encode, please refer to
127       * RFC 3986, Sections 2 and 3.3.
128       *
129       * As an example, if the value should include a slash ("/") not intended as
130       * delimiter between path segments, that value MUST be passed in encoded
131       * form (e.g., "%2F") to the instance.
132       *
133       * @see https://tools.ietf.org/html/rfc3986#section-2
134       * @see https://tools.ietf.org/html/rfc3986#section-3.3
135       * @return string The URI path.
136       */
137      public function getPath();
138   
139      /**
140       * Retrieve the query string of the URI.
141       *
142       * If no query string is present, this method MUST return an empty string.
143       *
144       * The leading "?" character is not part of the query and MUST NOT be
145       * added.
146       *
147       * The value returned MUST be percent-encoded, but MUST NOT double-encode
148       * any characters. To determine what characters to encode, please refer to
149       * RFC 3986, Sections 2 and 3.4.
150       *
151       * As an example, if a value in a key/value pair of the query string should
152       * include an ampersand ("&") not intended as a delimiter between values,
153       * that value MUST be passed in encoded form (e.g., "%26") to the instance.
154       *
155       * @see https://tools.ietf.org/html/rfc3986#section-2
156       * @see https://tools.ietf.org/html/rfc3986#section-3.4
157       * @return string The URI query string.
158       */
159      public function getQuery();
160   
161      /**
162       * Retrieve the fragment component of the URI.
163       *
164       * If no fragment is present, this method MUST return an empty string.
165       *
166       * The leading "#" character is not part of the fragment and MUST NOT be
167       * added.
168       *
169       * The value returned MUST be percent-encoded, but MUST NOT double-encode
170       * any characters. To determine what characters to encode, please refer to
171       * RFC 3986, Sections 2 and 3.5.
172       *
173       * @see https://tools.ietf.org/html/rfc3986#section-2
174       * @see https://tools.ietf.org/html/rfc3986#section-3.5
175       * @return string The URI fragment.
176       */
177      public function getFragment();
178   
179      /**
180       * Return an instance with the specified scheme.
181       *
182       * This method MUST retain the state of the current instance, and return
183       * an instance that contains the specified scheme.
184       *
185       * Implementations MUST support the schemes "http" and "https" case
186       * insensitively, and MAY accommodate other schemes if required.
187       *
188       * An empty scheme is equivalent to removing the scheme.
189       *
190       * @param string $scheme The scheme to use with the new instance.
191       * @return static A new instance with the specified scheme.
192       * @throws \InvalidArgumentException for invalid or unsupported schemes.
193       */
194      public function withScheme(string $scheme);
195   
196      /**
197       * Return an instance with the specified user information.
198       *
199       * This method MUST retain the state of the current instance, and return
200       * an instance that contains the specified user information.
201       *
202       * Password is optional, but the user information MUST include the
203       * user; an empty string for the user is equivalent to removing user
204       * information.
205       *
206       * @param string $user The user name to use for authority.
207       * @param null|string $password The password associated with $user.
208       * @return static A new instance with the specified user information.
209       */
210      public function withUserInfo(string $user, ?string $password = null);
211   
212      /**
213       * Return an instance with the specified host.
214       *
215       * This method MUST retain the state of the current instance, and return
216       * an instance that contains the specified host.
217       *
218       * An empty host value is equivalent to removing the host.
219       *
220       * @param string $host The hostname to use with the new instance.
221       * @return static A new instance with the specified host.
222       * @throws \InvalidArgumentException for invalid hostnames.
223       */
224      public function withHost(string $host);
225   
226      /**
227       * Return an instance with the specified port.
228       *
229       * This method MUST retain the state of the current instance, and return
230       * an instance that contains the specified port.
231       *
232       * Implementations MUST raise an exception for ports outside the
233       * established TCP and UDP port ranges.
234       *
235       * A null value provided for the port is equivalent to removing the port
236       * information.
237       *
238       * @param null|int $port The port to use with the new instance; a null value
239       *     removes the port information.
240       * @return static A new instance with the specified port.
241       * @throws \InvalidArgumentException for invalid ports.
242       */
243      public function withPort(?int $port);
244   
245      /**
246       * Return an instance with the specified path.
247       *
248       * This method MUST retain the state of the current instance, and return
249       * an instance that contains the specified path.
250       *
251       * The path can either be empty or absolute (starting with a slash) or
252       * rootless (not starting with a slash). Implementations MUST support all
253       * three syntaxes.
254       *
255       * If the path is intended to be domain-relative rather than path relative then
256       * it must begin with a slash ("/"). Paths not starting with a slash ("/")
257       * are assumed to be relative to some base path known to the application or
258       * consumer.
259       *
260       * Users can provide both encoded and decoded path characters.
261       * Implementations ensure the correct encoding as outlined in getPath().
262       *
263       * @param string $path The path to use with the new instance.
264       * @return static A new instance with the specified path.
265       * @throws \InvalidArgumentException for invalid paths.
266       */
267      public function withPath(string $path);
268   
269      /**
270       * Return an instance with the specified query string.
271       *
272       * This method MUST retain the state of the current instance, and return
273       * an instance that contains the specified query string.
274       *
275       * Users can provide both encoded and decoded query characters.
276       * Implementations ensure the correct encoding as outlined in getQuery().
277       *
278       * An empty query string value is equivalent to removing the query string.
279       *
280       * @param string $query The query string to use with the new instance.
281       * @return static A new instance with the specified query string.
282       * @throws \InvalidArgumentException for invalid query strings.
283       */
284      public function withQuery(string $query);
285   
286      /**
287       * Return an instance with the specified URI fragment.
288       *
289       * This method MUST retain the state of the current instance, and return
290       * an instance that contains the specified URI fragment.
291       *
292       * Users can provide both encoded and decoded fragment characters.
293       * Implementations ensure the correct encoding as outlined in getFragment().
294       *
295       * An empty fragment value is equivalent to removing the fragment.
296       *
297       * @param string $fragment The fragment to use with the new instance.
298       * @return static A new instance with the specified fragment.
299       */
300      public function withFragment(string $fragment);
301   
302      /**
303       * Return the string representation as a URI reference.
304       *
305       * Depending on which components of the URI are present, the resulting
306       * string is either a full URI or relative reference according to RFC 3986,
307       * Section 4.1. The method concatenates the various components of the URI,
308       * using the appropriate delimiters:
309       *
310       * - If a scheme is present, it MUST be suffixed by ":".
311       * - If an authority is present, it MUST be prefixed by "//".
312       * - The path can be concatenated without delimiters. But there are two
313       *   cases where the path has to be adjusted to make the URI reference
314       *   valid as PHP does not allow to throw an exception in __toString():
315       *     - If the path is rootless and an authority is present, the path MUST
316       *       be prefixed by "/".
317       *     - If the path is starting with more than one "/" and no authority is
318       *       present, the starting slashes MUST be reduced to one.
319       * - If a query is present, it MUST be prefixed by "?".
320       * - If a fragment is present, it MUST be prefixed by "#".
321       *
322       * @see http://tools.ietf.org/html/rfc3986#section-4.1
323       * @return string
324       */
325      public function __toString();
326  }
327