@@ -24,301 +24,301 @@ |
||
| 24 | 24 | */ |
| 25 | 25 | interface UriInterface |
| 26 | 26 | { |
| 27 | - /** |
|
| 28 | - * Retrieve the scheme component of the URI. |
|
| 29 | - * |
|
| 30 | - * If no scheme is present, this method MUST return an empty string. |
|
| 31 | - * |
|
| 32 | - * The value returned MUST be normalized to lowercase, per RFC 3986 |
|
| 33 | - * Section 3.1. |
|
| 34 | - * |
|
| 35 | - * The trailing ":" character is not part of the scheme and MUST NOT be |
|
| 36 | - * added. |
|
| 37 | - * |
|
| 38 | - * @see https://tools.ietf.org/html/rfc3986#section-3.1 |
|
| 39 | - * @return string The URI scheme. |
|
| 40 | - */ |
|
| 41 | - public function getScheme(): string; |
|
| 27 | + /** |
|
| 28 | + * Retrieve the scheme component of the URI. |
|
| 29 | + * |
|
| 30 | + * If no scheme is present, this method MUST return an empty string. |
|
| 31 | + * |
|
| 32 | + * The value returned MUST be normalized to lowercase, per RFC 3986 |
|
| 33 | + * Section 3.1. |
|
| 34 | + * |
|
| 35 | + * The trailing ":" character is not part of the scheme and MUST NOT be |
|
| 36 | + * added. |
|
| 37 | + * |
|
| 38 | + * @see https://tools.ietf.org/html/rfc3986#section-3.1 |
|
| 39 | + * @return string The URI scheme. |
|
| 40 | + */ |
|
| 41 | + public function getScheme(): string; |
|
| 42 | 42 | |
| 43 | - /** |
|
| 44 | - * Retrieve the authority component of the URI. |
|
| 45 | - * |
|
| 46 | - * If no authority information is present, this method MUST return an empty |
|
| 47 | - * string. |
|
| 48 | - * |
|
| 49 | - * The authority syntax of the URI is: |
|
| 50 | - * |
|
| 51 | - * <pre> |
|
| 52 | - * [user-info@]host[:port] |
|
| 53 | - * </pre> |
|
| 54 | - * |
|
| 55 | - * If the port component is not set or is the standard port for the current |
|
| 56 | - * scheme, it SHOULD NOT be included. |
|
| 57 | - * |
|
| 58 | - * @see https://tools.ietf.org/html/rfc3986#section-3.2 |
|
| 59 | - * @return string The URI authority, in "[user-info@]host[:port]" format. |
|
| 60 | - */ |
|
| 61 | - public function getAuthority(): string; |
|
| 43 | + /** |
|
| 44 | + * Retrieve the authority component of the URI. |
|
| 45 | + * |
|
| 46 | + * If no authority information is present, this method MUST return an empty |
|
| 47 | + * string. |
|
| 48 | + * |
|
| 49 | + * The authority syntax of the URI is: |
|
| 50 | + * |
|
| 51 | + * <pre> |
|
| 52 | + * [user-info@]host[:port] |
|
| 53 | + * </pre> |
|
| 54 | + * |
|
| 55 | + * If the port component is not set or is the standard port for the current |
|
| 56 | + * scheme, it SHOULD NOT be included. |
|
| 57 | + * |
|
| 58 | + * @see https://tools.ietf.org/html/rfc3986#section-3.2 |
|
| 59 | + * @return string The URI authority, in "[user-info@]host[:port]" format. |
|
| 60 | + */ |
|
| 61 | + public function getAuthority(): string; |
|
| 62 | 62 | |
| 63 | - /** |
|
| 64 | - * Retrieve the user information component of the URI. |
|
| 65 | - * |
|
| 66 | - * If no user information is present, this method MUST return an empty |
|
| 67 | - * string. |
|
| 68 | - * |
|
| 69 | - * If a user is present in the URI, this will return that value; |
|
| 70 | - * additionally, if the password is also present, it will be appended to the |
|
| 71 | - * user value, with a colon (":") separating the values. |
|
| 72 | - * |
|
| 73 | - * The trailing "@" character is not part of the user information and MUST |
|
| 74 | - * NOT be added. |
|
| 75 | - * |
|
| 76 | - * @return string The URI user information, in "username[:password]" format. |
|
| 77 | - */ |
|
| 78 | - public function getUserInfo(): string; |
|
| 63 | + /** |
|
| 64 | + * Retrieve the user information component of the URI. |
|
| 65 | + * |
|
| 66 | + * If no user information is present, this method MUST return an empty |
|
| 67 | + * string. |
|
| 68 | + * |
|
| 69 | + * If a user is present in the URI, this will return that value; |
|
| 70 | + * additionally, if the password is also present, it will be appended to the |
|
| 71 | + * user value, with a colon (":") separating the values. |
|
| 72 | + * |
|
| 73 | + * The trailing "@" character is not part of the user information and MUST |
|
| 74 | + * NOT be added. |
|
| 75 | + * |
|
| 76 | + * @return string The URI user information, in "username[:password]" format. |
|
| 77 | + */ |
|
| 78 | + public function getUserInfo(): string; |
|
| 79 | 79 | |
| 80 | - /** |
|
| 81 | - * Retrieve the host component of the URI. |
|
| 82 | - * |
|
| 83 | - * If no host is present, this method MUST return an empty string. |
|
| 84 | - * |
|
| 85 | - * The value returned MUST be normalized to lowercase, per RFC 3986 |
|
| 86 | - * Section 3.2.2. |
|
| 87 | - * |
|
| 88 | - * @see http://tools.ietf.org/html/rfc3986#section-3.2.2 |
|
| 89 | - * @return string The URI host. |
|
| 90 | - */ |
|
| 91 | - public function getHost(): string; |
|
| 80 | + /** |
|
| 81 | + * Retrieve the host component of the URI. |
|
| 82 | + * |
|
| 83 | + * If no host is present, this method MUST return an empty string. |
|
| 84 | + * |
|
| 85 | + * The value returned MUST be normalized to lowercase, per RFC 3986 |
|
| 86 | + * Section 3.2.2. |
|
| 87 | + * |
|
| 88 | + * @see http://tools.ietf.org/html/rfc3986#section-3.2.2 |
|
| 89 | + * @return string The URI host. |
|
| 90 | + */ |
|
| 91 | + public function getHost(): string; |
|
| 92 | 92 | |
| 93 | - /** |
|
| 94 | - * Retrieve the port component of the URI. |
|
| 95 | - * |
|
| 96 | - * If a port is present, and it is non-standard for the current scheme, |
|
| 97 | - * this method MUST return it as an integer. If the port is the standard port |
|
| 98 | - * used with the current scheme, this method SHOULD return null. |
|
| 99 | - * |
|
| 100 | - * If no port is present, and no scheme is present, this method MUST return |
|
| 101 | - * a null value. |
|
| 102 | - * |
|
| 103 | - * If no port is present, but a scheme is present, this method MAY return |
|
| 104 | - * the standard port for that scheme, but SHOULD return null. |
|
| 105 | - * |
|
| 106 | - * @return null|int The URI port. |
|
| 107 | - */ |
|
| 108 | - public function getPort(): ?int; |
|
| 93 | + /** |
|
| 94 | + * Retrieve the port component of the URI. |
|
| 95 | + * |
|
| 96 | + * If a port is present, and it is non-standard for the current scheme, |
|
| 97 | + * this method MUST return it as an integer. If the port is the standard port |
|
| 98 | + * used with the current scheme, this method SHOULD return null. |
|
| 99 | + * |
|
| 100 | + * If no port is present, and no scheme is present, this method MUST return |
|
| 101 | + * a null value. |
|
| 102 | + * |
|
| 103 | + * If no port is present, but a scheme is present, this method MAY return |
|
| 104 | + * the standard port for that scheme, but SHOULD return null. |
|
| 105 | + * |
|
| 106 | + * @return null|int The URI port. |
|
| 107 | + */ |
|
| 108 | + public function getPort(): ?int; |
|
| 109 | 109 | |
| 110 | - /** |
|
| 111 | - * Retrieve the path component of the URI. |
|
| 112 | - * |
|
| 113 | - * The path can either be empty or absolute (starting with a slash) or |
|
| 114 | - * rootless (not starting with a slash). Implementations MUST support all |
|
| 115 | - * three syntaxes. |
|
| 116 | - * |
|
| 117 | - * Normally, the empty path "" and absolute path "/" are considered equal as |
|
| 118 | - * defined in RFC 7230 Section 2.7.3. But this method MUST NOT automatically |
|
| 119 | - * do this normalization because in contexts with a trimmed base path, e.g. |
|
| 120 | - * the front controller, this difference becomes significant. It's the task |
|
| 121 | - * of the user to handle both "" and "/". |
|
| 122 | - * |
|
| 123 | - * The value returned MUST be percent-encoded, but MUST NOT double-encode |
|
| 124 | - * any characters. To determine what characters to encode, please refer to |
|
| 125 | - * RFC 3986, Sections 2 and 3.3. |
|
| 126 | - * |
|
| 127 | - * As an example, if the value should include a slash ("/") not intended as |
|
| 128 | - * delimiter between path segments, that value MUST be passed in encoded |
|
| 129 | - * form (e.g., "%2F") to the instance. |
|
| 130 | - * |
|
| 131 | - * @see https://tools.ietf.org/html/rfc3986#section-2 |
|
| 132 | - * @see https://tools.ietf.org/html/rfc3986#section-3.3 |
|
| 133 | - * @return string The URI path. |
|
| 134 | - */ |
|
| 135 | - public function getPath(): string; |
|
| 110 | + /** |
|
| 111 | + * Retrieve the path component of the URI. |
|
| 112 | + * |
|
| 113 | + * The path can either be empty or absolute (starting with a slash) or |
|
| 114 | + * rootless (not starting with a slash). Implementations MUST support all |
|
| 115 | + * three syntaxes. |
|
| 116 | + * |
|
| 117 | + * Normally, the empty path "" and absolute path "/" are considered equal as |
|
| 118 | + * defined in RFC 7230 Section 2.7.3. But this method MUST NOT automatically |
|
| 119 | + * do this normalization because in contexts with a trimmed base path, e.g. |
|
| 120 | + * the front controller, this difference becomes significant. It's the task |
|
| 121 | + * of the user to handle both "" and "/". |
|
| 122 | + * |
|
| 123 | + * The value returned MUST be percent-encoded, but MUST NOT double-encode |
|
| 124 | + * any characters. To determine what characters to encode, please refer to |
|
| 125 | + * RFC 3986, Sections 2 and 3.3. |
|
| 126 | + * |
|
| 127 | + * As an example, if the value should include a slash ("/") not intended as |
|
| 128 | + * delimiter between path segments, that value MUST be passed in encoded |
|
| 129 | + * form (e.g., "%2F") to the instance. |
|
| 130 | + * |
|
| 131 | + * @see https://tools.ietf.org/html/rfc3986#section-2 |
|
| 132 | + * @see https://tools.ietf.org/html/rfc3986#section-3.3 |
|
| 133 | + * @return string The URI path. |
|
| 134 | + */ |
|
| 135 | + public function getPath(): string; |
|
| 136 | 136 | |
| 137 | - /** |
|
| 138 | - * Retrieve the query string of the URI. |
|
| 139 | - * |
|
| 140 | - * If no query string is present, this method MUST return an empty string. |
|
| 141 | - * |
|
| 142 | - * The leading "?" character is not part of the query and MUST NOT be |
|
| 143 | - * added. |
|
| 144 | - * |
|
| 145 | - * The value returned MUST be percent-encoded, but MUST NOT double-encode |
|
| 146 | - * any characters. To determine what characters to encode, please refer to |
|
| 147 | - * RFC 3986, Sections 2 and 3.4. |
|
| 148 | - * |
|
| 149 | - * As an example, if a value in a key/value pair of the query string should |
|
| 150 | - * include an ampersand ("&") not intended as a delimiter between values, |
|
| 151 | - * that value MUST be passed in encoded form (e.g., "%26") to the instance. |
|
| 152 | - * |
|
| 153 | - * @see https://tools.ietf.org/html/rfc3986#section-2 |
|
| 154 | - * @see https://tools.ietf.org/html/rfc3986#section-3.4 |
|
| 155 | - * @return string The URI query string. |
|
| 156 | - */ |
|
| 157 | - public function getQuery(): string; |
|
| 137 | + /** |
|
| 138 | + * Retrieve the query string of the URI. |
|
| 139 | + * |
|
| 140 | + * If no query string is present, this method MUST return an empty string. |
|
| 141 | + * |
|
| 142 | + * The leading "?" character is not part of the query and MUST NOT be |
|
| 143 | + * added. |
|
| 144 | + * |
|
| 145 | + * The value returned MUST be percent-encoded, but MUST NOT double-encode |
|
| 146 | + * any characters. To determine what characters to encode, please refer to |
|
| 147 | + * RFC 3986, Sections 2 and 3.4. |
|
| 148 | + * |
|
| 149 | + * As an example, if a value in a key/value pair of the query string should |
|
| 150 | + * include an ampersand ("&") not intended as a delimiter between values, |
|
| 151 | + * that value MUST be passed in encoded form (e.g., "%26") to the instance. |
|
| 152 | + * |
|
| 153 | + * @see https://tools.ietf.org/html/rfc3986#section-2 |
|
| 154 | + * @see https://tools.ietf.org/html/rfc3986#section-3.4 |
|
| 155 | + * @return string The URI query string. |
|
| 156 | + */ |
|
| 157 | + public function getQuery(): string; |
|
| 158 | 158 | |
| 159 | - /** |
|
| 160 | - * Retrieve the fragment component of the URI. |
|
| 161 | - * |
|
| 162 | - * If no fragment is present, this method MUST return an empty string. |
|
| 163 | - * |
|
| 164 | - * The leading "#" character is not part of the fragment and MUST NOT be |
|
| 165 | - * added. |
|
| 166 | - * |
|
| 167 | - * The value returned MUST be percent-encoded, but MUST NOT double-encode |
|
| 168 | - * any characters. To determine what characters to encode, please refer to |
|
| 169 | - * RFC 3986, Sections 2 and 3.5. |
|
| 170 | - * |
|
| 171 | - * @see https://tools.ietf.org/html/rfc3986#section-2 |
|
| 172 | - * @see https://tools.ietf.org/html/rfc3986#section-3.5 |
|
| 173 | - * @return string The URI fragment. |
|
| 174 | - */ |
|
| 175 | - public function getFragment(): string; |
|
| 159 | + /** |
|
| 160 | + * Retrieve the fragment component of the URI. |
|
| 161 | + * |
|
| 162 | + * If no fragment is present, this method MUST return an empty string. |
|
| 163 | + * |
|
| 164 | + * The leading "#" character is not part of the fragment and MUST NOT be |
|
| 165 | + * added. |
|
| 166 | + * |
|
| 167 | + * The value returned MUST be percent-encoded, but MUST NOT double-encode |
|
| 168 | + * any characters. To determine what characters to encode, please refer to |
|
| 169 | + * RFC 3986, Sections 2 and 3.5. |
|
| 170 | + * |
|
| 171 | + * @see https://tools.ietf.org/html/rfc3986#section-2 |
|
| 172 | + * @see https://tools.ietf.org/html/rfc3986#section-3.5 |
|
| 173 | + * @return string The URI fragment. |
|
| 174 | + */ |
|
| 175 | + public function getFragment(): string; |
|
| 176 | 176 | |
| 177 | - /** |
|
| 178 | - * Return an instance with the specified scheme. |
|
| 179 | - * |
|
| 180 | - * This method MUST retain the state of the current instance, and return |
|
| 181 | - * an instance that contains the specified scheme. |
|
| 182 | - * |
|
| 183 | - * Implementations MUST support the schemes "http" and "https" case |
|
| 184 | - * insensitively, and MAY accommodate other schemes if required. |
|
| 185 | - * |
|
| 186 | - * An empty scheme is equivalent to removing the scheme. |
|
| 187 | - * |
|
| 188 | - * @param string $scheme The scheme to use with the new instance. |
|
| 189 | - * @return static A new instance with the specified scheme. |
|
| 190 | - * @throws \InvalidArgumentException for invalid or unsupported schemes. |
|
| 191 | - */ |
|
| 192 | - public function withScheme(string $scheme): UriInterface; |
|
| 177 | + /** |
|
| 178 | + * Return an instance with the specified scheme. |
|
| 179 | + * |
|
| 180 | + * This method MUST retain the state of the current instance, and return |
|
| 181 | + * an instance that contains the specified scheme. |
|
| 182 | + * |
|
| 183 | + * Implementations MUST support the schemes "http" and "https" case |
|
| 184 | + * insensitively, and MAY accommodate other schemes if required. |
|
| 185 | + * |
|
| 186 | + * An empty scheme is equivalent to removing the scheme. |
|
| 187 | + * |
|
| 188 | + * @param string $scheme The scheme to use with the new instance. |
|
| 189 | + * @return static A new instance with the specified scheme. |
|
| 190 | + * @throws \InvalidArgumentException for invalid or unsupported schemes. |
|
| 191 | + */ |
|
| 192 | + public function withScheme(string $scheme): UriInterface; |
|
| 193 | 193 | |
| 194 | - /** |
|
| 195 | - * Return an instance with the specified user information. |
|
| 196 | - * |
|
| 197 | - * This method MUST retain the state of the current instance, and return |
|
| 198 | - * an instance that contains the specified user information. |
|
| 199 | - * |
|
| 200 | - * Password is optional, but the user information MUST include the |
|
| 201 | - * user; an empty string for the user is equivalent to removing user |
|
| 202 | - * information. |
|
| 203 | - * |
|
| 204 | - * @param string $user The user name to use for authority. |
|
| 205 | - * @param null|string $password The password associated with $user. |
|
| 206 | - * @return static A new instance with the specified user information. |
|
| 207 | - */ |
|
| 208 | - public function withUserInfo(string $user, ?string $password = null): UriInterface; |
|
| 194 | + /** |
|
| 195 | + * Return an instance with the specified user information. |
|
| 196 | + * |
|
| 197 | + * This method MUST retain the state of the current instance, and return |
|
| 198 | + * an instance that contains the specified user information. |
|
| 199 | + * |
|
| 200 | + * Password is optional, but the user information MUST include the |
|
| 201 | + * user; an empty string for the user is equivalent to removing user |
|
| 202 | + * information. |
|
| 203 | + * |
|
| 204 | + * @param string $user The user name to use for authority. |
|
| 205 | + * @param null|string $password The password associated with $user. |
|
| 206 | + * @return static A new instance with the specified user information. |
|
| 207 | + */ |
|
| 208 | + public function withUserInfo(string $user, ?string $password = null): UriInterface; |
|
| 209 | 209 | |
| 210 | - /** |
|
| 211 | - * Return an instance with the specified host. |
|
| 212 | - * |
|
| 213 | - * This method MUST retain the state of the current instance, and return |
|
| 214 | - * an instance that contains the specified host. |
|
| 215 | - * |
|
| 216 | - * An empty host value is equivalent to removing the host. |
|
| 217 | - * |
|
| 218 | - * @param string $host The hostname to use with the new instance. |
|
| 219 | - * @return static A new instance with the specified host. |
|
| 220 | - * @throws \InvalidArgumentException for invalid hostnames. |
|
| 221 | - */ |
|
| 222 | - public function withHost(string $host): UriInterface; |
|
| 210 | + /** |
|
| 211 | + * Return an instance with the specified host. |
|
| 212 | + * |
|
| 213 | + * This method MUST retain the state of the current instance, and return |
|
| 214 | + * an instance that contains the specified host. |
|
| 215 | + * |
|
| 216 | + * An empty host value is equivalent to removing the host. |
|
| 217 | + * |
|
| 218 | + * @param string $host The hostname to use with the new instance. |
|
| 219 | + * @return static A new instance with the specified host. |
|
| 220 | + * @throws \InvalidArgumentException for invalid hostnames. |
|
| 221 | + */ |
|
| 222 | + public function withHost(string $host): UriInterface; |
|
| 223 | 223 | |
| 224 | - /** |
|
| 225 | - * Return an instance with the specified port. |
|
| 226 | - * |
|
| 227 | - * This method MUST retain the state of the current instance, and return |
|
| 228 | - * an instance that contains the specified port. |
|
| 229 | - * |
|
| 230 | - * Implementations MUST raise an exception for ports outside the |
|
| 231 | - * established TCP and UDP port ranges. |
|
| 232 | - * |
|
| 233 | - * A null value provided for the port is equivalent to removing the port |
|
| 234 | - * information. |
|
| 235 | - * |
|
| 236 | - * @param null|int $port The port to use with the new instance; a null value |
|
| 237 | - * removes the port information. |
|
| 238 | - * @return static A new instance with the specified port. |
|
| 239 | - * @throws \InvalidArgumentException for invalid ports. |
|
| 240 | - */ |
|
| 241 | - public function withPort(?int $port): UriInterface; |
|
| 224 | + /** |
|
| 225 | + * Return an instance with the specified port. |
|
| 226 | + * |
|
| 227 | + * This method MUST retain the state of the current instance, and return |
|
| 228 | + * an instance that contains the specified port. |
|
| 229 | + * |
|
| 230 | + * Implementations MUST raise an exception for ports outside the |
|
| 231 | + * established TCP and UDP port ranges. |
|
| 232 | + * |
|
| 233 | + * A null value provided for the port is equivalent to removing the port |
|
| 234 | + * information. |
|
| 235 | + * |
|
| 236 | + * @param null|int $port The port to use with the new instance; a null value |
|
| 237 | + * removes the port information. |
|
| 238 | + * @return static A new instance with the specified port. |
|
| 239 | + * @throws \InvalidArgumentException for invalid ports. |
|
| 240 | + */ |
|
| 241 | + public function withPort(?int $port): UriInterface; |
|
| 242 | 242 | |
| 243 | - /** |
|
| 244 | - * Return an instance with the specified path. |
|
| 245 | - * |
|
| 246 | - * This method MUST retain the state of the current instance, and return |
|
| 247 | - * an instance that contains the specified path. |
|
| 248 | - * |
|
| 249 | - * The path can either be empty or absolute (starting with a slash) or |
|
| 250 | - * rootless (not starting with a slash). Implementations MUST support all |
|
| 251 | - * three syntaxes. |
|
| 252 | - * |
|
| 253 | - * If the path is intended to be domain-relative rather than path relative then |
|
| 254 | - * it must begin with a slash ("/"). Paths not starting with a slash ("/") |
|
| 255 | - * are assumed to be relative to some base path known to the application or |
|
| 256 | - * consumer. |
|
| 257 | - * |
|
| 258 | - * Users can provide both encoded and decoded path characters. |
|
| 259 | - * Implementations ensure the correct encoding as outlined in getPath(). |
|
| 260 | - * |
|
| 261 | - * @param string $path The path to use with the new instance. |
|
| 262 | - * @return static A new instance with the specified path. |
|
| 263 | - * @throws \InvalidArgumentException for invalid paths. |
|
| 264 | - */ |
|
| 265 | - public function withPath(string $path): UriInterface; |
|
| 243 | + /** |
|
| 244 | + * Return an instance with the specified path. |
|
| 245 | + * |
|
| 246 | + * This method MUST retain the state of the current instance, and return |
|
| 247 | + * an instance that contains the specified path. |
|
| 248 | + * |
|
| 249 | + * The path can either be empty or absolute (starting with a slash) or |
|
| 250 | + * rootless (not starting with a slash). Implementations MUST support all |
|
| 251 | + * three syntaxes. |
|
| 252 | + * |
|
| 253 | + * If the path is intended to be domain-relative rather than path relative then |
|
| 254 | + * it must begin with a slash ("/"). Paths not starting with a slash ("/") |
|
| 255 | + * are assumed to be relative to some base path known to the application or |
|
| 256 | + * consumer. |
|
| 257 | + * |
|
| 258 | + * Users can provide both encoded and decoded path characters. |
|
| 259 | + * Implementations ensure the correct encoding as outlined in getPath(). |
|
| 260 | + * |
|
| 261 | + * @param string $path The path to use with the new instance. |
|
| 262 | + * @return static A new instance with the specified path. |
|
| 263 | + * @throws \InvalidArgumentException for invalid paths. |
|
| 264 | + */ |
|
| 265 | + public function withPath(string $path): UriInterface; |
|
| 266 | 266 | |
| 267 | - /** |
|
| 268 | - * Return an instance with the specified query string. |
|
| 269 | - * |
|
| 270 | - * This method MUST retain the state of the current instance, and return |
|
| 271 | - * an instance that contains the specified query string. |
|
| 272 | - * |
|
| 273 | - * Users can provide both encoded and decoded query characters. |
|
| 274 | - * Implementations ensure the correct encoding as outlined in getQuery(). |
|
| 275 | - * |
|
| 276 | - * An empty query string value is equivalent to removing the query string. |
|
| 277 | - * |
|
| 278 | - * @param string $query The query string to use with the new instance. |
|
| 279 | - * @return static A new instance with the specified query string. |
|
| 280 | - * @throws \InvalidArgumentException for invalid query strings. |
|
| 281 | - */ |
|
| 282 | - public function withQuery(string $query): UriInterface; |
|
| 267 | + /** |
|
| 268 | + * Return an instance with the specified query string. |
|
| 269 | + * |
|
| 270 | + * This method MUST retain the state of the current instance, and return |
|
| 271 | + * an instance that contains the specified query string. |
|
| 272 | + * |
|
| 273 | + * Users can provide both encoded and decoded query characters. |
|
| 274 | + * Implementations ensure the correct encoding as outlined in getQuery(). |
|
| 275 | + * |
|
| 276 | + * An empty query string value is equivalent to removing the query string. |
|
| 277 | + * |
|
| 278 | + * @param string $query The query string to use with the new instance. |
|
| 279 | + * @return static A new instance with the specified query string. |
|
| 280 | + * @throws \InvalidArgumentException for invalid query strings. |
|
| 281 | + */ |
|
| 282 | + public function withQuery(string $query): UriInterface; |
|
| 283 | 283 | |
| 284 | - /** |
|
| 285 | - * Return an instance with the specified URI fragment. |
|
| 286 | - * |
|
| 287 | - * This method MUST retain the state of the current instance, and return |
|
| 288 | - * an instance that contains the specified URI fragment. |
|
| 289 | - * |
|
| 290 | - * Users can provide both encoded and decoded fragment characters. |
|
| 291 | - * Implementations ensure the correct encoding as outlined in getFragment(). |
|
| 292 | - * |
|
| 293 | - * An empty fragment value is equivalent to removing the fragment. |
|
| 294 | - * |
|
| 295 | - * @param string $fragment The fragment to use with the new instance. |
|
| 296 | - * @return static A new instance with the specified fragment. |
|
| 297 | - */ |
|
| 298 | - public function withFragment(string $fragment): UriInterface; |
|
| 284 | + /** |
|
| 285 | + * Return an instance with the specified URI fragment. |
|
| 286 | + * |
|
| 287 | + * This method MUST retain the state of the current instance, and return |
|
| 288 | + * an instance that contains the specified URI fragment. |
|
| 289 | + * |
|
| 290 | + * Users can provide both encoded and decoded fragment characters. |
|
| 291 | + * Implementations ensure the correct encoding as outlined in getFragment(). |
|
| 292 | + * |
|
| 293 | + * An empty fragment value is equivalent to removing the fragment. |
|
| 294 | + * |
|
| 295 | + * @param string $fragment The fragment to use with the new instance. |
|
| 296 | + * @return static A new instance with the specified fragment. |
|
| 297 | + */ |
|
| 298 | + public function withFragment(string $fragment): UriInterface; |
|
| 299 | 299 | |
| 300 | - /** |
|
| 301 | - * Return the string representation as a URI reference. |
|
| 302 | - * |
|
| 303 | - * Depending on which components of the URI are present, the resulting |
|
| 304 | - * string is either a full URI or relative reference according to RFC 3986, |
|
| 305 | - * Section 4.1. The method concatenates the various components of the URI, |
|
| 306 | - * using the appropriate delimiters: |
|
| 307 | - * |
|
| 308 | - * - If a scheme is present, it MUST be suffixed by ":". |
|
| 309 | - * - If an authority is present, it MUST be prefixed by "//". |
|
| 310 | - * - The path can be concatenated without delimiters. But there are two |
|
| 311 | - * cases where the path has to be adjusted to make the URI reference |
|
| 312 | - * valid as PHP does not allow to throw an exception in __toString(): |
|
| 313 | - * - If the path is rootless and an authority is present, the path MUST |
|
| 314 | - * be prefixed by "/". |
|
| 315 | - * - If the path is starting with more than one "/" and no authority is |
|
| 316 | - * present, the starting slashes MUST be reduced to one. |
|
| 317 | - * - If a query is present, it MUST be prefixed by "?". |
|
| 318 | - * - If a fragment is present, it MUST be prefixed by "#". |
|
| 319 | - * |
|
| 320 | - * @see http://tools.ietf.org/html/rfc3986#section-4.1 |
|
| 321 | - * @return string |
|
| 322 | - */ |
|
| 323 | - public function __toString(): string; |
|
| 300 | + /** |
|
| 301 | + * Return the string representation as a URI reference. |
|
| 302 | + * |
|
| 303 | + * Depending on which components of the URI are present, the resulting |
|
| 304 | + * string is either a full URI or relative reference according to RFC 3986, |
|
| 305 | + * Section 4.1. The method concatenates the various components of the URI, |
|
| 306 | + * using the appropriate delimiters: |
|
| 307 | + * |
|
| 308 | + * - If a scheme is present, it MUST be suffixed by ":". |
|
| 309 | + * - If an authority is present, it MUST be prefixed by "//". |
|
| 310 | + * - The path can be concatenated without delimiters. But there are two |
|
| 311 | + * cases where the path has to be adjusted to make the URI reference |
|
| 312 | + * valid as PHP does not allow to throw an exception in __toString(): |
|
| 313 | + * - If the path is rootless and an authority is present, the path MUST |
|
| 314 | + * be prefixed by "/". |
|
| 315 | + * - If the path is starting with more than one "/" and no authority is |
|
| 316 | + * present, the starting slashes MUST be reduced to one. |
|
| 317 | + * - If a query is present, it MUST be prefixed by "?". |
|
| 318 | + * - If a fragment is present, it MUST be prefixed by "#". |
|
| 319 | + * |
|
| 320 | + * @see http://tools.ietf.org/html/rfc3986#section-4.1 |
|
| 321 | + * @return string |
|
| 322 | + */ |
|
| 323 | + public function __toString(): string; |
|
| 324 | 324 | } |
@@ -22,8 +22,7 @@ |
||
| 22 | 22 | * |
| 23 | 23 | * @link http://tools.ietf.org/html/rfc3986 (the URI specification) |
| 24 | 24 | */ |
| 25 | -interface UriInterface |
|
| 26 | -{ |
|
| 25 | +interface UriInterface { |
|
| 27 | 26 | /** |
| 28 | 27 | * Retrieve the scheme component of the URI. |
| 29 | 28 | * |
@@ -4,42 +4,42 @@ |
||
| 4 | 4 | |
| 5 | 5 | interface StreamFactoryInterface |
| 6 | 6 | { |
| 7 | - /** |
|
| 8 | - * Create a new stream from a string. |
|
| 9 | - * |
|
| 10 | - * The stream SHOULD be created with a temporary resource. |
|
| 11 | - * |
|
| 12 | - * @param string $content String content with which to populate the stream. |
|
| 13 | - * |
|
| 14 | - * @return StreamInterface |
|
| 15 | - */ |
|
| 16 | - public function createStream(string $content = ''): StreamInterface; |
|
| 7 | + /** |
|
| 8 | + * Create a new stream from a string. |
|
| 9 | + * |
|
| 10 | + * The stream SHOULD be created with a temporary resource. |
|
| 11 | + * |
|
| 12 | + * @param string $content String content with which to populate the stream. |
|
| 13 | + * |
|
| 14 | + * @return StreamInterface |
|
| 15 | + */ |
|
| 16 | + public function createStream(string $content = ''): StreamInterface; |
|
| 17 | 17 | |
| 18 | - /** |
|
| 19 | - * Create a stream from an existing file. |
|
| 20 | - * |
|
| 21 | - * The file MUST be opened using the given mode, which may be any mode |
|
| 22 | - * supported by the `fopen` function. |
|
| 23 | - * |
|
| 24 | - * The `$filename` MAY be any string supported by `fopen()`. |
|
| 25 | - * |
|
| 26 | - * @param string $filename Filename or stream URI to use as basis of stream. |
|
| 27 | - * @param string $mode Mode with which to open the underlying filename/stream. |
|
| 28 | - * |
|
| 29 | - * @return StreamInterface |
|
| 30 | - * @throws \RuntimeException If the file cannot be opened. |
|
| 31 | - * @throws \InvalidArgumentException If the mode is invalid. |
|
| 32 | - */ |
|
| 33 | - public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface; |
|
| 18 | + /** |
|
| 19 | + * Create a stream from an existing file. |
|
| 20 | + * |
|
| 21 | + * The file MUST be opened using the given mode, which may be any mode |
|
| 22 | + * supported by the `fopen` function. |
|
| 23 | + * |
|
| 24 | + * The `$filename` MAY be any string supported by `fopen()`. |
|
| 25 | + * |
|
| 26 | + * @param string $filename Filename or stream URI to use as basis of stream. |
|
| 27 | + * @param string $mode Mode with which to open the underlying filename/stream. |
|
| 28 | + * |
|
| 29 | + * @return StreamInterface |
|
| 30 | + * @throws \RuntimeException If the file cannot be opened. |
|
| 31 | + * @throws \InvalidArgumentException If the mode is invalid. |
|
| 32 | + */ |
|
| 33 | + public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface; |
|
| 34 | 34 | |
| 35 | - /** |
|
| 36 | - * Create a new stream from an existing resource. |
|
| 37 | - * |
|
| 38 | - * The stream MUST be readable and may be writable. |
|
| 39 | - * |
|
| 40 | - * @param resource $resource PHP resource to use as basis of stream. |
|
| 41 | - * |
|
| 42 | - * @return StreamInterface |
|
| 43 | - */ |
|
| 44 | - public function createStreamFromResource($resource): StreamInterface; |
|
| 35 | + /** |
|
| 36 | + * Create a new stream from an existing resource. |
|
| 37 | + * |
|
| 38 | + * The stream MUST be readable and may be writable. |
|
| 39 | + * |
|
| 40 | + * @param resource $resource PHP resource to use as basis of stream. |
|
| 41 | + * |
|
| 42 | + * @return StreamInterface |
|
| 43 | + */ |
|
| 44 | + public function createStreamFromResource($resource): StreamInterface; |
|
| 45 | 45 | } |
@@ -2,8 +2,7 @@ |
||
| 2 | 2 | |
| 3 | 3 | namespace OCA\FullTextSearch_Elasticsearch\Vendor\Psr\Http\Message; |
| 4 | 4 | |
| 5 | -interface StreamFactoryInterface |
|
| 6 | -{ |
|
| 5 | +interface StreamFactoryInterface { |
|
| 7 | 6 | /** |
| 8 | 7 | * Create a new stream from a string. |
| 9 | 8 | * |
@@ -4,31 +4,31 @@ |
||
| 4 | 4 | |
| 5 | 5 | interface UploadedFileFactoryInterface |
| 6 | 6 | { |
| 7 | - /** |
|
| 8 | - * Create a new uploaded file. |
|
| 9 | - * |
|
| 10 | - * If a size is not provided it will be determined by checking the size of |
|
| 11 | - * the file. |
|
| 12 | - * |
|
| 13 | - * @see http://php.net/manual/features.file-upload.post-method.php |
|
| 14 | - * @see http://php.net/manual/features.file-upload.errors.php |
|
| 15 | - * |
|
| 16 | - * @param StreamInterface $stream Underlying stream representing the |
|
| 17 | - * uploaded file content. |
|
| 18 | - * @param int $size in bytes |
|
| 19 | - * @param int $error PHP file upload error |
|
| 20 | - * @param string $clientFilename Filename as provided by the client, if any. |
|
| 21 | - * @param string $clientMediaType Media type as provided by the client, if any. |
|
| 22 | - * |
|
| 23 | - * @return UploadedFileInterface |
|
| 24 | - * |
|
| 25 | - * @throws \InvalidArgumentException If the file resource is not readable. |
|
| 26 | - */ |
|
| 27 | - public function createUploadedFile( |
|
| 28 | - StreamInterface $stream, |
|
| 29 | - int $size = null, |
|
| 30 | - int $error = \UPLOAD_ERR_OK, |
|
| 31 | - string $clientFilename = null, |
|
| 32 | - string $clientMediaType = null |
|
| 33 | - ): UploadedFileInterface; |
|
| 7 | + /** |
|
| 8 | + * Create a new uploaded file. |
|
| 9 | + * |
|
| 10 | + * If a size is not provided it will be determined by checking the size of |
|
| 11 | + * the file. |
|
| 12 | + * |
|
| 13 | + * @see http://php.net/manual/features.file-upload.post-method.php |
|
| 14 | + * @see http://php.net/manual/features.file-upload.errors.php |
|
| 15 | + * |
|
| 16 | + * @param StreamInterface $stream Underlying stream representing the |
|
| 17 | + * uploaded file content. |
|
| 18 | + * @param int $size in bytes |
|
| 19 | + * @param int $error PHP file upload error |
|
| 20 | + * @param string $clientFilename Filename as provided by the client, if any. |
|
| 21 | + * @param string $clientMediaType Media type as provided by the client, if any. |
|
| 22 | + * |
|
| 23 | + * @return UploadedFileInterface |
|
| 24 | + * |
|
| 25 | + * @throws \InvalidArgumentException If the file resource is not readable. |
|
| 26 | + */ |
|
| 27 | + public function createUploadedFile( |
|
| 28 | + StreamInterface $stream, |
|
| 29 | + int $size = null, |
|
| 30 | + int $error = \UPLOAD_ERR_OK, |
|
| 31 | + string $clientFilename = null, |
|
| 32 | + string $clientMediaType = null |
|
| 33 | + ): UploadedFileInterface; |
|
| 34 | 34 | } |
@@ -2,8 +2,7 @@ |
||
| 2 | 2 | |
| 3 | 3 | namespace OCA\FullTextSearch_Elasticsearch\Vendor\Psr\Http\Message; |
| 4 | 4 | |
| 5 | -interface UploadedFileFactoryInterface |
|
| 6 | -{ |
|
| 5 | +interface UploadedFileFactoryInterface { |
|
| 7 | 6 | /** |
| 8 | 7 | * Create a new uploaded file. |
| 9 | 8 | * |
@@ -16,172 +16,172 @@ |
||
| 16 | 16 | */ |
| 17 | 17 | interface MessageInterface |
| 18 | 18 | { |
| 19 | - /** |
|
| 20 | - * Retrieves the HTTP protocol version as a string. |
|
| 21 | - * |
|
| 22 | - * The string MUST contain only the HTTP version number (e.g., "1.1", "1.0"). |
|
| 23 | - * |
|
| 24 | - * @return string HTTP protocol version. |
|
| 25 | - */ |
|
| 26 | - public function getProtocolVersion(): string; |
|
| 19 | + /** |
|
| 20 | + * Retrieves the HTTP protocol version as a string. |
|
| 21 | + * |
|
| 22 | + * The string MUST contain only the HTTP version number (e.g., "1.1", "1.0"). |
|
| 23 | + * |
|
| 24 | + * @return string HTTP protocol version. |
|
| 25 | + */ |
|
| 26 | + public function getProtocolVersion(): string; |
|
| 27 | 27 | |
| 28 | - /** |
|
| 29 | - * Return an instance with the specified HTTP protocol version. |
|
| 30 | - * |
|
| 31 | - * The version string MUST contain only the HTTP version number (e.g., |
|
| 32 | - * "1.1", "1.0"). |
|
| 33 | - * |
|
| 34 | - * This method MUST be implemented in such a way as to retain the |
|
| 35 | - * immutability of the message, and MUST return an instance that has the |
|
| 36 | - * new protocol version. |
|
| 37 | - * |
|
| 38 | - * @param string $version HTTP protocol version |
|
| 39 | - * @return static |
|
| 40 | - */ |
|
| 41 | - public function withProtocolVersion(string $version): MessageInterface; |
|
| 28 | + /** |
|
| 29 | + * Return an instance with the specified HTTP protocol version. |
|
| 30 | + * |
|
| 31 | + * The version string MUST contain only the HTTP version number (e.g., |
|
| 32 | + * "1.1", "1.0"). |
|
| 33 | + * |
|
| 34 | + * This method MUST be implemented in such a way as to retain the |
|
| 35 | + * immutability of the message, and MUST return an instance that has the |
|
| 36 | + * new protocol version. |
|
| 37 | + * |
|
| 38 | + * @param string $version HTTP protocol version |
|
| 39 | + * @return static |
|
| 40 | + */ |
|
| 41 | + public function withProtocolVersion(string $version): MessageInterface; |
|
| 42 | 42 | |
| 43 | - /** |
|
| 44 | - * Retrieves all message header values. |
|
| 45 | - * |
|
| 46 | - * The keys represent the header name as it will be sent over the wire, and |
|
| 47 | - * each value is an array of strings associated with the header. |
|
| 48 | - * |
|
| 49 | - * // Represent the headers as a string |
|
| 50 | - * foreach ($message->getHeaders() as $name => $values) { |
|
| 51 | - * echo $name . ": " . implode(", ", $values); |
|
| 52 | - * } |
|
| 53 | - * |
|
| 54 | - * // Emit headers iteratively: |
|
| 55 | - * foreach ($message->getHeaders() as $name => $values) { |
|
| 56 | - * foreach ($values as $value) { |
|
| 57 | - * header(sprintf('%s: %s', $name, $value), false); |
|
| 58 | - * } |
|
| 59 | - * } |
|
| 60 | - * |
|
| 61 | - * While header names are not case-sensitive, getHeaders() will preserve the |
|
| 62 | - * exact case in which headers were originally specified. |
|
| 63 | - * |
|
| 64 | - * @return string[][] Returns an associative array of the message's headers. Each |
|
| 65 | - * key MUST be a header name, and each value MUST be an array of strings |
|
| 66 | - * for that header. |
|
| 67 | - */ |
|
| 68 | - public function getHeaders(): array; |
|
| 43 | + /** |
|
| 44 | + * Retrieves all message header values. |
|
| 45 | + * |
|
| 46 | + * The keys represent the header name as it will be sent over the wire, and |
|
| 47 | + * each value is an array of strings associated with the header. |
|
| 48 | + * |
|
| 49 | + * // Represent the headers as a string |
|
| 50 | + * foreach ($message->getHeaders() as $name => $values) { |
|
| 51 | + * echo $name . ": " . implode(", ", $values); |
|
| 52 | + * } |
|
| 53 | + * |
|
| 54 | + * // Emit headers iteratively: |
|
| 55 | + * foreach ($message->getHeaders() as $name => $values) { |
|
| 56 | + * foreach ($values as $value) { |
|
| 57 | + * header(sprintf('%s: %s', $name, $value), false); |
|
| 58 | + * } |
|
| 59 | + * } |
|
| 60 | + * |
|
| 61 | + * While header names are not case-sensitive, getHeaders() will preserve the |
|
| 62 | + * exact case in which headers were originally specified. |
|
| 63 | + * |
|
| 64 | + * @return string[][] Returns an associative array of the message's headers. Each |
|
| 65 | + * key MUST be a header name, and each value MUST be an array of strings |
|
| 66 | + * for that header. |
|
| 67 | + */ |
|
| 68 | + public function getHeaders(): array; |
|
| 69 | 69 | |
| 70 | - /** |
|
| 71 | - * Checks if a header exists by the given case-insensitive name. |
|
| 72 | - * |
|
| 73 | - * @param string $name Case-insensitive header field name. |
|
| 74 | - * @return bool Returns true if any header names match the given header |
|
| 75 | - * name using a case-insensitive string comparison. Returns false if |
|
| 76 | - * no matching header name is found in the message. |
|
| 77 | - */ |
|
| 78 | - public function hasHeader(string $name): bool; |
|
| 70 | + /** |
|
| 71 | + * Checks if a header exists by the given case-insensitive name. |
|
| 72 | + * |
|
| 73 | + * @param string $name Case-insensitive header field name. |
|
| 74 | + * @return bool Returns true if any header names match the given header |
|
| 75 | + * name using a case-insensitive string comparison. Returns false if |
|
| 76 | + * no matching header name is found in the message. |
|
| 77 | + */ |
|
| 78 | + public function hasHeader(string $name): bool; |
|
| 79 | 79 | |
| 80 | - /** |
|
| 81 | - * Retrieves a message header value by the given case-insensitive name. |
|
| 82 | - * |
|
| 83 | - * This method returns an array of all the header values of the given |
|
| 84 | - * case-insensitive header name. |
|
| 85 | - * |
|
| 86 | - * If the header does not appear in the message, this method MUST return an |
|
| 87 | - * empty array. |
|
| 88 | - * |
|
| 89 | - * @param string $name Case-insensitive header field name. |
|
| 90 | - * @return string[] An array of string values as provided for the given |
|
| 91 | - * header. If the header does not appear in the message, this method MUST |
|
| 92 | - * return an empty array. |
|
| 93 | - */ |
|
| 94 | - public function getHeader(string $name): array; |
|
| 80 | + /** |
|
| 81 | + * Retrieves a message header value by the given case-insensitive name. |
|
| 82 | + * |
|
| 83 | + * This method returns an array of all the header values of the given |
|
| 84 | + * case-insensitive header name. |
|
| 85 | + * |
|
| 86 | + * If the header does not appear in the message, this method MUST return an |
|
| 87 | + * empty array. |
|
| 88 | + * |
|
| 89 | + * @param string $name Case-insensitive header field name. |
|
| 90 | + * @return string[] An array of string values as provided for the given |
|
| 91 | + * header. If the header does not appear in the message, this method MUST |
|
| 92 | + * return an empty array. |
|
| 93 | + */ |
|
| 94 | + public function getHeader(string $name): array; |
|
| 95 | 95 | |
| 96 | - /** |
|
| 97 | - * Retrieves a comma-separated string of the values for a single header. |
|
| 98 | - * |
|
| 99 | - * This method returns all of the header values of the given |
|
| 100 | - * case-insensitive header name as a string concatenated together using |
|
| 101 | - * a comma. |
|
| 102 | - * |
|
| 103 | - * NOTE: Not all header values may be appropriately represented using |
|
| 104 | - * comma concatenation. For such headers, use getHeader() instead |
|
| 105 | - * and supply your own delimiter when concatenating. |
|
| 106 | - * |
|
| 107 | - * If the header does not appear in the message, this method MUST return |
|
| 108 | - * an empty string. |
|
| 109 | - * |
|
| 110 | - * @param string $name Case-insensitive header field name. |
|
| 111 | - * @return string A string of values as provided for the given header |
|
| 112 | - * concatenated together using a comma. If the header does not appear in |
|
| 113 | - * the message, this method MUST return an empty string. |
|
| 114 | - */ |
|
| 115 | - public function getHeaderLine(string $name): string; |
|
| 96 | + /** |
|
| 97 | + * Retrieves a comma-separated string of the values for a single header. |
|
| 98 | + * |
|
| 99 | + * This method returns all of the header values of the given |
|
| 100 | + * case-insensitive header name as a string concatenated together using |
|
| 101 | + * a comma. |
|
| 102 | + * |
|
| 103 | + * NOTE: Not all header values may be appropriately represented using |
|
| 104 | + * comma concatenation. For such headers, use getHeader() instead |
|
| 105 | + * and supply your own delimiter when concatenating. |
|
| 106 | + * |
|
| 107 | + * If the header does not appear in the message, this method MUST return |
|
| 108 | + * an empty string. |
|
| 109 | + * |
|
| 110 | + * @param string $name Case-insensitive header field name. |
|
| 111 | + * @return string A string of values as provided for the given header |
|
| 112 | + * concatenated together using a comma. If the header does not appear in |
|
| 113 | + * the message, this method MUST return an empty string. |
|
| 114 | + */ |
|
| 115 | + public function getHeaderLine(string $name): string; |
|
| 116 | 116 | |
| 117 | - /** |
|
| 118 | - * Return an instance with the provided value replacing the specified header. |
|
| 119 | - * |
|
| 120 | - * While header names are case-insensitive, the casing of the header will |
|
| 121 | - * be preserved by this function, and returned from getHeaders(). |
|
| 122 | - * |
|
| 123 | - * This method MUST be implemented in such a way as to retain the |
|
| 124 | - * immutability of the message, and MUST return an instance that has the |
|
| 125 | - * new and/or updated header and value. |
|
| 126 | - * |
|
| 127 | - * @param string $name Case-insensitive header field name. |
|
| 128 | - * @param string|string[] $value Header value(s). |
|
| 129 | - * @return static |
|
| 130 | - * @throws \InvalidArgumentException for invalid header names or values. |
|
| 131 | - */ |
|
| 132 | - public function withHeader(string $name, $value): MessageInterface; |
|
| 117 | + /** |
|
| 118 | + * Return an instance with the provided value replacing the specified header. |
|
| 119 | + * |
|
| 120 | + * While header names are case-insensitive, the casing of the header will |
|
| 121 | + * be preserved by this function, and returned from getHeaders(). |
|
| 122 | + * |
|
| 123 | + * This method MUST be implemented in such a way as to retain the |
|
| 124 | + * immutability of the message, and MUST return an instance that has the |
|
| 125 | + * new and/or updated header and value. |
|
| 126 | + * |
|
| 127 | + * @param string $name Case-insensitive header field name. |
|
| 128 | + * @param string|string[] $value Header value(s). |
|
| 129 | + * @return static |
|
| 130 | + * @throws \InvalidArgumentException for invalid header names or values. |
|
| 131 | + */ |
|
| 132 | + public function withHeader(string $name, $value): MessageInterface; |
|
| 133 | 133 | |
| 134 | - /** |
|
| 135 | - * Return an instance with the specified header appended with the given value. |
|
| 136 | - * |
|
| 137 | - * Existing values for the specified header will be maintained. The new |
|
| 138 | - * value(s) will be appended to the existing list. If the header did not |
|
| 139 | - * exist previously, it will be added. |
|
| 140 | - * |
|
| 141 | - * This method MUST be implemented in such a way as to retain the |
|
| 142 | - * immutability of the message, and MUST return an instance that has the |
|
| 143 | - * new header and/or value. |
|
| 144 | - * |
|
| 145 | - * @param string $name Case-insensitive header field name to add. |
|
| 146 | - * @param string|string[] $value Header value(s). |
|
| 147 | - * @return static |
|
| 148 | - * @throws \InvalidArgumentException for invalid header names or values. |
|
| 149 | - */ |
|
| 150 | - public function withAddedHeader(string $name, $value): MessageInterface; |
|
| 134 | + /** |
|
| 135 | + * Return an instance with the specified header appended with the given value. |
|
| 136 | + * |
|
| 137 | + * Existing values for the specified header will be maintained. The new |
|
| 138 | + * value(s) will be appended to the existing list. If the header did not |
|
| 139 | + * exist previously, it will be added. |
|
| 140 | + * |
|
| 141 | + * This method MUST be implemented in such a way as to retain the |
|
| 142 | + * immutability of the message, and MUST return an instance that has the |
|
| 143 | + * new header and/or value. |
|
| 144 | + * |
|
| 145 | + * @param string $name Case-insensitive header field name to add. |
|
| 146 | + * @param string|string[] $value Header value(s). |
|
| 147 | + * @return static |
|
| 148 | + * @throws \InvalidArgumentException for invalid header names or values. |
|
| 149 | + */ |
|
| 150 | + public function withAddedHeader(string $name, $value): MessageInterface; |
|
| 151 | 151 | |
| 152 | - /** |
|
| 153 | - * Return an instance without the specified header. |
|
| 154 | - * |
|
| 155 | - * Header resolution MUST be done without case-sensitivity. |
|
| 156 | - * |
|
| 157 | - * This method MUST be implemented in such a way as to retain the |
|
| 158 | - * immutability of the message, and MUST return an instance that removes |
|
| 159 | - * the named header. |
|
| 160 | - * |
|
| 161 | - * @param string $name Case-insensitive header field name to remove. |
|
| 162 | - * @return static |
|
| 163 | - */ |
|
| 164 | - public function withoutHeader(string $name): MessageInterface; |
|
| 152 | + /** |
|
| 153 | + * Return an instance without the specified header. |
|
| 154 | + * |
|
| 155 | + * Header resolution MUST be done without case-sensitivity. |
|
| 156 | + * |
|
| 157 | + * This method MUST be implemented in such a way as to retain the |
|
| 158 | + * immutability of the message, and MUST return an instance that removes |
|
| 159 | + * the named header. |
|
| 160 | + * |
|
| 161 | + * @param string $name Case-insensitive header field name to remove. |
|
| 162 | + * @return static |
|
| 163 | + */ |
|
| 164 | + public function withoutHeader(string $name): MessageInterface; |
|
| 165 | 165 | |
| 166 | - /** |
|
| 167 | - * Gets the body of the message. |
|
| 168 | - * |
|
| 169 | - * @return StreamInterface Returns the body as a stream. |
|
| 170 | - */ |
|
| 171 | - public function getBody(): StreamInterface; |
|
| 166 | + /** |
|
| 167 | + * Gets the body of the message. |
|
| 168 | + * |
|
| 169 | + * @return StreamInterface Returns the body as a stream. |
|
| 170 | + */ |
|
| 171 | + public function getBody(): StreamInterface; |
|
| 172 | 172 | |
| 173 | - /** |
|
| 174 | - * Return an instance with the specified message body. |
|
| 175 | - * |
|
| 176 | - * The body MUST be a StreamInterface object. |
|
| 177 | - * |
|
| 178 | - * This method MUST be implemented in such a way as to retain the |
|
| 179 | - * immutability of the message, and MUST return a new instance that has the |
|
| 180 | - * new body stream. |
|
| 181 | - * |
|
| 182 | - * @param StreamInterface $body Body. |
|
| 183 | - * @return static |
|
| 184 | - * @throws \InvalidArgumentException When the body is not valid. |
|
| 185 | - */ |
|
| 186 | - public function withBody(StreamInterface $body): MessageInterface; |
|
| 173 | + /** |
|
| 174 | + * Return an instance with the specified message body. |
|
| 175 | + * |
|
| 176 | + * The body MUST be a StreamInterface object. |
|
| 177 | + * |
|
| 178 | + * This method MUST be implemented in such a way as to retain the |
|
| 179 | + * immutability of the message, and MUST return a new instance that has the |
|
| 180 | + * new body stream. |
|
| 181 | + * |
|
| 182 | + * @param StreamInterface $body Body. |
|
| 183 | + * @return static |
|
| 184 | + * @throws \InvalidArgumentException When the body is not valid. |
|
| 185 | + */ |
|
| 186 | + public function withBody(StreamInterface $body): MessageInterface; |
|
| 187 | 187 | } |
@@ -14,8 +14,7 @@ |
||
| 14 | 14 | * @link http://www.ietf.org/rfc/rfc7230.txt |
| 15 | 15 | * @link http://www.ietf.org/rfc/rfc7231.txt |
| 16 | 16 | */ |
| 17 | -interface MessageInterface |
|
| 18 | -{ |
|
| 17 | +interface MessageInterface { |
|
| 19 | 18 | /** |
| 20 | 19 | * Retrieves the HTTP protocol version as a string. |
| 21 | 20 | * |
@@ -23,108 +23,108 @@ |
||
| 23 | 23 | */ |
| 24 | 24 | interface RequestInterface extends MessageInterface |
| 25 | 25 | { |
| 26 | - /** |
|
| 27 | - * Retrieves the message's request target. |
|
| 28 | - * |
|
| 29 | - * Retrieves the message's request-target either as it will appear (for |
|
| 30 | - * clients), as it appeared at request (for servers), or as it was |
|
| 31 | - * specified for the instance (see withRequestTarget()). |
|
| 32 | - * |
|
| 33 | - * In most cases, this will be the origin-form of the composed URI, |
|
| 34 | - * unless a value was provided to the concrete implementation (see |
|
| 35 | - * withRequestTarget() below). |
|
| 36 | - * |
|
| 37 | - * If no URI is available, and no request-target has been specifically |
|
| 38 | - * provided, this method MUST return the string "/". |
|
| 39 | - * |
|
| 40 | - * @return string |
|
| 41 | - */ |
|
| 42 | - public function getRequestTarget(): string; |
|
| 26 | + /** |
|
| 27 | + * Retrieves the message's request target. |
|
| 28 | + * |
|
| 29 | + * Retrieves the message's request-target either as it will appear (for |
|
| 30 | + * clients), as it appeared at request (for servers), or as it was |
|
| 31 | + * specified for the instance (see withRequestTarget()). |
|
| 32 | + * |
|
| 33 | + * In most cases, this will be the origin-form of the composed URI, |
|
| 34 | + * unless a value was provided to the concrete implementation (see |
|
| 35 | + * withRequestTarget() below). |
|
| 36 | + * |
|
| 37 | + * If no URI is available, and no request-target has been specifically |
|
| 38 | + * provided, this method MUST return the string "/". |
|
| 39 | + * |
|
| 40 | + * @return string |
|
| 41 | + */ |
|
| 42 | + public function getRequestTarget(): string; |
|
| 43 | 43 | |
| 44 | - /** |
|
| 45 | - * Return an instance with the specific request-target. |
|
| 46 | - * |
|
| 47 | - * If the request needs a non-origin-form request-target — e.g., for |
|
| 48 | - * specifying an absolute-form, authority-form, or asterisk-form — |
|
| 49 | - * this method may be used to create an instance with the specified |
|
| 50 | - * request-target, verbatim. |
|
| 51 | - * |
|
| 52 | - * This method MUST be implemented in such a way as to retain the |
|
| 53 | - * immutability of the message, and MUST return an instance that has the |
|
| 54 | - * changed request target. |
|
| 55 | - * |
|
| 56 | - * @link http://tools.ietf.org/html/rfc7230#section-5.3 (for the various |
|
| 57 | - * request-target forms allowed in request messages) |
|
| 58 | - * @param string $requestTarget |
|
| 59 | - * @return static |
|
| 60 | - */ |
|
| 61 | - public function withRequestTarget(string $requestTarget): RequestInterface; |
|
| 44 | + /** |
|
| 45 | + * Return an instance with the specific request-target. |
|
| 46 | + * |
|
| 47 | + * If the request needs a non-origin-form request-target — e.g., for |
|
| 48 | + * specifying an absolute-form, authority-form, or asterisk-form — |
|
| 49 | + * this method may be used to create an instance with the specified |
|
| 50 | + * request-target, verbatim. |
|
| 51 | + * |
|
| 52 | + * This method MUST be implemented in such a way as to retain the |
|
| 53 | + * immutability of the message, and MUST return an instance that has the |
|
| 54 | + * changed request target. |
|
| 55 | + * |
|
| 56 | + * @link http://tools.ietf.org/html/rfc7230#section-5.3 (for the various |
|
| 57 | + * request-target forms allowed in request messages) |
|
| 58 | + * @param string $requestTarget |
|
| 59 | + * @return static |
|
| 60 | + */ |
|
| 61 | + public function withRequestTarget(string $requestTarget): RequestInterface; |
|
| 62 | 62 | |
| 63 | 63 | |
| 64 | - /** |
|
| 65 | - * Retrieves the HTTP method of the request. |
|
| 66 | - * |
|
| 67 | - * @return string Returns the request method. |
|
| 68 | - */ |
|
| 69 | - public function getMethod(): string; |
|
| 64 | + /** |
|
| 65 | + * Retrieves the HTTP method of the request. |
|
| 66 | + * |
|
| 67 | + * @return string Returns the request method. |
|
| 68 | + */ |
|
| 69 | + public function getMethod(): string; |
|
| 70 | 70 | |
| 71 | - /** |
|
| 72 | - * Return an instance with the provided HTTP method. |
|
| 73 | - * |
|
| 74 | - * While HTTP method names are typically all uppercase characters, HTTP |
|
| 75 | - * method names are case-sensitive and thus implementations SHOULD NOT |
|
| 76 | - * modify the given string. |
|
| 77 | - * |
|
| 78 | - * This method MUST be implemented in such a way as to retain the |
|
| 79 | - * immutability of the message, and MUST return an instance that has the |
|
| 80 | - * changed request method. |
|
| 81 | - * |
|
| 82 | - * @param string $method Case-sensitive method. |
|
| 83 | - * @return static |
|
| 84 | - * @throws \InvalidArgumentException for invalid HTTP methods. |
|
| 85 | - */ |
|
| 86 | - public function withMethod(string $method): RequestInterface; |
|
| 71 | + /** |
|
| 72 | + * Return an instance with the provided HTTP method. |
|
| 73 | + * |
|
| 74 | + * While HTTP method names are typically all uppercase characters, HTTP |
|
| 75 | + * method names are case-sensitive and thus implementations SHOULD NOT |
|
| 76 | + * modify the given string. |
|
| 77 | + * |
|
| 78 | + * This method MUST be implemented in such a way as to retain the |
|
| 79 | + * immutability of the message, and MUST return an instance that has the |
|
| 80 | + * changed request method. |
|
| 81 | + * |
|
| 82 | + * @param string $method Case-sensitive method. |
|
| 83 | + * @return static |
|
| 84 | + * @throws \InvalidArgumentException for invalid HTTP methods. |
|
| 85 | + */ |
|
| 86 | + public function withMethod(string $method): RequestInterface; |
|
| 87 | 87 | |
| 88 | - /** |
|
| 89 | - * Retrieves the URI instance. |
|
| 90 | - * |
|
| 91 | - * This method MUST return a UriInterface instance. |
|
| 92 | - * |
|
| 93 | - * @link http://tools.ietf.org/html/rfc3986#section-4.3 |
|
| 94 | - * @return UriInterface Returns a UriInterface instance |
|
| 95 | - * representing the URI of the request. |
|
| 96 | - */ |
|
| 97 | - public function getUri(): UriInterface; |
|
| 88 | + /** |
|
| 89 | + * Retrieves the URI instance. |
|
| 90 | + * |
|
| 91 | + * This method MUST return a UriInterface instance. |
|
| 92 | + * |
|
| 93 | + * @link http://tools.ietf.org/html/rfc3986#section-4.3 |
|
| 94 | + * @return UriInterface Returns a UriInterface instance |
|
| 95 | + * representing the URI of the request. |
|
| 96 | + */ |
|
| 97 | + public function getUri(): UriInterface; |
|
| 98 | 98 | |
| 99 | - /** |
|
| 100 | - * Returns an instance with the provided URI. |
|
| 101 | - * |
|
| 102 | - * This method MUST update the Host header of the returned request by |
|
| 103 | - * default if the URI contains a host component. If the URI does not |
|
| 104 | - * contain a host component, any pre-existing Host header MUST be carried |
|
| 105 | - * over to the returned request. |
|
| 106 | - * |
|
| 107 | - * You can opt-in to preserving the original state of the Host header by |
|
| 108 | - * setting `$preserveHost` to `true`. When `$preserveHost` is set to |
|
| 109 | - * `true`, this method interacts with the Host header in the following ways: |
|
| 110 | - * |
|
| 111 | - * - If the Host header is missing or empty, and the new URI contains |
|
| 112 | - * a host component, this method MUST update the Host header in the returned |
|
| 113 | - * request. |
|
| 114 | - * - If the Host header is missing or empty, and the new URI does not contain a |
|
| 115 | - * host component, this method MUST NOT update the Host header in the returned |
|
| 116 | - * request. |
|
| 117 | - * - If a Host header is present and non-empty, this method MUST NOT update |
|
| 118 | - * the Host header in the returned request. |
|
| 119 | - * |
|
| 120 | - * This method MUST be implemented in such a way as to retain the |
|
| 121 | - * immutability of the message, and MUST return an instance that has the |
|
| 122 | - * new UriInterface instance. |
|
| 123 | - * |
|
| 124 | - * @link http://tools.ietf.org/html/rfc3986#section-4.3 |
|
| 125 | - * @param UriInterface $uri New request URI to use. |
|
| 126 | - * @param bool $preserveHost Preserve the original state of the Host header. |
|
| 127 | - * @return static |
|
| 128 | - */ |
|
| 129 | - public function withUri(UriInterface $uri, bool $preserveHost = false): RequestInterface; |
|
| 99 | + /** |
|
| 100 | + * Returns an instance with the provided URI. |
|
| 101 | + * |
|
| 102 | + * This method MUST update the Host header of the returned request by |
|
| 103 | + * default if the URI contains a host component. If the URI does not |
|
| 104 | + * contain a host component, any pre-existing Host header MUST be carried |
|
| 105 | + * over to the returned request. |
|
| 106 | + * |
|
| 107 | + * You can opt-in to preserving the original state of the Host header by |
|
| 108 | + * setting `$preserveHost` to `true`. When `$preserveHost` is set to |
|
| 109 | + * `true`, this method interacts with the Host header in the following ways: |
|
| 110 | + * |
|
| 111 | + * - If the Host header is missing or empty, and the new URI contains |
|
| 112 | + * a host component, this method MUST update the Host header in the returned |
|
| 113 | + * request. |
|
| 114 | + * - If the Host header is missing or empty, and the new URI does not contain a |
|
| 115 | + * host component, this method MUST NOT update the Host header in the returned |
|
| 116 | + * request. |
|
| 117 | + * - If a Host header is present and non-empty, this method MUST NOT update |
|
| 118 | + * the Host header in the returned request. |
|
| 119 | + * |
|
| 120 | + * This method MUST be implemented in such a way as to retain the |
|
| 121 | + * immutability of the message, and MUST return an instance that has the |
|
| 122 | + * new UriInterface instance. |
|
| 123 | + * |
|
| 124 | + * @link http://tools.ietf.org/html/rfc3986#section-4.3 |
|
| 125 | + * @param UriInterface $uri New request URI to use. |
|
| 126 | + * @param bool $preserveHost Preserve the original state of the Host header. |
|
| 127 | + * @return static |
|
| 128 | + */ |
|
| 129 | + public function withUri(UriInterface $uri, bool $preserveHost = false): RequestInterface; |
|
| 130 | 130 | } |
@@ -21,8 +21,7 @@ |
||
| 21 | 21 | * be implemented such that they retain the internal state of the current |
| 22 | 22 | * message and return an instance that contains the changed state. |
| 23 | 23 | */ |
| 24 | -interface RequestInterface extends MessageInterface |
|
| 25 | -{ |
|
| 24 | +interface RequestInterface extends MessageInterface { |
|
| 26 | 25 | /** |
| 27 | 26 | * Retrieves the message's request target. |
| 28 | 27 | * |
@@ -12,112 +12,112 @@ |
||
| 12 | 12 | */ |
| 13 | 13 | interface UploadedFileInterface |
| 14 | 14 | { |
| 15 | - /** |
|
| 16 | - * Retrieve a stream representing the uploaded file. |
|
| 17 | - * |
|
| 18 | - * This method MUST return a StreamInterface instance, representing the |
|
| 19 | - * uploaded file. The purpose of this method is to allow utilizing native PHP |
|
| 20 | - * stream functionality to manipulate the file upload, such as |
|
| 21 | - * stream_copy_to_stream() (though the result will need to be decorated in a |
|
| 22 | - * native PHP stream wrapper to work with such functions). |
|
| 23 | - * |
|
| 24 | - * If the moveTo() method has been called previously, this method MUST raise |
|
| 25 | - * an exception. |
|
| 26 | - * |
|
| 27 | - * @return StreamInterface Stream representation of the uploaded file. |
|
| 28 | - * @throws \RuntimeException in cases when no stream is available or can be |
|
| 29 | - * created. |
|
| 30 | - */ |
|
| 31 | - public function getStream(): StreamInterface; |
|
| 15 | + /** |
|
| 16 | + * Retrieve a stream representing the uploaded file. |
|
| 17 | + * |
|
| 18 | + * This method MUST return a StreamInterface instance, representing the |
|
| 19 | + * uploaded file. The purpose of this method is to allow utilizing native PHP |
|
| 20 | + * stream functionality to manipulate the file upload, such as |
|
| 21 | + * stream_copy_to_stream() (though the result will need to be decorated in a |
|
| 22 | + * native PHP stream wrapper to work with such functions). |
|
| 23 | + * |
|
| 24 | + * If the moveTo() method has been called previously, this method MUST raise |
|
| 25 | + * an exception. |
|
| 26 | + * |
|
| 27 | + * @return StreamInterface Stream representation of the uploaded file. |
|
| 28 | + * @throws \RuntimeException in cases when no stream is available or can be |
|
| 29 | + * created. |
|
| 30 | + */ |
|
| 31 | + public function getStream(): StreamInterface; |
|
| 32 | 32 | |
| 33 | - /** |
|
| 34 | - * Move the uploaded file to a new location. |
|
| 35 | - * |
|
| 36 | - * Use this method as an alternative to move_uploaded_file(). This method is |
|
| 37 | - * guaranteed to work in both SAPI and non-SAPI environments. |
|
| 38 | - * Implementations must determine which environment they are in, and use the |
|
| 39 | - * appropriate method (move_uploaded_file(), rename(), or a stream |
|
| 40 | - * operation) to perform the operation. |
|
| 41 | - * |
|
| 42 | - * $targetPath may be an absolute path, or a relative path. If it is a |
|
| 43 | - * relative path, resolution should be the same as used by PHP's rename() |
|
| 44 | - * function. |
|
| 45 | - * |
|
| 46 | - * The original file or stream MUST be removed on completion. |
|
| 47 | - * |
|
| 48 | - * If this method is called more than once, any subsequent calls MUST raise |
|
| 49 | - * an exception. |
|
| 50 | - * |
|
| 51 | - * When used in an SAPI environment where $_FILES is populated, when writing |
|
| 52 | - * files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be |
|
| 53 | - * used to ensure permissions and upload status are verified correctly. |
|
| 54 | - * |
|
| 55 | - * If you wish to move to a stream, use getStream(), as SAPI operations |
|
| 56 | - * cannot guarantee writing to stream destinations. |
|
| 57 | - * |
|
| 58 | - * @see http://php.net/is_uploaded_file |
|
| 59 | - * @see http://php.net/move_uploaded_file |
|
| 60 | - * @param string $targetPath Path to which to move the uploaded file. |
|
| 61 | - * @throws \InvalidArgumentException if the $targetPath specified is invalid. |
|
| 62 | - * @throws \RuntimeException on any error during the move operation, or on |
|
| 63 | - * the second or subsequent call to the method. |
|
| 64 | - */ |
|
| 65 | - public function moveTo(string $targetPath): void; |
|
| 33 | + /** |
|
| 34 | + * Move the uploaded file to a new location. |
|
| 35 | + * |
|
| 36 | + * Use this method as an alternative to move_uploaded_file(). This method is |
|
| 37 | + * guaranteed to work in both SAPI and non-SAPI environments. |
|
| 38 | + * Implementations must determine which environment they are in, and use the |
|
| 39 | + * appropriate method (move_uploaded_file(), rename(), or a stream |
|
| 40 | + * operation) to perform the operation. |
|
| 41 | + * |
|
| 42 | + * $targetPath may be an absolute path, or a relative path. If it is a |
|
| 43 | + * relative path, resolution should be the same as used by PHP's rename() |
|
| 44 | + * function. |
|
| 45 | + * |
|
| 46 | + * The original file or stream MUST be removed on completion. |
|
| 47 | + * |
|
| 48 | + * If this method is called more than once, any subsequent calls MUST raise |
|
| 49 | + * an exception. |
|
| 50 | + * |
|
| 51 | + * When used in an SAPI environment where $_FILES is populated, when writing |
|
| 52 | + * files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be |
|
| 53 | + * used to ensure permissions and upload status are verified correctly. |
|
| 54 | + * |
|
| 55 | + * If you wish to move to a stream, use getStream(), as SAPI operations |
|
| 56 | + * cannot guarantee writing to stream destinations. |
|
| 57 | + * |
|
| 58 | + * @see http://php.net/is_uploaded_file |
|
| 59 | + * @see http://php.net/move_uploaded_file |
|
| 60 | + * @param string $targetPath Path to which to move the uploaded file. |
|
| 61 | + * @throws \InvalidArgumentException if the $targetPath specified is invalid. |
|
| 62 | + * @throws \RuntimeException on any error during the move operation, or on |
|
| 63 | + * the second or subsequent call to the method. |
|
| 64 | + */ |
|
| 65 | + public function moveTo(string $targetPath): void; |
|
| 66 | 66 | |
| 67 | - /** |
|
| 68 | - * Retrieve the file size. |
|
| 69 | - * |
|
| 70 | - * Implementations SHOULD return the value stored in the "size" key of |
|
| 71 | - * the file in the $_FILES array if available, as PHP calculates this based |
|
| 72 | - * on the actual size transmitted. |
|
| 73 | - * |
|
| 74 | - * @return int|null The file size in bytes or null if unknown. |
|
| 75 | - */ |
|
| 76 | - public function getSize(): ?int; |
|
| 67 | + /** |
|
| 68 | + * Retrieve the file size. |
|
| 69 | + * |
|
| 70 | + * Implementations SHOULD return the value stored in the "size" key of |
|
| 71 | + * the file in the $_FILES array if available, as PHP calculates this based |
|
| 72 | + * on the actual size transmitted. |
|
| 73 | + * |
|
| 74 | + * @return int|null The file size in bytes or null if unknown. |
|
| 75 | + */ |
|
| 76 | + public function getSize(): ?int; |
|
| 77 | 77 | |
| 78 | - /** |
|
| 79 | - * Retrieve the error associated with the uploaded file. |
|
| 80 | - * |
|
| 81 | - * The return value MUST be one of PHP's UPLOAD_ERR_XXX constants. |
|
| 82 | - * |
|
| 83 | - * If the file was uploaded successfully, this method MUST return |
|
| 84 | - * UPLOAD_ERR_OK. |
|
| 85 | - * |
|
| 86 | - * Implementations SHOULD return the value stored in the "error" key of |
|
| 87 | - * the file in the $_FILES array. |
|
| 88 | - * |
|
| 89 | - * @see http://php.net/manual/en/features.file-upload.errors.php |
|
| 90 | - * @return int One of PHP's UPLOAD_ERR_XXX constants. |
|
| 91 | - */ |
|
| 92 | - public function getError(): int; |
|
| 78 | + /** |
|
| 79 | + * Retrieve the error associated with the uploaded file. |
|
| 80 | + * |
|
| 81 | + * The return value MUST be one of PHP's UPLOAD_ERR_XXX constants. |
|
| 82 | + * |
|
| 83 | + * If the file was uploaded successfully, this method MUST return |
|
| 84 | + * UPLOAD_ERR_OK. |
|
| 85 | + * |
|
| 86 | + * Implementations SHOULD return the value stored in the "error" key of |
|
| 87 | + * the file in the $_FILES array. |
|
| 88 | + * |
|
| 89 | + * @see http://php.net/manual/en/features.file-upload.errors.php |
|
| 90 | + * @return int One of PHP's UPLOAD_ERR_XXX constants. |
|
| 91 | + */ |
|
| 92 | + public function getError(): int; |
|
| 93 | 93 | |
| 94 | - /** |
|
| 95 | - * Retrieve the filename sent by the client. |
|
| 96 | - * |
|
| 97 | - * Do not trust the value returned by this method. A client could send |
|
| 98 | - * a malicious filename with the intention to corrupt or hack your |
|
| 99 | - * application. |
|
| 100 | - * |
|
| 101 | - * Implementations SHOULD return the value stored in the "name" key of |
|
| 102 | - * the file in the $_FILES array. |
|
| 103 | - * |
|
| 104 | - * @return string|null The filename sent by the client or null if none |
|
| 105 | - * was provided. |
|
| 106 | - */ |
|
| 107 | - public function getClientFilename(): ?string; |
|
| 94 | + /** |
|
| 95 | + * Retrieve the filename sent by the client. |
|
| 96 | + * |
|
| 97 | + * Do not trust the value returned by this method. A client could send |
|
| 98 | + * a malicious filename with the intention to corrupt or hack your |
|
| 99 | + * application. |
|
| 100 | + * |
|
| 101 | + * Implementations SHOULD return the value stored in the "name" key of |
|
| 102 | + * the file in the $_FILES array. |
|
| 103 | + * |
|
| 104 | + * @return string|null The filename sent by the client or null if none |
|
| 105 | + * was provided. |
|
| 106 | + */ |
|
| 107 | + public function getClientFilename(): ?string; |
|
| 108 | 108 | |
| 109 | - /** |
|
| 110 | - * Retrieve the media type sent by the client. |
|
| 111 | - * |
|
| 112 | - * Do not trust the value returned by this method. A client could send |
|
| 113 | - * a malicious media type with the intention to corrupt or hack your |
|
| 114 | - * application. |
|
| 115 | - * |
|
| 116 | - * Implementations SHOULD return the value stored in the "type" key of |
|
| 117 | - * the file in the $_FILES array. |
|
| 118 | - * |
|
| 119 | - * @return string|null The media type sent by the client or null if none |
|
| 120 | - * was provided. |
|
| 121 | - */ |
|
| 122 | - public function getClientMediaType(): ?string; |
|
| 109 | + /** |
|
| 110 | + * Retrieve the media type sent by the client. |
|
| 111 | + * |
|
| 112 | + * Do not trust the value returned by this method. A client could send |
|
| 113 | + * a malicious media type with the intention to corrupt or hack your |
|
| 114 | + * application. |
|
| 115 | + * |
|
| 116 | + * Implementations SHOULD return the value stored in the "type" key of |
|
| 117 | + * the file in the $_FILES array. |
|
| 118 | + * |
|
| 119 | + * @return string|null The media type sent by the client or null if none |
|
| 120 | + * was provided. |
|
| 121 | + */ |
|
| 122 | + public function getClientMediaType(): ?string; |
|
| 123 | 123 | } |
@@ -10,8 +10,7 @@ |
||
| 10 | 10 | * state of the current instance and return an instance that contains the |
| 11 | 11 | * changed state. |
| 12 | 12 | */ |
| 13 | -interface UploadedFileInterface |
|
| 14 | -{ |
|
| 13 | +interface UploadedFileInterface { |
|
| 15 | 14 | /** |
| 16 | 15 | * Retrieve a stream representing the uploaded file. |
| 17 | 16 | * |
@@ -4,21 +4,21 @@ |
||
| 4 | 4 | |
| 5 | 5 | interface ServerRequestFactoryInterface |
| 6 | 6 | { |
| 7 | - /** |
|
| 8 | - * Create a new server request. |
|
| 9 | - * |
|
| 10 | - * Note that server-params are taken precisely as given - no parsing/processing |
|
| 11 | - * of the given values is performed, and, in particular, no attempt is made to |
|
| 12 | - * determine the HTTP method or URI, which must be provided explicitly. |
|
| 13 | - * |
|
| 14 | - * @param string $method The HTTP method associated with the request. |
|
| 15 | - * @param UriInterface|string $uri The URI associated with the request. If |
|
| 16 | - * the value is a string, the factory MUST create a UriInterface |
|
| 17 | - * instance based on it. |
|
| 18 | - * @param array $serverParams Array of SAPI parameters with which to seed |
|
| 19 | - * the generated request instance. |
|
| 20 | - * |
|
| 21 | - * @return ServerRequestInterface |
|
| 22 | - */ |
|
| 23 | - public function createServerRequest(string $method, $uri, array $serverParams = []): ServerRequestInterface; |
|
| 7 | + /** |
|
| 8 | + * Create a new server request. |
|
| 9 | + * |
|
| 10 | + * Note that server-params are taken precisely as given - no parsing/processing |
|
| 11 | + * of the given values is performed, and, in particular, no attempt is made to |
|
| 12 | + * determine the HTTP method or URI, which must be provided explicitly. |
|
| 13 | + * |
|
| 14 | + * @param string $method The HTTP method associated with the request. |
|
| 15 | + * @param UriInterface|string $uri The URI associated with the request. If |
|
| 16 | + * the value is a string, the factory MUST create a UriInterface |
|
| 17 | + * instance based on it. |
|
| 18 | + * @param array $serverParams Array of SAPI parameters with which to seed |
|
| 19 | + * the generated request instance. |
|
| 20 | + * |
|
| 21 | + * @return ServerRequestInterface |
|
| 22 | + */ |
|
| 23 | + public function createServerRequest(string $method, $uri, array $serverParams = []): ServerRequestInterface; |
|
| 24 | 24 | } |
@@ -2,8 +2,7 @@ |
||
| 2 | 2 | |
| 3 | 3 | namespace OCA\FullTextSearch_Elasticsearch\Vendor\Psr\Http\Message; |
| 4 | 4 | |
| 5 | -interface ServerRequestFactoryInterface |
|
| 6 | -{ |
|
| 5 | +interface ServerRequestFactoryInterface { |
|
| 7 | 6 | /** |
| 8 | 7 | * Create a new server request. |
| 9 | 8 | * |
@@ -19,50 +19,50 @@ |
||
| 19 | 19 | */ |
| 20 | 20 | interface ResponseInterface extends MessageInterface |
| 21 | 21 | { |
| 22 | - /** |
|
| 23 | - * Gets the response status code. |
|
| 24 | - * |
|
| 25 | - * The status code is a 3-digit integer result code of the server's attempt |
|
| 26 | - * to understand and satisfy the request. |
|
| 27 | - * |
|
| 28 | - * @return int Status code. |
|
| 29 | - */ |
|
| 30 | - public function getStatusCode(): int; |
|
| 22 | + /** |
|
| 23 | + * Gets the response status code. |
|
| 24 | + * |
|
| 25 | + * The status code is a 3-digit integer result code of the server's attempt |
|
| 26 | + * to understand and satisfy the request. |
|
| 27 | + * |
|
| 28 | + * @return int Status code. |
|
| 29 | + */ |
|
| 30 | + public function getStatusCode(): int; |
|
| 31 | 31 | |
| 32 | - /** |
|
| 33 | - * Return an instance with the specified status code and, optionally, reason phrase. |
|
| 34 | - * |
|
| 35 | - * If no reason phrase is specified, implementations MAY choose to default |
|
| 36 | - * to the RFC 7231 or IANA recommended reason phrase for the response's |
|
| 37 | - * status code. |
|
| 38 | - * |
|
| 39 | - * This method MUST be implemented in such a way as to retain the |
|
| 40 | - * immutability of the message, and MUST return an instance that has the |
|
| 41 | - * updated status and reason phrase. |
|
| 42 | - * |
|
| 43 | - * @link http://tools.ietf.org/html/rfc7231#section-6 |
|
| 44 | - * @link http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml |
|
| 45 | - * @param int $code The 3-digit integer result code to set. |
|
| 46 | - * @param string $reasonPhrase The reason phrase to use with the |
|
| 47 | - * provided status code; if none is provided, implementations MAY |
|
| 48 | - * use the defaults as suggested in the HTTP specification. |
|
| 49 | - * @return static |
|
| 50 | - * @throws \InvalidArgumentException For invalid status code arguments. |
|
| 51 | - */ |
|
| 52 | - public function withStatus(int $code, string $reasonPhrase = ''): ResponseInterface; |
|
| 32 | + /** |
|
| 33 | + * Return an instance with the specified status code and, optionally, reason phrase. |
|
| 34 | + * |
|
| 35 | + * If no reason phrase is specified, implementations MAY choose to default |
|
| 36 | + * to the RFC 7231 or IANA recommended reason phrase for the response's |
|
| 37 | + * status code. |
|
| 38 | + * |
|
| 39 | + * This method MUST be implemented in such a way as to retain the |
|
| 40 | + * immutability of the message, and MUST return an instance that has the |
|
| 41 | + * updated status and reason phrase. |
|
| 42 | + * |
|
| 43 | + * @link http://tools.ietf.org/html/rfc7231#section-6 |
|
| 44 | + * @link http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml |
|
| 45 | + * @param int $code The 3-digit integer result code to set. |
|
| 46 | + * @param string $reasonPhrase The reason phrase to use with the |
|
| 47 | + * provided status code; if none is provided, implementations MAY |
|
| 48 | + * use the defaults as suggested in the HTTP specification. |
|
| 49 | + * @return static |
|
| 50 | + * @throws \InvalidArgumentException For invalid status code arguments. |
|
| 51 | + */ |
|
| 52 | + public function withStatus(int $code, string $reasonPhrase = ''): ResponseInterface; |
|
| 53 | 53 | |
| 54 | - /** |
|
| 55 | - * Gets the response reason phrase associated with the status code. |
|
| 56 | - * |
|
| 57 | - * Because a reason phrase is not a required element in a response |
|
| 58 | - * status line, the reason phrase value MAY be null. Implementations MAY |
|
| 59 | - * choose to return the default RFC 7231 recommended reason phrase (or those |
|
| 60 | - * listed in the IANA HTTP Status Code Registry) for the response's |
|
| 61 | - * status code. |
|
| 62 | - * |
|
| 63 | - * @link http://tools.ietf.org/html/rfc7231#section-6 |
|
| 64 | - * @link http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml |
|
| 65 | - * @return string Reason phrase; must return an empty string if none present. |
|
| 66 | - */ |
|
| 67 | - public function getReasonPhrase(): string; |
|
| 54 | + /** |
|
| 55 | + * Gets the response reason phrase associated with the status code. |
|
| 56 | + * |
|
| 57 | + * Because a reason phrase is not a required element in a response |
|
| 58 | + * status line, the reason phrase value MAY be null. Implementations MAY |
|
| 59 | + * choose to return the default RFC 7231 recommended reason phrase (or those |
|
| 60 | + * listed in the IANA HTTP Status Code Registry) for the response's |
|
| 61 | + * status code. |
|
| 62 | + * |
|
| 63 | + * @link http://tools.ietf.org/html/rfc7231#section-6 |
|
| 64 | + * @link http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml |
|
| 65 | + * @return string Reason phrase; must return an empty string if none present. |
|
| 66 | + */ |
|
| 67 | + public function getReasonPhrase(): string; |
|
| 68 | 68 | } |
@@ -17,8 +17,7 @@ |
||
| 17 | 17 | * be implemented such that they retain the internal state of the current |
| 18 | 18 | * message and return an instance that contains the changed state. |
| 19 | 19 | */ |
| 20 | -interface ResponseInterface extends MessageInterface |
|
| 21 | -{ |
|
| 20 | +interface ResponseInterface extends MessageInterface { |
|
| 22 | 21 | /** |
| 23 | 22 | * Gets the response status code. |
| 24 | 23 | * |
@@ -42,220 +42,220 @@ |
||
| 42 | 42 | */ |
| 43 | 43 | interface ServerRequestInterface extends RequestInterface |
| 44 | 44 | { |
| 45 | - /** |
|
| 46 | - * Retrieve server parameters. |
|
| 47 | - * |
|
| 48 | - * Retrieves data related to the incoming request environment, |
|
| 49 | - * typically derived from PHP's $_SERVER superglobal. The data IS NOT |
|
| 50 | - * REQUIRED to originate from $_SERVER. |
|
| 51 | - * |
|
| 52 | - * @return array |
|
| 53 | - */ |
|
| 54 | - public function getServerParams(): array; |
|
| 45 | + /** |
|
| 46 | + * Retrieve server parameters. |
|
| 47 | + * |
|
| 48 | + * Retrieves data related to the incoming request environment, |
|
| 49 | + * typically derived from PHP's $_SERVER superglobal. The data IS NOT |
|
| 50 | + * REQUIRED to originate from $_SERVER. |
|
| 51 | + * |
|
| 52 | + * @return array |
|
| 53 | + */ |
|
| 54 | + public function getServerParams(): array; |
|
| 55 | 55 | |
| 56 | - /** |
|
| 57 | - * Retrieve cookies. |
|
| 58 | - * |
|
| 59 | - * Retrieves cookies sent by the client to the server. |
|
| 60 | - * |
|
| 61 | - * The data MUST be compatible with the structure of the $_COOKIE |
|
| 62 | - * superglobal. |
|
| 63 | - * |
|
| 64 | - * @return array |
|
| 65 | - */ |
|
| 66 | - public function getCookieParams(): array; |
|
| 56 | + /** |
|
| 57 | + * Retrieve cookies. |
|
| 58 | + * |
|
| 59 | + * Retrieves cookies sent by the client to the server. |
|
| 60 | + * |
|
| 61 | + * The data MUST be compatible with the structure of the $_COOKIE |
|
| 62 | + * superglobal. |
|
| 63 | + * |
|
| 64 | + * @return array |
|
| 65 | + */ |
|
| 66 | + public function getCookieParams(): array; |
|
| 67 | 67 | |
| 68 | - /** |
|
| 69 | - * Return an instance with the specified cookies. |
|
| 70 | - * |
|
| 71 | - * The data IS NOT REQUIRED to come from the $_COOKIE superglobal, but MUST |
|
| 72 | - * be compatible with the structure of $_COOKIE. Typically, this data will |
|
| 73 | - * be injected at instantiation. |
|
| 74 | - * |
|
| 75 | - * This method MUST NOT update the related Cookie header of the request |
|
| 76 | - * instance, nor related values in the server params. |
|
| 77 | - * |
|
| 78 | - * This method MUST be implemented in such a way as to retain the |
|
| 79 | - * immutability of the message, and MUST return an instance that has the |
|
| 80 | - * updated cookie values. |
|
| 81 | - * |
|
| 82 | - * @param array $cookies Array of key/value pairs representing cookies. |
|
| 83 | - * @return static |
|
| 84 | - */ |
|
| 85 | - public function withCookieParams(array $cookies): ServerRequestInterface; |
|
| 68 | + /** |
|
| 69 | + * Return an instance with the specified cookies. |
|
| 70 | + * |
|
| 71 | + * The data IS NOT REQUIRED to come from the $_COOKIE superglobal, but MUST |
|
| 72 | + * be compatible with the structure of $_COOKIE. Typically, this data will |
|
| 73 | + * be injected at instantiation. |
|
| 74 | + * |
|
| 75 | + * This method MUST NOT update the related Cookie header of the request |
|
| 76 | + * instance, nor related values in the server params. |
|
| 77 | + * |
|
| 78 | + * This method MUST be implemented in such a way as to retain the |
|
| 79 | + * immutability of the message, and MUST return an instance that has the |
|
| 80 | + * updated cookie values. |
|
| 81 | + * |
|
| 82 | + * @param array $cookies Array of key/value pairs representing cookies. |
|
| 83 | + * @return static |
|
| 84 | + */ |
|
| 85 | + public function withCookieParams(array $cookies): ServerRequestInterface; |
|
| 86 | 86 | |
| 87 | - /** |
|
| 88 | - * Retrieve query string arguments. |
|
| 89 | - * |
|
| 90 | - * Retrieves the deserialized query string arguments, if any. |
|
| 91 | - * |
|
| 92 | - * Note: the query params might not be in sync with the URI or server |
|
| 93 | - * params. If you need to ensure you are only getting the original |
|
| 94 | - * values, you may need to parse the query string from `getUri()->getQuery()` |
|
| 95 | - * or from the `QUERY_STRING` server param. |
|
| 96 | - * |
|
| 97 | - * @return array |
|
| 98 | - */ |
|
| 99 | - public function getQueryParams(): array; |
|
| 87 | + /** |
|
| 88 | + * Retrieve query string arguments. |
|
| 89 | + * |
|
| 90 | + * Retrieves the deserialized query string arguments, if any. |
|
| 91 | + * |
|
| 92 | + * Note: the query params might not be in sync with the URI or server |
|
| 93 | + * params. If you need to ensure you are only getting the original |
|
| 94 | + * values, you may need to parse the query string from `getUri()->getQuery()` |
|
| 95 | + * or from the `QUERY_STRING` server param. |
|
| 96 | + * |
|
| 97 | + * @return array |
|
| 98 | + */ |
|
| 99 | + public function getQueryParams(): array; |
|
| 100 | 100 | |
| 101 | - /** |
|
| 102 | - * Return an instance with the specified query string arguments. |
|
| 103 | - * |
|
| 104 | - * These values SHOULD remain immutable over the course of the incoming |
|
| 105 | - * request. They MAY be injected during instantiation, such as from PHP's |
|
| 106 | - * $_GET superglobal, or MAY be derived from some other value such as the |
|
| 107 | - * URI. In cases where the arguments are parsed from the URI, the data |
|
| 108 | - * MUST be compatible with what PHP's parse_str() would return for |
|
| 109 | - * purposes of how duplicate query parameters are handled, and how nested |
|
| 110 | - * sets are handled. |
|
| 111 | - * |
|
| 112 | - * Setting query string arguments MUST NOT change the URI stored by the |
|
| 113 | - * request, nor the values in the server params. |
|
| 114 | - * |
|
| 115 | - * This method MUST be implemented in such a way as to retain the |
|
| 116 | - * immutability of the message, and MUST return an instance that has the |
|
| 117 | - * updated query string arguments. |
|
| 118 | - * |
|
| 119 | - * @param array $query Array of query string arguments, typically from |
|
| 120 | - * $_GET. |
|
| 121 | - * @return static |
|
| 122 | - */ |
|
| 123 | - public function withQueryParams(array $query): ServerRequestInterface; |
|
| 101 | + /** |
|
| 102 | + * Return an instance with the specified query string arguments. |
|
| 103 | + * |
|
| 104 | + * These values SHOULD remain immutable over the course of the incoming |
|
| 105 | + * request. They MAY be injected during instantiation, such as from PHP's |
|
| 106 | + * $_GET superglobal, or MAY be derived from some other value such as the |
|
| 107 | + * URI. In cases where the arguments are parsed from the URI, the data |
|
| 108 | + * MUST be compatible with what PHP's parse_str() would return for |
|
| 109 | + * purposes of how duplicate query parameters are handled, and how nested |
|
| 110 | + * sets are handled. |
|
| 111 | + * |
|
| 112 | + * Setting query string arguments MUST NOT change the URI stored by the |
|
| 113 | + * request, nor the values in the server params. |
|
| 114 | + * |
|
| 115 | + * This method MUST be implemented in such a way as to retain the |
|
| 116 | + * immutability of the message, and MUST return an instance that has the |
|
| 117 | + * updated query string arguments. |
|
| 118 | + * |
|
| 119 | + * @param array $query Array of query string arguments, typically from |
|
| 120 | + * $_GET. |
|
| 121 | + * @return static |
|
| 122 | + */ |
|
| 123 | + public function withQueryParams(array $query): ServerRequestInterface; |
|
| 124 | 124 | |
| 125 | - /** |
|
| 126 | - * Retrieve normalized file upload data. |
|
| 127 | - * |
|
| 128 | - * This method returns upload metadata in a normalized tree, with each leaf |
|
| 129 | - * an instance of OCA\FullTextSearch_Elasticsearch\Vendor\Psr\Http\Message\UploadedFileInterface. |
|
| 130 | - * |
|
| 131 | - * These values MAY be prepared from $_FILES or the message body during |
|
| 132 | - * instantiation, or MAY be injected via withUploadedFiles(). |
|
| 133 | - * |
|
| 134 | - * @return array An array tree of UploadedFileInterface instances; an empty |
|
| 135 | - * array MUST be returned if no data is present. |
|
| 136 | - */ |
|
| 137 | - public function getUploadedFiles(): array; |
|
| 125 | + /** |
|
| 126 | + * Retrieve normalized file upload data. |
|
| 127 | + * |
|
| 128 | + * This method returns upload metadata in a normalized tree, with each leaf |
|
| 129 | + * an instance of OCA\FullTextSearch_Elasticsearch\Vendor\Psr\Http\Message\UploadedFileInterface. |
|
| 130 | + * |
|
| 131 | + * These values MAY be prepared from $_FILES or the message body during |
|
| 132 | + * instantiation, or MAY be injected via withUploadedFiles(). |
|
| 133 | + * |
|
| 134 | + * @return array An array tree of UploadedFileInterface instances; an empty |
|
| 135 | + * array MUST be returned if no data is present. |
|
| 136 | + */ |
|
| 137 | + public function getUploadedFiles(): array; |
|
| 138 | 138 | |
| 139 | - /** |
|
| 140 | - * Create a new instance with the specified uploaded files. |
|
| 141 | - * |
|
| 142 | - * This method MUST be implemented in such a way as to retain the |
|
| 143 | - * immutability of the message, and MUST return an instance that has the |
|
| 144 | - * updated body parameters. |
|
| 145 | - * |
|
| 146 | - * @param array $uploadedFiles An array tree of UploadedFileInterface instances. |
|
| 147 | - * @return static |
|
| 148 | - * @throws \InvalidArgumentException if an invalid structure is provided. |
|
| 149 | - */ |
|
| 150 | - public function withUploadedFiles(array $uploadedFiles): ServerRequestInterface; |
|
| 139 | + /** |
|
| 140 | + * Create a new instance with the specified uploaded files. |
|
| 141 | + * |
|
| 142 | + * This method MUST be implemented in such a way as to retain the |
|
| 143 | + * immutability of the message, and MUST return an instance that has the |
|
| 144 | + * updated body parameters. |
|
| 145 | + * |
|
| 146 | + * @param array $uploadedFiles An array tree of UploadedFileInterface instances. |
|
| 147 | + * @return static |
|
| 148 | + * @throws \InvalidArgumentException if an invalid structure is provided. |
|
| 149 | + */ |
|
| 150 | + public function withUploadedFiles(array $uploadedFiles): ServerRequestInterface; |
|
| 151 | 151 | |
| 152 | - /** |
|
| 153 | - * Retrieve any parameters provided in the request body. |
|
| 154 | - * |
|
| 155 | - * If the request Content-Type is either application/x-www-form-urlencoded |
|
| 156 | - * or multipart/form-data, and the request method is POST, this method MUST |
|
| 157 | - * return the contents of $_POST. |
|
| 158 | - * |
|
| 159 | - * Otherwise, this method may return any results of deserializing |
|
| 160 | - * the request body content; as parsing returns structured content, the |
|
| 161 | - * potential types MUST be arrays or objects only. A null value indicates |
|
| 162 | - * the absence of body content. |
|
| 163 | - * |
|
| 164 | - * @return null|array|object The deserialized body parameters, if any. |
|
| 165 | - * These will typically be an array or object. |
|
| 166 | - */ |
|
| 167 | - public function getParsedBody(); |
|
| 152 | + /** |
|
| 153 | + * Retrieve any parameters provided in the request body. |
|
| 154 | + * |
|
| 155 | + * If the request Content-Type is either application/x-www-form-urlencoded |
|
| 156 | + * or multipart/form-data, and the request method is POST, this method MUST |
|
| 157 | + * return the contents of $_POST. |
|
| 158 | + * |
|
| 159 | + * Otherwise, this method may return any results of deserializing |
|
| 160 | + * the request body content; as parsing returns structured content, the |
|
| 161 | + * potential types MUST be arrays or objects only. A null value indicates |
|
| 162 | + * the absence of body content. |
|
| 163 | + * |
|
| 164 | + * @return null|array|object The deserialized body parameters, if any. |
|
| 165 | + * These will typically be an array or object. |
|
| 166 | + */ |
|
| 167 | + public function getParsedBody(); |
|
| 168 | 168 | |
| 169 | - /** |
|
| 170 | - * Return an instance with the specified body parameters. |
|
| 171 | - * |
|
| 172 | - * These MAY be injected during instantiation. |
|
| 173 | - * |
|
| 174 | - * If the request Content-Type is either application/x-www-form-urlencoded |
|
| 175 | - * or multipart/form-data, and the request method is POST, use this method |
|
| 176 | - * ONLY to inject the contents of $_POST. |
|
| 177 | - * |
|
| 178 | - * The data IS NOT REQUIRED to come from $_POST, but MUST be the results of |
|
| 179 | - * deserializing the request body content. Deserialization/parsing returns |
|
| 180 | - * structured data, and, as such, this method ONLY accepts arrays or objects, |
|
| 181 | - * or a null value if nothing was available to parse. |
|
| 182 | - * |
|
| 183 | - * As an example, if content negotiation determines that the request data |
|
| 184 | - * is a JSON payload, this method could be used to create a request |
|
| 185 | - * instance with the deserialized parameters. |
|
| 186 | - * |
|
| 187 | - * This method MUST be implemented in such a way as to retain the |
|
| 188 | - * immutability of the message, and MUST return an instance that has the |
|
| 189 | - * updated body parameters. |
|
| 190 | - * |
|
| 191 | - * @param null|array|object $data The deserialized body data. This will |
|
| 192 | - * typically be in an array or object. |
|
| 193 | - * @return static |
|
| 194 | - * @throws \InvalidArgumentException if an unsupported argument type is |
|
| 195 | - * provided. |
|
| 196 | - */ |
|
| 197 | - public function withParsedBody($data): ServerRequestInterface; |
|
| 169 | + /** |
|
| 170 | + * Return an instance with the specified body parameters. |
|
| 171 | + * |
|
| 172 | + * These MAY be injected during instantiation. |
|
| 173 | + * |
|
| 174 | + * If the request Content-Type is either application/x-www-form-urlencoded |
|
| 175 | + * or multipart/form-data, and the request method is POST, use this method |
|
| 176 | + * ONLY to inject the contents of $_POST. |
|
| 177 | + * |
|
| 178 | + * The data IS NOT REQUIRED to come from $_POST, but MUST be the results of |
|
| 179 | + * deserializing the request body content. Deserialization/parsing returns |
|
| 180 | + * structured data, and, as such, this method ONLY accepts arrays or objects, |
|
| 181 | + * or a null value if nothing was available to parse. |
|
| 182 | + * |
|
| 183 | + * As an example, if content negotiation determines that the request data |
|
| 184 | + * is a JSON payload, this method could be used to create a request |
|
| 185 | + * instance with the deserialized parameters. |
|
| 186 | + * |
|
| 187 | + * This method MUST be implemented in such a way as to retain the |
|
| 188 | + * immutability of the message, and MUST return an instance that has the |
|
| 189 | + * updated body parameters. |
|
| 190 | + * |
|
| 191 | + * @param null|array|object $data The deserialized body data. This will |
|
| 192 | + * typically be in an array or object. |
|
| 193 | + * @return static |
|
| 194 | + * @throws \InvalidArgumentException if an unsupported argument type is |
|
| 195 | + * provided. |
|
| 196 | + */ |
|
| 197 | + public function withParsedBody($data): ServerRequestInterface; |
|
| 198 | 198 | |
| 199 | - /** |
|
| 200 | - * Retrieve attributes derived from the request. |
|
| 201 | - * |
|
| 202 | - * The request "attributes" may be used to allow injection of any |
|
| 203 | - * parameters derived from the request: e.g., the results of path |
|
| 204 | - * match operations; the results of decrypting cookies; the results of |
|
| 205 | - * deserializing non-form-encoded message bodies; etc. Attributes |
|
| 206 | - * will be application and request specific, and CAN be mutable. |
|
| 207 | - * |
|
| 208 | - * @return array Attributes derived from the request. |
|
| 209 | - */ |
|
| 210 | - public function getAttributes(): array; |
|
| 199 | + /** |
|
| 200 | + * Retrieve attributes derived from the request. |
|
| 201 | + * |
|
| 202 | + * The request "attributes" may be used to allow injection of any |
|
| 203 | + * parameters derived from the request: e.g., the results of path |
|
| 204 | + * match operations; the results of decrypting cookies; the results of |
|
| 205 | + * deserializing non-form-encoded message bodies; etc. Attributes |
|
| 206 | + * will be application and request specific, and CAN be mutable. |
|
| 207 | + * |
|
| 208 | + * @return array Attributes derived from the request. |
|
| 209 | + */ |
|
| 210 | + public function getAttributes(): array; |
|
| 211 | 211 | |
| 212 | - /** |
|
| 213 | - * Retrieve a single derived request attribute. |
|
| 214 | - * |
|
| 215 | - * Retrieves a single derived request attribute as described in |
|
| 216 | - * getAttributes(). If the attribute has not been previously set, returns |
|
| 217 | - * the default value as provided. |
|
| 218 | - * |
|
| 219 | - * This method obviates the need for a hasAttribute() method, as it allows |
|
| 220 | - * specifying a default value to return if the attribute is not found. |
|
| 221 | - * |
|
| 222 | - * @see getAttributes() |
|
| 223 | - * @param string $name The attribute name. |
|
| 224 | - * @param mixed $default Default value to return if the attribute does not exist. |
|
| 225 | - * @return mixed |
|
| 226 | - */ |
|
| 227 | - public function getAttribute(string $name, $default = null); |
|
| 212 | + /** |
|
| 213 | + * Retrieve a single derived request attribute. |
|
| 214 | + * |
|
| 215 | + * Retrieves a single derived request attribute as described in |
|
| 216 | + * getAttributes(). If the attribute has not been previously set, returns |
|
| 217 | + * the default value as provided. |
|
| 218 | + * |
|
| 219 | + * This method obviates the need for a hasAttribute() method, as it allows |
|
| 220 | + * specifying a default value to return if the attribute is not found. |
|
| 221 | + * |
|
| 222 | + * @see getAttributes() |
|
| 223 | + * @param string $name The attribute name. |
|
| 224 | + * @param mixed $default Default value to return if the attribute does not exist. |
|
| 225 | + * @return mixed |
|
| 226 | + */ |
|
| 227 | + public function getAttribute(string $name, $default = null); |
|
| 228 | 228 | |
| 229 | - /** |
|
| 230 | - * Return an instance with the specified derived request attribute. |
|
| 231 | - * |
|
| 232 | - * This method allows setting a single derived request attribute as |
|
| 233 | - * described in getAttributes(). |
|
| 234 | - * |
|
| 235 | - * This method MUST be implemented in such a way as to retain the |
|
| 236 | - * immutability of the message, and MUST return an instance that has the |
|
| 237 | - * updated attribute. |
|
| 238 | - * |
|
| 239 | - * @see getAttributes() |
|
| 240 | - * @param string $name The attribute name. |
|
| 241 | - * @param mixed $value The value of the attribute. |
|
| 242 | - * @return static |
|
| 243 | - */ |
|
| 244 | - public function withAttribute(string $name, $value): ServerRequestInterface; |
|
| 229 | + /** |
|
| 230 | + * Return an instance with the specified derived request attribute. |
|
| 231 | + * |
|
| 232 | + * This method allows setting a single derived request attribute as |
|
| 233 | + * described in getAttributes(). |
|
| 234 | + * |
|
| 235 | + * This method MUST be implemented in such a way as to retain the |
|
| 236 | + * immutability of the message, and MUST return an instance that has the |
|
| 237 | + * updated attribute. |
|
| 238 | + * |
|
| 239 | + * @see getAttributes() |
|
| 240 | + * @param string $name The attribute name. |
|
| 241 | + * @param mixed $value The value of the attribute. |
|
| 242 | + * @return static |
|
| 243 | + */ |
|
| 244 | + public function withAttribute(string $name, $value): ServerRequestInterface; |
|
| 245 | 245 | |
| 246 | - /** |
|
| 247 | - * Return an instance that removes the specified derived request attribute. |
|
| 248 | - * |
|
| 249 | - * This method allows removing a single derived request attribute as |
|
| 250 | - * described in getAttributes(). |
|
| 251 | - * |
|
| 252 | - * This method MUST be implemented in such a way as to retain the |
|
| 253 | - * immutability of the message, and MUST return an instance that removes |
|
| 254 | - * the attribute. |
|
| 255 | - * |
|
| 256 | - * @see getAttributes() |
|
| 257 | - * @param string $name The attribute name. |
|
| 258 | - * @return static |
|
| 259 | - */ |
|
| 260 | - public function withoutAttribute(string $name): ServerRequestInterface; |
|
| 246 | + /** |
|
| 247 | + * Return an instance that removes the specified derived request attribute. |
|
| 248 | + * |
|
| 249 | + * This method allows removing a single derived request attribute as |
|
| 250 | + * described in getAttributes(). |
|
| 251 | + * |
|
| 252 | + * This method MUST be implemented in such a way as to retain the |
|
| 253 | + * immutability of the message, and MUST return an instance that removes |
|
| 254 | + * the attribute. |
|
| 255 | + * |
|
| 256 | + * @see getAttributes() |
|
| 257 | + * @param string $name The attribute name. |
|
| 258 | + * @return static |
|
| 259 | + */ |
|
| 260 | + public function withoutAttribute(string $name): ServerRequestInterface; |
|
| 261 | 261 | } |
@@ -40,8 +40,7 @@ |
||
| 40 | 40 | * be implemented such that they retain the internal state of the current |
| 41 | 41 | * message and return an instance that contains the changed state. |
| 42 | 42 | */ |
| 43 | -interface ServerRequestInterface extends RequestInterface |
|
| 44 | -{ |
|
| 43 | +interface ServerRequestInterface extends RequestInterface { |
|
| 45 | 44 | /** |
| 46 | 45 | * Retrieve server parameters. |
| 47 | 46 | * |