password_compat

Compatibility with the password_* functions that ship with PHP 5.5

2,149

421

2,149

Quick Overview

The ircmaxell/password_compat is a compatibility library that provides forward compatibility with the password_* functions that ship with PHP 5.5. It allows developers to use these functions in PHP versions 5.3.7+ and PHP 5.4.x, ensuring consistent password hashing across different PHP versions.

Pros

Enables the use of modern password hashing functions in older PHP versions
Improves security by providing access to more robust password hashing methods
Easy to integrate into existing projects
Maintained and widely used in the PHP community

Cons

No longer actively maintained (last commit was in 2018)
May introduce a slight performance overhead compared to native implementations
Not necessary for PHP versions 5.5 and above
Requires manual installation in projects not using Composer

Code Examples

Hashing a password:

$password = 'user_password';
$hash = password_hash($password, PASSWORD_DEFAULT);

Verifying a password:

$password = 'user_input_password';
$hash = 'stored_hash_from_database';
if (password_verify($password, $hash)) {
    echo "Password is valid!";
} else {
    echo "Invalid password.";
}

Checking if a password needs rehashing:

$hash = 'stored_hash_from_database';
if (password_needs_rehash($hash, PASSWORD_DEFAULT)) {
    $newHash = password_hash($password, PASSWORD_DEFAULT);
    // Store $newHash in the database
}

Getting Started

Install via Composer:

composer require ircmaxell/password-compat

Include in your PHP file:

require 'vendor/autoload.php';

Use the functions as if they were native PHP functions:

$password = 'user_password';
$hash = password_hash($password, PASSWORD_DEFAULT);

Note: If you're using PHP 5.5 or later, you don't need this library as these functions are already available natively.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

password_compat

This library is intended to provide forward compatibility with the password_* functions that ship with PHP 5.5.

See the RFC for more detailed information.

Requirements

This library requires PHP >= 5.3.7 OR a version that has the $2y fix backported into it (such as RedHat provides). Note that Debian's 5.3.3 version is NOT supported.

The runtime checks have been removed due to this version issue. To see if password_compat is available for your system, run the included version-test.php. If it outputs "Pass", you can safely use the library. If not, you cannot.

If you attempt to use password-compat on an unsupported version, attempts to create or verify hashes will return false. You have been warned!

The reason for this is that PHP prior to 5.3.7 contains a security issue with its BCRYPT implementation. Therefore, it's highly recommended that you upgrade to a newer version of PHP prior to using this layer.

Installation

To install, simply require the password.php file under lib.

You can also install it via Composer by using the Packagist archive.

Usage

Creating Password Hashes

To create a password hash from a password, simply use the password_hash function.

    $hash = password_hash($password, PASSWORD_BCRYPT);

Note that the algorithm that we chose is PASSWORD_BCRYPT. That's the current strongest algorithm supported. This is the BCRYPT crypt algorithm. It produces a 60 character hash as the result.

BCRYPT also allows for you to define a cost parameter in the options array. This allows for you to change the CPU cost of the algorithm:

    $hash = password_hash($password, PASSWORD_BCRYPT, array("cost" => 10));

That's the same as the default. The cost can range from 4 to 31. I would suggest that you use the highest cost that you can, while keeping response time reasonable (I target between 0.1 and 0.5 seconds for a hash, depending on use-case).

Another algorithm name is supported:

    PASSWORD_DEFAULT

This will use the strongest algorithm available to PHP at the current time. Presently, this is the same as specifying PASSWORD_BCRYPT. But in future versions of PHP, it may be updated to use a stronger algorithm if one is introduced. It can also be changed if a problem is identified with the BCRYPT algorithm. Note that if you use this option, you are strongly encouraged to store it in a VARCHAR(255) column to avoid truncation issues if a future algorithm increases the length of the generated hash.

It is very important that you should check the return value of password_hash prior to storing it, because false or null may be returned if it encountered an error.

Verifying Password Hashes

To verify a hash created by password_hash, simply call:

	if (password_verify($password, $hash)) {
		/* Valid */
	} else {
		/* Invalid */
	}

That's all there is to it.

Rehashing Passwords

From time to time you may update your hashing parameters (algorithm, cost, etc). So a function to determine if rehashing is necessary is available:

    if (password_verify($password, $hash)) {
		if (password_needs_rehash($hash, $algorithm, $options)) {
			$hash = password_hash($password, $algorithm, $options);
			/* Store new hash in db */
		}
	}

Security Vulnerabilities

If you have found a security issue, please contact the author directly at ircmaxell@php.net.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot