🚿 docblock updates/cleanup

Author: codemasher

src/Header.php

@@ -22,10 +22,6 @@ class Header{
 	 * Normalizes an array of header lines to format ["Name" => "Value (, Value2, Value3, ...)", ...]
 	 * An exception is being made for Set-Cookie, which holds an array of values for each cookie.
 	 * For multiple cookies with the same name, only the last value will be kept.
-	 *
-	 * @param array $headers
-	 *
-	 * @return array
 	 */
 	public static function normalize(array $headers):array{
 		$normalized = [];

src/Query.php

@@ -10,7 +10,8 @@
 
 namespace chillerlan\HTTP\Utils;
 
-use function array_merge, explode, implode, is_array, is_bool, is_string, rawurldecode, sort, str_replace, uksort;
+use function array_merge, call_user_func_array, explode, implode, is_array, is_bool, is_iterable,
+	is_numeric, is_string, rawurldecode, sort, str_replace, trim, uksort;
 use const PHP_QUERY_RFC1738, PHP_QUERY_RFC3986, SORT_STRING;
 
 /**
@@ -26,6 +27,10 @@ final class Query{
 	public const NO_ENCODING = -1;
 
 	/**
+	 * Cleans/normalizes an array of query parameters, booleans will be converted according to the given $bool_cast constant.
+	 * By default, booleans will be left as-is (BOOLEANS_AS_BOOL) and may result in empty values.
+	 * If $remove_empty is set to true, empty and null values will be removed from the array.
+	 *
 	 * @param iterable  $params
 	 * @param int|null  $bool_cast    converts booleans to a type determined like following:
 	 *                                BOOLEANS_AS_BOOL      : unchanged boolean value (default)
@@ -76,7 +81,7 @@ public static function cleanParams(iterable $params, int $bool_cast = null, bool
 			}
 			else{
 
-				if($remove_empty && ($value === null || (!is_numeric($value) && empty($value)))){
+				if($remove_empty && (!is_numeric($value) && empty($value))){
 					continue;
 				}
 
@@ -88,7 +93,7 @@ public static function cleanParams(iterable $params, int $bool_cast = null, bool
 	}
 
 	/**
-	 * Build a query string from an array of key value pairs.
+	 * Builds a query string from an array of key value pairs.
 	 *
 	 * Valid values for $encoding are PHP_QUERY_RFC3986 (default) and PHP_QUERY_RFC1738,
 	 * any other integer value will be interpreted as "no encoding".
@@ -158,27 +163,22 @@ public static function build(array $params, int $encoding = null, string $delimi
 	}
 
 	/**
-	 * merges additional query parameters into an existing query string
-	 *
-	 * @param string $uri
-	 * @param array  $query
-	 *
-	 * @return string
+	 * Merges additional query parameters into an existing query string
 	 */
 	public static function merge(string $uri, array $query):string{
 		$parsedquery = self::parse(parseUrl($uri)['query'] ?? '');
 		$requestURI  = explode('?', $uri)[0];
 		$params      = array_merge($parsedquery, $query);
 
 		if(!empty($params)){
-			$requestURI .= '?'.Query::build($params);
+			$requestURI .= '?'.self::build($params);
 		}
 
 		return $requestURI;
 	}
 
 	/**
-	 * Parse a query string into an associative array.
+	 * Parses a query string into an associative array.
 	 *
 	 * @link https://github.com/guzzle/psr7/blob/c0dcda9f54d145bd4d062a6d15f54931a67732f9/src/Query.php#L9-L57
 	 */

src/Server.php

@@ -41,7 +41,7 @@ public function __construct(
 	}
 
 	/**
-	 * Return a ServerRequest populated with superglobals:
+	 * Returns a ServerRequest populated with superglobals:
 	 *  - $_GET
 	 *  - $_POST
 	 *  - $_COOKIE
@@ -74,7 +74,7 @@ public function createServerRequestFromGlobals():ServerRequestInterface{
 	}
 
 	/**
-	 * Create a Uri populated with values from $_SERVER.
+	 * Creates an Uri populated with values from $_SERVER.
 	 */
 	public function createUriFromGlobals():UriInterface{
 		$hasPort  = false;
@@ -124,11 +124,11 @@ public function createUriFromGlobals():UriInterface{
 
 
 	/**
-	 * Return an UploadedFile instance array.
+	 * Returns an UploadedFile instance array.
 	 *
-	 * @param array $files A array which respect $_FILES structure
+	 * @param array $files An array which respect $_FILES structure
 	 *
-	 * @return array
+	 * @return \Psr\Http\Message\UploadedFileInterface[]
 	 * @throws \InvalidArgumentException for unrecognized values
 	 */
 	public function normalizeFiles(array $files):array{
@@ -156,7 +156,7 @@ public function normalizeFiles(array $files):array{
 	}
 
 	/**
-	 * Create and return an UploadedFile instance from a $_FILES specification.
+	 * Creates an UploadedFile instance from a $_FILES specification.
 	 *
 	 * If the specification represents an array of values, this method will
 	 * delegate to normalizeNestedFileSpec() and return that return value.
@@ -181,7 +181,7 @@ public function createUploadedFileFromSpec(array $value){
 	}
 
 	/**
-	 * Normalize an array of file specifications.
+	 * Normalizes an array of file specifications.
 	 *
 	 * Loops through all nested files and returns a normalized array of
 	 * UploadedFileInterface instances.

src/message_helpers.php

@@ -140,6 +140,8 @@ function getMimetypeFromFilename(string $filename):?string{
 }
 
 /**
+ * Recursive rawurlencode
+ *
  * @param string|string[] $data
  *
  * @return string|string[]
@@ -159,9 +161,6 @@ function r_rawurlencode($data){
 }
 
 /**
- * @param \Psr\Http\Message\MessageInterface $message
- * @param bool|null                          $assoc
- *
  * @return \stdClass|array|bool
  */
 function get_json(MessageInterface $message, bool $assoc = null){
@@ -173,9 +172,6 @@ function get_json(MessageInterface $message, bool $assoc = null){
 }
 
 /**
- * @param \Psr\Http\Message\MessageInterface $message
- * @param bool|null                          $assoc
- *
  * @return \SimpleXMLElement|array|bool
  */
 function get_xml(MessageInterface $message, bool $assoc = null){
@@ -190,10 +186,6 @@ function get_xml(MessageInterface $message, bool $assoc = null){
 
 /**
  * Returns the string representation of an HTTP message. (from Guzzle)
- *
- * @param \Psr\Http\Message\MessageInterface $message Message to convert to a string.
- *
- * @return string
  */
 function message_to_string(MessageInterface $message):string{
 	$msg = '';
@@ -223,9 +215,6 @@ function message_to_string(MessageInterface $message):string{
 /**
  * Decompresses the message content according to the Content-Encoding header and returns the decompressed data
  *
- * @param \Psr\Http\Message\MessageInterface $message
- *
- * @return string
  * @throws \RuntimeException
  */
 function decompress_content(MessageInterface $message):string{
@@ -270,7 +259,7 @@ function decompress_content(MessageInterface $message):string{
 ];
 
 /**
- * Checks whether the URI has a port set and if that port is one of the default ports for the given scheme
+ * Checks whether the UriInterface has a port set and if that port is one of the default ports for the given scheme
  */
 function uriIsDefaultPort(UriInterface $uri):bool{
 	$port   = $uri->getPort();
@@ -280,7 +269,7 @@ function uriIsDefaultPort(UriInterface $uri):bool{
 }
 
 /**
- * Whether the URI is absolute, i.e. it has a scheme.
+ * Checks Whether the URI is absolute, i.e. it has a scheme.
  *
  * An instance of UriInterface can either be an absolute URI or a relative reference. This method returns true
  * if it is the former. An absolute URI has a scheme. A relative reference is used to express a URI relative
@@ -299,7 +288,7 @@ function uriIsAbsolute(UriInterface $uri):bool{
 }
 
 /**
- * Whether the URI is a network-path reference.
+ * Checks Whether the URI is a network-path reference.
  *
  * A relative reference that begins with two slash characters is termed an network-path reference.
  *
@@ -310,7 +299,7 @@ function uriIsNetworkPathReference(UriInterface $uri):bool{
 }
 
 /**
- * Whether the URI is a absolute-path reference.
+ * Checks Whether the URI is a absolute-path reference.
  *
  * A relative reference that begins with a single slash character is termed an absolute-path reference.
  *
@@ -321,7 +310,7 @@ function uriIsAbsolutePathReference(UriInterface $uri):bool{
 }
 
 /**
- * Whether the URI is a relative-path reference.
+ * Checks Whether the URI is a relative-path reference.
  *
  * A relative reference that does not begin with a slash character is termed a relative-path reference.
  *
@@ -332,12 +321,9 @@ function uriIsRelativePathReference(UriInterface $uri):bool{
 }
 
 /**
- * removes a specific query string value.
+ * Removes a specific query string value.
  *
- * Any existing query string values that exactly match the provided key are
- * removed.
- *
- * @param string $key Query string key to remove.
+ * Any existing query string values that exactly match the provided $key are removed.
  */
 function uriWithoutQueryValue(UriInterface $uri, string $key):UriInterface{
 	$current = $uri->getQuery();
@@ -356,16 +342,12 @@ function uriWithoutQueryValue(UriInterface $uri, string $key):UriInterface{
 }
 
 /**
- * adds a specific query string value.
- *
- * Any existing query string values that exactly match the provided key are
- * removed and replaced with the given key value pair.
+ * Adds a specific query string value.
  *
- * A value of null will set the query string key without a value, e.g. "key"
- * instead of "key=value".
+ * Any existing query string values that exactly match the provided $key are
+ * removed and replaced with the given $key $value pair.
  *
- * @param string      $key   Key to set.
- * @param string|null $value Value to set
+ * A value of null will set the query string key without a value, e.g. "key" instead of "key=value".
  */
 function uriWithQueryValue(UriInterface $uri, string $key, string $value = null):UriInterface{
 	$current = $uri->getQuery();