From 68f815ae8f55ebc33f88a9e630c456595c7e935b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Demonchaux?= Date: Fri, 18 Oct 2024 09:35:07 +0200 Subject: [PATCH] #85 : md lint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Stéphane Demonchaux --- docs/book/client/cookies.md | 6 +- docs/book/headers.md | 106 ++++++++++++++++++------------------ docs/book/intro.md | 10 ++-- docs/book/request.md | 14 ++--- docs/book/response.md | 4 +- 5 files changed, 70 insertions(+), 70 deletions(-) diff --git a/docs/book/client/cookies.md b/docs/book/client/cookies.md index f573cefb..cc9e2e2f 100644 --- a/docs/book/client/cookies.md +++ b/docs/book/client/cookies.md @@ -102,10 +102,10 @@ Besides the methods demonstrated in the examples, `Laminas\Http\Cookies` defines Method signature | Description ------------------------------------------------------------------- | ----------- `static fromResponse(Response $response, string $refUri) : Cookies` | Create a `Cookies` instance from a response and the request URI. Parses all `Set-Cookie` headers, maps them to the URI, and aggregates them. -`addCookie(string|SetCookie $cookie, string $refUri = null) : void` | Add a cookie, mapping it to the given URI. If no URI is provided, it will be inferred from the cookie value's domain and path. +`addCookie(string\|SetCookie $cookie, string $refUri = null) : void` | Add a cookie, mapping it to the given URI. If no URI is provided, it will be inferred from the cookie value's domain and path. `addCookiesFromResponse(Response $response, string $refUri) : void` | Add all `Set-Cookie` values from the provided response, mapping to the given URI. -`getAllCookies(int $retAs = self::COOKIE_OBJECT) : array|string` | Retrieve all cookies. Returned array will have either `SetCookie` instances (the default), strings for each `Set-Cookie` declaration, or a single string containing all declarations, based on the `COOKIE_*` constant used. -`getCookie(/* ... */) : string|SetCookie` | Retrieve a single cookie by name for the given URI. See below for argument details. +`getAllCookies(int $retAs = self::COOKIE_OBJECT) : array\|string` | Retrieve all cookies. Returned array will have either `SetCookie` instances (the default), strings for each `Set-Cookie` declaration, or a single string containing all declarations, based on the `COOKIE_*` constant used. +`getCookie(/*...*/) : string\|SetCookie` | Retrieve a single cookie by name for the given URI. See below for argument details. `getMatchingCookies(/* ... */) : array` | See below for details. `isEmpty() : bool` | Whether or not the instance aggregates any cookies currently. `reset() : void` | Clear all aggregated cookies from the instance. diff --git a/docs/book/headers.md b/docs/book/headers.md index 0b3ffa5f..246d9e58 100644 --- a/docs/book/headers.md +++ b/docs/book/headers.md @@ -64,27 +64,27 @@ brevity, we map the following references to the following classes or namespaces: - `Headers`: `Laminas\Http\Headers` - `PluginClassLocator`: `Laminas\Loader\PluginClassLocator` -Method signature | Description -------------------------------------------------------------------------- | ----------- -`static fromString(string $string) : Headers` | Parses a string for headers, and aggregates them, in order, a new `Headers` instance, primarily as strings until they are needed (they will be lazy loaded). -`setPluginClassLoader(PluginClassLocator $pluginClassLoader) : self` | Set an alternate implementation for the plugin class loader. -`getPluginClassLoader() : PluginClassLocator` | Return an instance of a `PluginClassLocator`; lazy-load and inject map if necessary. -`addHeaders(array|Traversable $headers) : self` | Add many headers at once; expects an array (or `Traversable` object) of type/value pairs. -`addHeaderLine(string $headerFieldNameOrLine, string $fieldValue) : self` | Add a raw header line, either as separate name and value arguments, or as a single string in the form `name: value` This method allows for lazy-loading in that the parsing and instantiation of a `HeaderInterface` implementation will be delayed until they are retrieved by either `get()` or `current()`. -`addHeader(HeaderInterface $header) : self` | Add a header instance to the container; for raw values see `addHeaderLine()` and `addHeaders()`. -`removeHeader(HeaderInterface $header) : bool` | Remove a Header from the container. -`clearHeaders() : self` | Removes all headers from the container. -`get(string $name) : false|HeaderInterface|ArrayIterator` | Get all values for a given header. If none are found, `false` is returned. If the header is a single-value header, a `HeaderInterface` is returned. If the header is a multi-value header, an `ArrayIterator` containing all values is returned. -`has(string $name) : bool` | Test for existence of a header. -`next() : void` | Advance the pointer for this object as an iterator. -`key() : mixed` | Return the current key for this object as an iterator. -`valid() : bool` | Is this iterator still valid? -`rewind() : void` | Reset the internal pointer for this object as an iterator. -`current() : HeaderInterface` | Return the current value for this iterator, lazy loading it if need be. -`count() : int` | Return the number of headers in this container. If all headers have not been parsed, the actual count could decrease if `MultipleHeader` instances exist. If you need an exact count, iterate. -`toString() : string` | Render all headers at once. This method handles the normal iteration of headers; it is up to the concrete classes to prepend with the appropriate status/request line. -`toArray() : array` | Return all headers as an associative array. -`forceLoading() : bool` | By calling this, it will force parsing and loading of all headers, ensuring `count()` is accurate. + Method signature | Description +---------------------------------------------------------------------------| ----------- + `static fromString(string $string) : Headers` | Parses a string for headers, and aggregates them, in order, a new `Headers` instance, primarily as strings until they are needed (they will be lazy loaded). + `setPluginClassLoader(PluginClassLocator $pluginClassLoader) : self` | Set an alternate implementation for the plugin class loader. + `getPluginClassLoader() : PluginClassLocator` | Return an instance of a `PluginClassLocator`; lazy-load and inject map if necessary. + `addHeaders(array\|Traversable $headers) : self` | Add many headers at once; expects an array (or `Traversable` object) of type/value pairs. + `addHeaderLine(string $headerFieldNameOrLine, string $fieldValue) : self` | Add a raw header line, either as separate name and value arguments, or as a single string in the form `name: value` This method allows for lazy-loading in that the parsing and instantiation of a `HeaderInterface` implementation will be delayed until they are retrieved by either `get()` or `current()`. + `addHeader(HeaderInterface $header) : self` | Add a header instance to the container; for raw values see `addHeaderLine()` and `addHeaders()`. + `removeHeader(HeaderInterface $header) : bool` | Remove a Header from the container. + `clearHeaders() : self` | Removes all headers from the container. + `get(string $name) : false\|HeaderInterface\|ArrayIterator` | Get all values for a given header. If none are found, `false` is returned. If the header is a single-value header, a `HeaderInterface` is returned. If the header is a multi-value header, an `ArrayIterator` containing all values is returned. + `has(string $name) : bool` | Test for existence of a header. + `next() : void` | Advance the pointer for this object as an iterator. + `key() : mixed` | Return the current key for this object as an iterator. + `valid() : bool` | Is this iterator still valid? + `rewind() : void` | Reset the internal pointer for this object as an iterator. + `current() : HeaderInterface` | Return the current value for this iterator, lazy loading it if need be. + `count() : int` | Return the number of headers in this container. If all headers have not been parsed, the actual count could decrease if `MultipleHeader` instances exist. If you need an exact count, iterate. + `toString() : string` | Render all headers at once. This method handles the normal iteration of headers; it is up to the concrete classes to prepend with the appropriate status/request line. + `toArray() : array` | Return all headers as an associative array. + `forceLoading() : bool` | By calling this, it will force parsing and loading of all headers, ensuring `count()` is accurate. ## HeaderInterface Methods @@ -110,13 +110,13 @@ namespaces: - `AcceptFieldValuePart`: `Laminas\Http\Header\Accept\FieldValuePart\AcceptFieldValuePart` - `InvalidArgumentException`: `Laminas\Http\Header\Exception\InvalidArgumentException` -Method signature | Description ---------------------------------------------------------------- | ----------- -`parseHeaderLine(string $headerLine) : void` | Parse the given header line and add the values discovered to the instance. -`getFieldValuePartsFromHeaderLine(string $headerLine) : array` | Parse the field value parts represented by an Accept* header line. Throws `InvalidArgumentException` if the header is invalid. -`getFieldValue(array|null $values = null) : string` | Get field value. -`match(array|string $matchAgainst) : bool|AcceptFieldValuePart` | Match a media string against this header. Returns the matched value or false. -`getPrioritized() : array` | Returns all the keys, values and parameters this header represents. + Method signature | Description +-------------------------------------------------------------------| ----------- + `parseHeaderLine(string $headerLine) : void` | Parse the given header line and add the values discovered to the instance. + `getFieldValuePartsFromHeaderLine(string $headerLine) : array` | Parse the field value parts represented by an Accept* header line. Throws `InvalidArgumentException` if the header is invalid. + `getFieldValue(array\|null $values = null) : string` | Get field value. + `match(array\|string $matchAgainst) : bool\|AcceptFieldValuePart` | Match a media string against this header. Returns the matched value or false. + `getPrioritized() : array` | Returns all the keys, values and parameters this header represents. ## AbstractDate Methods @@ -136,10 +136,10 @@ Method signature | Description `static fromTimeString(string $time) : AbstractDate` | Create date-based header from `strtotime()`-compatible string. `static setDateFormat(int $format) : void` | Set date output format; should be an index from the implementation's `$dateFormat` static property. `static getDateFormat() : string` | Return current date output format. -`setDate(string|DateTime $date) : self` | Set the date for this header; this can be a string or an instance of `DateTime`. Throws `InvalidArgumentException` if the date is neither a valid string nor an instance of `DateTime`. +`setDate(string\|DateTime $date) : self` | Set the date for this header; this can be a string or an instance of `DateTime`. Throws `InvalidArgumentException` if the date is neither a valid string nor an instance of `DateTime`. `getDate() : string` | Return string representation of the date for this header. -`compareTo(string|DateTime $date) : int` | Compare provided date to date for this header. Returns `< 0` if date in header is less than `$date`; `> 0` if it's greater, and `= 0` if they are equal. See [strcmp](http://www.php.net/manual/en/function.strcmp.php). -`date() | DateTime` | Return date for this header as an instance of `DateTime`. +`compareTo(string\|DateTime $date) : int` | Compare provided date to date for this header. Returns `< 0` if date in header is less than `$date`; `> 0` if it's greater, and `= 0` if they are equal. See [strcmp](http://www.php.net/manual/en/function.strcmp.php). +`date() \| DateTime` | Return date for this header as an instance of `DateTime`. ## AbstractLocation Methods @@ -155,7 +155,7 @@ namespaces: Method signature | Description -------------------------------- | ----------- -`setUri(string|Uri $uri) : self` | Set the URI for this header; throws `InvalidArgumentException` for invalid `$uri` arguments. +`setUri(string\|Uri $uri) : self` | Set the URI for this header; throws `InvalidArgumentException` for invalid `$uri` arguments. `getUri() : string` | Return the URI for this header. `uri() : Uri` | Return the `Uri` instance for this header. @@ -172,7 +172,7 @@ Extends [AbstractAccept](#abstractaccept-methods). Method signature | Description ------------------------------------------------------------ | ----------- -`addMediaType(string $type, int|float $priority = 1) : self` | Add a media type, with the given priority. +`addMediaType(string $type, int\|float $priority = 1) : self` | Add a media type, with the given priority. `hasMediaType(string $type): bool` | Does the header have the requested media type? ### AcceptCharset @@ -181,7 +181,7 @@ Extends [AbstractAccept](#abstractaccept-methods). Method signature | Description ---------------------------------------------------------- | ----------- -`addCharset(string $type, int|float $priority = 1) : self` | Add a charset, with the given priority. +`addCharset(string $type, int\|float $priority = 1) : self` | Add a charset, with the given priority. `hasCharset(string $type) : bool` | Does the header have the requested charset? ### AcceptEncoding @@ -190,7 +190,7 @@ Extends [AbstractAccept](#abstractaccept-methods). Method signature | Description ----------------------------------------------------------- | ----------- -`addEncoding(string $type, int|float $priority = 1) : self` | Add an encoding, with the given priority. +`addEncoding(string $type, int\|float $priority = 1) : self` | Add an encoding, with the given priority. `hasEncoding(string $type) : bool` | Does the header have the requested encoding? ### AcceptLanguage @@ -199,7 +199,7 @@ Extends [AbstractAccept](#abstractaccept-methods). Method signature | Description ---------------------------------------------------------- | ----------- -`addLanguage(string $type, int|float $priority = 1): self` | Add a language, with the given priority. +`addLanguage(string $type, int\|float $priority = 1): self` | Add a language, with the given priority. `hasLanguage(string $type) : bool` | Does the header have the requested language? ### AcceptRanges @@ -222,9 +222,9 @@ Method signature | Description ---------------------------------------------------- | ----------- `getAllMethods() : string[]` | Get list of all defined methods. `getAllowedMethods() : string[]` | Get list of allowed methods. -`allowMethods(array|string $allowedMethods) : self` | Allow methods or list of methods. -`disallowMethods(array|string $allowedMethods) self` | Disallow methods or list of methods. -`denyMethods(array|string $allowedMethods) : self` | Convenience alias for `disallowMethods()`. +`allowMethods(array\|string $allowedMethods) : self` | Allow methods or list of methods. +`disallowMethods(array\|string $allowedMethods) self` | Disallow methods or list of methods. +`denyMethods(array\|string $allowedMethods) : self` | Convenience alias for `disallowMethods()`. `isAllowedMethod(string $method) : bool` | Check whether method is allowed. ### AuthenticationInfo @@ -240,9 +240,9 @@ No additional methods. Method signature | Description ------------------------------------------------------------- | ----------- `isEmpty(): bool` | Checks if the internal directives array is empty. -`addDirective(string $key, string|bool $value = true) : self` | Add a directive. For directives like `max-age=60`, call as `addDirective('max-age', 60)`. For directives like `private`, use the default `$value` (`true`). +`addDirective(string $key, string\|bool $value = true) : self` | Add a directive. For directives like `max-age=60`, call as `addDirective('max-age', 60)`. For directives like `private`, use the default `$value` (`true`). `hasDirective(string $key) : bool` | Check the internal directives array for a directive. -`getDirective(string $key) : null|string` | Fetch the value of a directive from the internal directive array. +`getDirective(string $key) : null\|string` | Fetch the value of a directive from the internal directive array. `removeDirective(string $key) : self` | Remove a directive. ### Connection @@ -308,15 +308,15 @@ No additional methods. ### ContentType -Method signature | Description -------------------------------------------------- | ----------- -`match(array|string $matchAgainst) : bool|string` | Determine if the mediatype value in this header matches the provided criteria. -`getMediaType() : string` | Get the media type. -`setMediaType(string $mediaType) : self` | Set the media type. -`getParameters() : array` | Get any additional content-type parameters currently set. -`setParameters(array $parameters) : self` | Set additional content-type parameters. -`getCharset() : null|string` | Get the content-type character set encoding, if any. -`setCharset(string $charset) : self` | Set the content-type character set encoding. + Method signature | Description +-----------------------------------------------------| ----------- + `match(array\|string $matchAgainst) : bool\|string` | Determine if the mediatype value in this header matches the provided criteria. + `getMediaType() : string` | Get the media type. + `setMediaType(string $mediaType) : self` | Set the media type. + `getParameters() : array` | Get any additional content-type parameters currently set. + `setParameters(array $parameters) : self` | Set additional content-type parameters. + `getCharset() : null\|string` | Get the content-type character set encoding, if any. + `setCharset(string $charset) : self` | Set the content-type character set encoding. ### Cookie @@ -442,15 +442,15 @@ Method signature | Descript `getValue() : string` | Retrieve the cookie value. `setValue(string $value) : self` | Set the cookie value. `getExpires() : int` | Retrieve the expiration date for the cookie. -`setExpires(int|string $expires) : self` | Set the cookie expiration timestamp; null indicates a session cookie. +`setExpires(int\|string $expires) : self` | Set the cookie expiration timestamp; null indicates a session cookie. `getPath() : string` | Retrieve the URI path the cookie is bound to. `setPath(string $path) : self` | Set the URI path the cookie is bound to. `getDomain() : string` | Retrieve the domain the cookie is bound to. `setDomain(string $domain) : self` | Set the domain the cookie is bound to. `getMaxAge() : int` | Retrieve the maximum age for the cookie. -`setMaxAge(int|string $maxAge) : self` | Set the maximum age for the cookie. +`setMaxAge(int\|string $maxAge) : self` | Set the maximum age for the cookie. `getVersion() : int` | Retrieve the cookie version. -`setVersion(int|string $version) : self` | Set the cookie version. +`setVersion(int\|string $version) : self` | Set the cookie version. `isSecure(): bool` | Whether the cookies contains the Secure flag. `setSecure(bool $secure) : self` | Set whether the cookies contain the Secure flag. `isHttponly() : bool` | Whether the cookies can be accessed via the HTTP protocol only. diff --git a/docs/book/intro.md b/docs/book/intro.md index 38adc572..13d9dba6 100644 --- a/docs/book/intro.md +++ b/docs/book/intro.md @@ -7,14 +7,14 @@ abstractions: - Context-less `Request` and `Response` classes that expose a fluent API for introspecting several aspects of HTTP messages: - - Request line information and response status information - - Parameters, such as those found in POST and GET - - Message Body - - Headers + - Request line information and response status information + - Parameters, such as those found in POST and GET + - Message Body + - Headers - A client implementation with various adapters that allow for sending requests and introspecting responses. -> ### Not PSR-7! +> ## Not PSR-7 > > This library **does not** support [PSR-7](http://www.php-fig.org/psr/psr-7), as > it predates that specification. For PSR-7 support, please see our diff --git a/docs/book/request.md b/docs/book/request.md index e546fdc5..e391a013 100644 --- a/docs/book/request.md +++ b/docs/book/request.md @@ -72,22 +72,22 @@ Method signature | De `static fromString(string $string) : Request` | A factory that produces a `Request` object from a well-formed HTTP request message string. `setMethod(string $method) : self` | Set the method for this request. `getMethod() : string` | Return the method for this request. -`setUri(string|Uri $uri) : self` | Set the URI/URL for this request; this can be a string or an instance of `Laminas\Uri\Http`. +`setUri(string\|Uri $uri) : self` | Set the URI/URL for this request; this can be a string or an instance of `Laminas\Uri\Http`. `getUri() : Uri` | Return the URI for this request object. `getUriString() : string` | Return the URI for this request object as a string. `setVersion(string $version) : self` | Set the HTTP version for this object, one of 1.0, 1.1 or 2 (`Request::VERSION_10`, `Request::VERSION_11`, `Request::VERSION_2`). HTTP/2 support was added in laminas-http 2.10.0. `getVersion() : string` | Return the HTTP version for this request. `setQuery(Parameters $query) : self` | Provide an alternate Parameter Container implementation for query parameters in this object. (This is NOT the primary API for value setting; for that, see `getQuery()`). -`getQuery(string|null $name, mixed|null $default) : null|string|Parameters` | Return the parameter container responsible for query parameters or a single query parameter based on `$name`. +`getQuery(string\|null $name, mixed\|null $default) : null\|string\|Parameters` | Return the parameter container responsible for query parameters or a single query parameter based on `$name`. `setPost(Parameters $post) : self` | Provide an alternate Parameter Container implementation for POST parameters in this object. (This is NOT the primary API for value setting; for that, see `getPost()`). -`getPost(string|null $name, mixed|null $default) : null|string|Parameters` | Return the parameter container responsible for POST parameters or a single POST parameter, based on `$name`. +`getPost(string\|null $name, mixed\|null $default) : null\|string\|Parameters` | Return the parameter container responsible for POST parameters or a single POST parameter, based on `$name`. `getCookie() : Header\Cookie` | Return the Cookie header, this is the same as calling `$request->getHeaders()->get('Cookie');`. `setFiles(Parameters $files) : self` | Provide an alternate Parameter Container implementation for file parameters in this object, (This is NOT the primary API for value setting; for that, see `getFiles()`). -`getFiles(string|null $name, mixed|null $default) : null|string|Parameters` | Return the parameter container responsible for file parameters or a single file parameter, based on `$name`. +`getFiles(string\|null $name, mixed\|null $default) : null\|string\|Parameters` | Return the parameter container responsible for file parameters or a single file parameter, based on `$name`. `setHeaders(Headers $headers) : self` | Provide an alternate Parameter Container implementation for headers in this object, (this is NOT the primary API for value setting, for that see `getHeaders()`). -`getHeaders(string|null $name, mixed|null $default) : mixed` | Return the container responsible for storing HTTP headers. This container exposes the primary API for manipulating headers set in the HTTP request. See the section on [Headers](headers.md) for more information. Return value is based on `$name`; `null` returns `Headers`, while a matched header returns a `Header\HeaderInterface` implementation for single-value headers or an `ArrayIterator` for multi-value headers. -`setMetadata(string|int|array|Traversable $spec, mixed $value) : self` | Set message metadata. Non-destructive setting of message metadata; always adds to the metadata, never overwrites the entire metadata container. -`getMetadata(null|string|int $key, null|mixed $default) : mixed` | Retrieve all metadata or a single metadatum as specified by key. +`getHeaders(string\|null $name, mixed\|null $default) : mixed` | Return the container responsible for storing HTTP headers. This container exposes the primary API for manipulating headers set in the HTTP request. See the section on [Headers](headers.md) for more information. Return value is based on `$name`; `null` returns `Headers`, while a matched header returns a `Header\HeaderInterface` implementation for single-value headers or an `ArrayIterator` for multi-value headers. +`setMetadata(string\|int\|array\|Traversable $spec, mixed $value) : self` | Set message metadata. Non-destructive setting of message metadata; always adds to the metadata, never overwrites the entire metadata container. +`getMetadata(null\|string\|int $key, null\|mixed $default) : mixed` | Retrieve all metadata or a single metadatum as specified by key. `setContent(mixed $value) : self` | Set request body (content). `getContent() : mixed` | Get request body (content). `isOptions() : bool` | Is this an OPTIONS method request? diff --git a/docs/book/response.md b/docs/book/response.md index 86265093..241ad9e5 100644 --- a/docs/book/response.md +++ b/docs/book/response.md @@ -94,8 +94,8 @@ Method signature | Descrip `decodeChunkedBody(string $body) : string` | Decode a "chunked" transfer-encoded body and return the decoded text. `decodeGzip(string $body) : string` | Decode a gzip encoded message (when `Content-Encoding` indicates gzip). Currently requires PHP with zlib support. `decodeDeflate(string $body) : string` | Decode a zlib deflated message (when `Content-Encoding` indicates deflate). Currently requires PHP with zlib support. -`setMetadata(string|int|array|Traversable $spec, mixed $value) : self` | Non-destructive setting of message metadata; always adds to the metadata, never overwrites the entire metadata container. -`getMetadata(null|string|int $key, null|mixed $default) : mixed` | Retrieve all metadata or a single metadatum as specified by key. +`setMetadata(string\|int\|array\|Traversable $spec, mixed $value) : self` | Non-destructive setting of message metadata; always adds to the metadata, never overwrites the entire metadata container. +`getMetadata(null\|string\|int $key, null\|mixed $default) : mixed` | Retrieve all metadata or a single metadatum as specified by key. `setContent(mixed $value) : self` | Set message content. `getContent() : mixed` | Get raw message content. `getBody() : mixed` | Get decoded message content.