<?php

namespace Safe;

use Safe\Exceptions\PasswordException;

/**
 * password_hash creates a new password hash using a strong one-way hashing
 * algorithm. password_hash is compatible with crypt.
 * Therefore, password hashes created by crypt can be used with
 * password_hash.
 *
 *
 *
 *
 * PASSWORD_DEFAULT - Use the bcrypt algorithm (default as of PHP 5.5.0).
 * Note that this constant is designed to change over time as new and stronger algorithms are added
 * to PHP. For that reason, the length of the result from using this identifier can change over
 * time. Therefore, it is recommended to store the result in a database column that can expand
 * beyond 60 characters (255 characters would be a good choice).
 *
 *
 *
 *
 * PASSWORD_BCRYPT - Use the CRYPT_BLOWFISH algorithm to
 * create the hash. This will produce a standard crypt compatible hash using
 * the "$2y$" identifier. The result will always be a 60 character string.
 *
 *
 *
 *
 * PASSWORD_ARGON2I - Use the Argon2i hashing algorithm to create the hash.
 * This algorithm is only available if PHP has been compiled with Argon2 support.
 *
 *
 *
 *
 * PASSWORD_ARGON2ID - Use the Argon2id hashing algorithm to create the hash.
 * This algorithm is only available if PHP has been compiled with Argon2 support.
 *
 *
 *
 *
 *
 *
 *
 * salt (string) - to manually provide a salt to use when hashing the password.
 * Note that this will override and prevent a salt from being automatically generated.
 *
 *
 * If omitted, a random salt will be generated by password_hash for
 * each password hashed. This is the intended mode of operation.
 *
 *
 *
 * The salt option has been deprecated as of PHP 7.0.0. It is now
 * preferred to simply use the salt that is generated by default.
 *
 *
 *
 *
 *
 * cost (integer) - which denotes the algorithmic cost that should be used.
 * Examples of these values can be found on the crypt page.
 *
 *
 * If omitted, a default value of 10 will be used. This is a good
 * baseline cost, but you may want to consider increasing it depending on your hardware.
 *
 *
 *
 *
 *
 *
 *
 * memory_cost (integer) - Maximum memory (in kibibytes) that may
 * be used to compute the Argon2 hash. Defaults to PASSWORD_ARGON2_DEFAULT_MEMORY_COST.
 *
 *
 *
 *
 * time_cost (integer) - Maximum amount of time it may
 * take to compute the Argon2 hash. Defaults to PASSWORD_ARGON2_DEFAULT_TIME_COST.
 *
 *
 *
 *
 * threads (integer) - Number of threads to use for computing
 * the Argon2 hash. Defaults to PASSWORD_ARGON2_DEFAULT_THREADS.
 *
 *
 *
 *
 * @param string $password The user's password.
 *
 * Using the PASSWORD_BCRYPT as the
 * algorithm, will result
 * in the password parameter being truncated to a
 * maximum length of 72 characters.
 * @param int|string|null $algo A password algorithm constant denoting the algorithm to use when hashing the password.
 * @param array $options An associative array containing options. See the password algorithm constants for documentation on the supported options for each algorithm.
 *
 * If omitted, a random salt will be created and the default cost will be
 * used.
 * @return string Returns the hashed password.
 *
 * The used algorithm, cost and salt are returned as part of the hash. Therefore,
 * all information that's needed to verify the hash is included in it. This allows
 * the password_verify function to verify the hash without
 * needing separate storage for the salt or algorithm information.
 * @throws PasswordException
 *
 */
function password_hash(string $password, $algo, array $options = null): string
{
    error_clear_last();
    if ($options !== null) {
        $result = \password_hash($password, $algo, $options);
    } else {
        $result = \password_hash($password, $algo);
    }
    if ($result === false) {
        throw PasswordException::createFromPhpError();
    }
    return $result;
}