Merge pull request thecodingmachine#96 from jderusse/update-doc

Update documentation

Author: moufmouf

generated/com.php

@@ -86,16 +86,16 @@ function com_event_sink(variant $comobject, object $sinkobject, $sinkinterface =
  *
  * The type library name, e.g. Microsoft OLE DB ActiveX Data
  * Objects 1.0 Library.
- * @param int $case_insensitive The case_insensitive behaves in the same way as
- * the parameter with the same name in the define
+ * @param bool $case_sensitive The case_sensitive behaves inversely to
+ * the parameter $case_insensitive in the define
  * function.
  * @throws ComException
  *
  */
-function com_load_typelib(string $typelib_name, bool $case_insensitive = true): void
+function com_load_typelib(string $typelib_name, bool $case_sensitive = true): void
 {
     error_clear_last();
-    $result = \com_load_typelib($typelib_name, $case_insensitive);
+    $result = \com_load_typelib($typelib_name, $case_sensitive);
     if ($result === false) {
         throw ComException::createFromPhpError();
     }

generated/funchand.php

@@ -89,8 +89,7 @@ function forward_static_call(callable $function, ...$params)
 /**
  *
  *
- * @param callable $function The function name as a string, or an array consisting of an object and
- * a method.
+ * @param callable $function The function to register.
  * @param mixed $params
  * @throws FunchandException
  *

generated/functionsList.php

@@ -914,6 +914,7 @@
     'socket_set_option',
     'socket_shutdown',
     'socket_write',
+    'sodium_crypto_pwhash_str',
     'sodium_crypto_pwhash',
     'solr_get_version',
     'class_implements',
@@ -1036,6 +1037,8 @@
     'xdiff_string_bpatch',
     'xdiff_string_patch_binary',
     'xdiff_string_patch',
+    'xml_parser_create_ns',
+    'xml_parser_create',
     'xml_set_object',
     'xmlrpc_set_type',
     'yaml_parse_file',

generated/image.php

@@ -1639,20 +1639,16 @@ function imagerotate($image, float $angle, int $bgd_color, int $ignore_transpare
 
 
 /**
- * imagesavealpha sets the flag to attempt to save
+ * imagesavealpha sets the flag which determines whether to retain
  * full alpha channel information (as opposed to single-color transparency)
  * when saving PNG images.
  *
- * You have to unset alphablending
- * (imagealphablending($im, false)), to use it.
- *
- * Alpha channel is not supported by all browsers, if you have problem with
- * your browser, try to load your script with an alpha channel compliant
- * browser, e.g. latest Mozilla.
+ * Alphablending has to be disabled (imagealphablending($im, false))
+ * to retain the alpha-channel in the first place.
  *
  * @param resource $image An image resource, returned by one of the image creation functions,
  * such as imagecreatetruecolor.
- * @param bool $saveflag Whether to save the alpha channel or not. Default to FALSE.
+ * @param bool $saveflag Whether to save the alpha channel or not. Defaults to FALSE.
  * @throws ImageException
  *
  */

generated/mbstring.php

@@ -451,7 +451,7 @@ function mb_regex_encoding(string $encoding = null)
  *
  * This parameter is escaped by escapeshellcmd internally
  * to prevent command execution. escapeshellcmd prevents
- * command execution, but allows to add addtional parameters. For security reason,
+ * command execution, but allows to add additional parameters. For security reason,
  * this parameter should be validated.
  *
  * Since escapeshellcmd is applied automatically, some characters

generated/misc.php

@@ -110,13 +110,16 @@ function sapi_windows_cp_set(int $cp): void
 
 
 /**
- * If enable is omitted, the function return TRUE if the stream stream has VT100 control codes enabled, FALSE otherwise.
+ * If enable is omitted, the function returns TRUE if the stream stream has VT100 control codes enabled, FALSE otherwise.
  *
  * If enable is specified, the function will try to enable or disable the VT100 features of the stream stream.
  * If the feature has been successfully enabled (or disabled), .
  *
  * At startup, PHP tries to enable the VT100 feature of the STDOUT/STDERR streams. By the way, if those streams are redirected to a file, the VT100 features may not be enabled.
  *
+ * If VT100 support is enabled, it is possible to use control sequences as they are known from the VT100 terminal.
+ * They allow the modification of the terminal's output. On Windows these sequences are called Console Virtual Terminal Sequences.
+ *
  * @param resource $stream The stream on which the function will operate.
  * @param bool $enable If specified, the VT100 feature will be enabled (if TRUE) or disabled (if FALSE).
  * @throws MiscException

generated/sodium.php

@@ -5,20 +5,41 @@
 use Safe\Exceptions\SodiumException;
 
 /**
+ * Uses a CPU- and memory-hard hash algorithm along with a randomly-generated salt, and memory and CPU limits to generate an ASCII-encoded hash suitable for password storage.
  *
+ * @param string $password string; The password to generate a hash for.
+ * @param int $opslimit Represents a maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key. There are constants available to set the operations limit to appropriate values depending on intended use, in order of strength: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE and SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE.
+ * @param int $memlimit The maximum amount of RAM that the function will use, in bytes. There are constants to help you choose an appropriate value, in order of size: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE, and SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE. Typically these should be paired with the matching opslimit values.
+ * @return string Returns the hashed password,  .
+ *
+ * In order to produce the same password hash from the same password, the same values for opslimit and memlimit must be used. These are embedded within the generated hash, so
+ * everything that's needed to verify the hash is included. This allows
+ * the sodium_crypto_pwhash_str_verify function to verify the hash without
+ * needing separate storage for the other parameters.
+ * @throws SodiumException
+ *
+ */
+function sodium_crypto_pwhash_str(string $password, int $opslimit, int $memlimit): string
+{
+    error_clear_last();
+    $result = \sodium_crypto_pwhash_str($password, $opslimit, $memlimit);
+    if ($result === false) {
+        throw SodiumException::createFromPhpError();
+    }
+    return $result;
+}
+
+
+/**
+ * This function provides low-level access to libsodium's crypto_pwhash key derivation function. Unless you have specific reason to use this function, you should use sodium_crypto_pwhash_str or password_hash functions instead.
  *
  * @param int $length integer; The length of the password hash to generate, in bytes.
  * @param string $password string; The password to generate a hash for.
  * @param string $salt string A salt to add to the password before hashing. The salt should be unpredictable, ideally generated from a good random mumber source such as random_bytes, and have a length of at least SODIUM_CRYPTO_PWHASH_SALTBYTES bytes.
  * @param int $opslimit Represents a maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key. There are some constants available to set the operations limit to appropriate values depending on intended use, in order of strength: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE and SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE.
  * @param int $memlimit The maximum amount of RAM that the function will use, in bytes. There are constants to help you choose an appropriate value, in order of size: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE, and SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE. Typically these should be paired with the matching opslimit values.
- * @param int $alg integer A number indicating the hash algorithm to use. By default SODIUM_CRYPTO_PWHASH_ALG_DEFAULT (the currently recommended algorithm, which can change from one version of libsodium to another), or explicitly using SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13, representing the Argon2id algorithm version 1.3.
- * @return string Returns the hashed password,  .
- *
- * The used algorithm, opslimit, memlimit and salt are embedded within the hash, so
- * all information needed to verify the hash is included. This allows
- * the password_verify function to verify the hash without
- * needing separate storage for the salt or algorithm information.
+ * @param int $alg integer A number indicating the hash algorithm to use. By default SODIUM_CRYPTO_PWHASH_ALG_DEFAULT (the currently recommended algorithm, which can change from one version of libsodium to another), or explicitly using SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13, representing the Argon2id algorithm version 1.3.
+ * @return string Returns the derived key,  . The return value is a binary string of the hash, not an ASCII-encoded representation, and does not contain additional information about the parameters used to create the hash, so you will need to keep that information if you are ever going to verify the password in future. Use sodium_crypto_pwhash_str to avoid needing to do all that.
  * @throws SodiumException
  *
  */

generated/sqlsrv.php

@@ -10,7 +10,7 @@
  * sqlsrv_begin_transaction and before calls to
  * sqlsrv_rollback or sqlsrv_commit.
  * Explicit transactions should be started and committed or rolled back using
- * these functions instead of executing SQL statements that begin and committ/roll
+ * these functions instead of executing SQL statements that begin and commit/roll
  * back transactions. For more information, see
  * SQLSRV Transactions.
  *
@@ -122,7 +122,7 @@ function sqlsrv_close($conn): void
  * is called. The transaction that is committed includes all statements that were
  * executed after the call to sqlsrv_begin_transaction.
  * Explicit transactions should be started and committed or rolled back using these
- * functions instead of executing SQL statements that begin and committ/roll back
+ * functions instead of executing SQL statements that begin and commit/roll back
  * transactions. For more information, see
  * SQLSRV Transactions.
  *
@@ -218,7 +218,7 @@ function sqlsrv_execute($stmt): void
  * that alters server state, statement execution is terminated and the statement
  * is rolled back.
  *
- * @param resource $stmt The statment for which resources are freed.
+ * @param resource $stmt The statement for which resources are freed.
  * Note that NULL is a valid parameter value. This allows the function to be
  * called multiple times in a script.
  * @throws SqlsrvException
@@ -271,7 +271,7 @@ function sqlsrv_get_field($stmt, int $fieldIndex, int $getAsType = null)
  * Makes the next result of the specified statement active. Results include result
  * sets, row counts, and output parameters.
  *
- * @param resource $stmt The statment on which the next result is being called.
+ * @param resource $stmt The statement on which the next result is being called.
  * @return mixed Returns TRUE if the next result was successfully retrieved, FALSE if an error
  * occurred, and NULL if there are no more results to retrieve.
  * @throws SqlsrvException
@@ -291,7 +291,7 @@ function sqlsrv_next_result($stmt)
 /**
  * Retrieves the number of fields (columns) on a statement.
  *
- * @param resource $stmt The statment for which the number of fields is returned.
+ * @param resource $stmt The statement for which the number of fields is returned.
  * sqlsrv_num_fields can be called on a statement before
  * or after statement execution.
  * @return mixed Returns the number of fields on success. Returns FALSE otherwise.
@@ -311,12 +311,12 @@ function sqlsrv_num_fields($stmt)
 
 /**
  * Retrieves the number of rows in a result set. This function requires that the
- * statment resource be created with a static or keyset cursor. For more information,
+ * statement resource be created with a static or keyset cursor. For more information,
  * see sqlsrv_query, sqlsrv_prepare,
  * or Specifying a Cursor Type and Selecting Rows
  * in the Microsoft SQLSRV documentation.
  *
- * @param resource $stmt The statement for which the row count is returned. The statment resource
+ * @param resource $stmt The statement for which the row count is returned. The statement resource
  * must be created with a static or keyset cursor. For more information, see
  * sqlsrv_query, sqlsrv_prepare, or
  * Specifying a Cursor Type and Selecting Rows
@@ -352,7 +352,7 @@ function sqlsrv_num_rows($stmt)
  * array($value [, $direction [, $phpType [, $sqlType]]])
  *
  * The following table describes the elements in the array structure above:
- * @param array $options An array specifing query property options. The supported keys are described
+ * @param array $options An array specifying query property options. The supported keys are described
  * in the following table:
  * @return mixed Returns a statement resource on success and FALSE if an error occurred.
  * @throws SqlsrvException
@@ -389,7 +389,7 @@ function sqlsrv_prepare($conn, string $sql, array $params = null, array $options
  * array($value [, $direction [, $phpType [, $sqlType]]])
  *
  * The following table describes the elements in the array structure above:
- * @param array $options An array specifing query property options. The supported keys are described
+ * @param array $options An array specifying query property options. The supported keys are described
  * in the following table:
  * @return mixed Returns a statement resource on success and FALSE if an error occurred.
  * @throws SqlsrvException

generated/strings.php

@@ -253,7 +253,7 @@ function sha1_file(string $filename, bool $raw_output = false): string
  *
  *
  * G - shorter of %E and
- * %f.
+ * %F.
  *
  *
  * o - the argument is treated as an
@@ -328,7 +328,7 @@ function sha1_file(string $filename, bool $raw_output = false): string
  *
  *
  * G - shorter of %E and
- * %f.
+ * %F.
  *
  *
  * o - the argument is treated as an

generated/xml.php

@@ -4,6 +4,76 @@
 
 use Safe\Exceptions\XmlException;
 
+/**
+ * xml_parser_create_ns creates a new XML parser
+ * with XML namespace support and returns a resource handle referencing
+ * it to be used by the other XML functions.
+ *
+ * @param string $encoding The input encoding is automatically detected, so that the
+ * encoding parameter specifies only the output
+ * encoding. In PHP 5.0.0 and 5.0.1, the default output charset is
+ * ISO-8859-1, while in PHP 5.0.2 and upper is UTF-8. The supported
+ * encodings are ISO-8859-1, UTF-8 and
+ * US-ASCII.
+ * @param string $separator With a namespace aware parser tag parameters passed to the various
+ * handler functions will consist of namespace and tag name separated by
+ * the string specified in separator.
+ * @return resource Returns a resource handle for the new XML parser,  .
+ * @throws XmlException
+ *
+ */
+function xml_parser_create_ns(string $encoding = null, string $separator = ":")
+{
+    error_clear_last();
+    if ($separator !== ":") {
+        $result = \xml_parser_create_ns($encoding, $separator);
+    } elseif ($encoding !== null) {
+        $result = \xml_parser_create_ns($encoding);
+    } else {
+        $result = \xml_parser_create_ns();
+    }
+    if ($result === false) {
+        throw XmlException::createFromPhpError();
+    }
+    return $result;
+}
+
+
+/**
+ * xml_parser_create creates a new XML parser
+ * and returns a resource handle referencing it to be used by the
+ * other XML functions.
+ *
+ * @param string $encoding The optional encoding specifies the character
+ * encoding for the input/output in PHP 4. Starting from PHP 5, the input
+ * encoding is automatically detected, so that the
+ * encoding parameter specifies only the output
+ * encoding. In PHP 4, the default output encoding is the same as the
+ * input charset. If empty string is passed, the parser attempts to identify
+ * which encoding the document is encoded in by looking at the heading 3 or
+ * 4 bytes. In PHP 5.0.0 and 5.0.1, the default output charset is
+ * ISO-8859-1, while in PHP 5.0.2 and upper is UTF-8. The supported
+ * encodings are ISO-8859-1, UTF-8 and
+ * US-ASCII.
+ * @return resource Returns a resource handle for the new XML parser,  .
+ * @throws XmlException
+ *
+ */
+function xml_parser_create(string $encoding = null)
+{
+    error_clear_last();
+    if ($encoding !== null) {
+        $result = \xml_parser_create($encoding);
+    } else {
+        $result = \xml_parser_create();
+    }
+    if ($result === false) {
+        throw XmlException::createFromPhpError();
+    }
+    return $result;
+}
+
+
 /**
  * This function allows to use parser inside
  * object. All callback functions could be set with