PHPackages                             brenno-duarte/php-secure-password - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. brenno-duarte/php-secure-password

ActiveLibrary

brenno-duarte/php-secure-password
=================================

SecurePassword is a PHP component for creating strong passwords using modern encryption.

3.1.4(1y ago)393↓100%1MITPHPPHP ^8.2

Since Apr 17Pushed 10mo ago1 watchersCompare

[ Source](https://github.com/brenno-duarte/php-secure-password)[ Packagist](https://packagist.org/packages/brenno-duarte/php-secure-password)[ RSS](/packages/brenno-duarte-php-secure-password/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (2)Versions (13)Used By (1)

PHP SecurePassword
==================

[](#php-securepassword)

SecurePassword is a PHP component for creating strong passwords using modern encryption.

Why use this component?
-----------------------

[](#why-use-this-component)

Unlike just using `password_hash` or `password_verify`, SecurePassword adds a secret entry (commonly called a pepper) to make it difficult to break the generated hash.

Requirements
------------

[](#requirements)

PHP >= 8.2

Installing via Composer
-----------------------

[](#installing-via-composer)

```
composer require brenno-duarte/php-secure-password

```

How to use
----------

[](#how-to-use)

The code below shows an example for creating the hash. The `createHash` method generates the password hash along with the "peeper", and the `getHash` method returns the generated hash.

```
use SecurePassword\SecurePassword;

$password = new SecurePassword();
$hash = $password->createHash('my_password')->getHash();

/** Return string */
var_dump($hash);
```

Settings
--------

[](#settings)

You can change encryption settings without using the methods that will be listed below. To do this, enter the following code in the constructor:

```
use SecurePassword\AlgorithmEnum;

$config = [
    'algo' => AlgorithmEnum::DEFAULT,
    'cost' => 12,
    'memory_cost' => PASSWORD_ARGON2_DEFAULT_MEMORY_COST,
    'time_cost' => PASSWORD_ARGON2_DEFAULT_TIME_COST,
    'threads' => PASSWORD_ARGON2_DEFAULT_THREADS
];

$password = new SecurePassword($config);
```

You can use the following encryptions: `AlgorithmEnum::DEFAULT`, `AlgorithmEnum::BCRYPT`, `AlgorithmEnum::ARGON2I`, `AlgorithmEnum::ARGON2ID`.

Changing the encryption algorithm
---------------------------------

[](#changing-the-encryption-algorithm)

**NOTE: If you are using the settings passed in the constructor then you can ignore the code below.**

You can change the type of algorithm used to generate the hash. It is possible to use `PASSWORD_BCRYPT`,` PASSWORD_ARGON2I`, `PASSWORD_ARGON2ID` and even `PASSWORD_DEFAULT`.

- `useDefault()` will use standard encryption
- `useBcrypt()` will use Bcrypt encryption
- `useArgon2()` will use Argon2 encryption
- `useArgon2(true)` passing `true` will use Argon2d encryption

```
# standard encryption
$hash = $password->useDefault()->createHash('my_password')->getHash();

# Bcrypt encryption
$hash = $password->useBcrypt()->createHash('my_password')->getHash();

# Argon2 encryption
$hash = $password->useArgon2()->createHash('my_password')->getHash();

# Argon2d encryption (with `true`)
$hash = $password->useArgon2(true)->createHash('my_password')->getHash();
```

If the type of algorithm is not provided, the default encryption will be 'PASSWORD\_DEFAULT'.

Returns information about the given hash
----------------------------------------

[](#returns-information-about-the-given-hash)

To return the information of the created hash, use `getHashInfo` method.

```
$hash = $password->createHash('my_password')->getHashInfo();

/** Return array */
var_dump($hash);
```

Verifies that a password matches a hash
---------------------------------------

[](#verifies-that-a-password-matches-a-hash)

To verify that the hash generated with `createHash` is valid, you can use `verifyHash` in two ways:

```
# First way
$hash = $password->createHash('my_password')->getHash();
$res = $password->verifyHash('my_password', $hash);

# Second way
$hash = $password->createHash('my_password')->verifyHash();

/** Return bool */
var_dump($res);
```

To make timing attacks more difficult, the `verifyHash` method waits 0.25 seconds (250000 microseconds) to return the value. You can change this time by changing the third parameter.

```
# First way
$hash = $password->createHash('my_password')->getHash();
$res = $password->verifyHash('my_password', $hash, 300000);

# Second way
$hash = $password->createHash('my_password')->verifyHash(wait_microseconds: 300000);

/** Return bool */
var_dump($res);
```

**NOTE: If you are using the settings passed in the constructor then you can ignore the code below.**

You can change the type of algorithm that will be used to check the hash.

```
$hash = $password->useArgon2()->createHash('my_password')->getHash();
$res = $password->useArgon2()->verifyHash('my_password', $hash);

/** Return bool */
var_dump($res);
```

Needs Rehash
------------

[](#needs-rehash)

If the encryption type has been changed, you can generate a new hash with the new encryption. The `needsHash()` method checks whether the reported hash needs to be regenerated. Otherwise, it will return `false`.

**Example 1**

```
$password = new SecurePassword();
$hash = $password->useArgon2()->createHash('my_password')->getHash();
$needs = $password->useDefault()->needsRehash('my_password', $hash);

/** Return string */
var_dump($needs);
```

**Example 2**

```
$hash = $password->createHash('my_password')->getHash();

$password = new SecurePassword([
    'algo' => AlgorithmEnum::BCRYPT
]);
$needs = $password->needsRehash('my_password', $hash);

/** Return false */
var_dump($needs);
```

Adding options
--------------

[](#adding-options)

**NOTE: If you are using the settings passed in the constructor then you can ignore the code below.**

Add options in the `useDefault`, `useBcrypt` and `useArgon2` methods.

- useDefault: default options, use an array.
- useBcrypt: you can change `$cost`. The default is `12`.
- useArgon2: you can change `$memory_cost`, `$time_cost` and `$threads`. The default is the constants `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`, `PASSWORD_ARGON2_DEFAULT_TIME_COST` and `PASSWORD_ARGON2_DEFAULT_THREADS`.

```
# standard encryption
$hash = $password->useDefault([])->createHash('my_password');

# Bcrypt encryption
$hash = $password->useBcrypt(12)->createHash('my_password');

# Argon2 encryption
$hash = $password->useArgon2(false, PASSWORD_ARGON2_DEFAULT_MEMORY_COST, PASSWORD_ARGON2_DEFAULT_TIME_COST, PASSWORD_ARGON2_DEFAULT_THREADS)->createHash('my_password');

# Argon2d encryption (with `true`)
$hash = $password->useArgon2(true, PASSWORD_ARGON2_DEFAULT_MEMORY_COST, PASSWORD_ARGON2_DEFAULT_TIME_COST, PASSWORD_ARGON2_DEFAULT_THREADS)->createHash('my_password');
```

Using OpenSSL and Sodium encryption
-----------------------------------

[](#using-openssl-and-sodium-encryption)

Secure Password has the component [paragonie/sodium\_compat](https://github.com/paragonie/sodium_compat). Therefore, it is not necessary to use the Sodium library in PECL format.

You can use OpenSSL and Sodium encryption using the `Encryption` class:

```
use SecurePassword\Encrypt\Encryption;

$encryption = new Encryption('your-key');

//Encrypt the message
$encrypt = $encryption->encrypt("This is a text");
echo $encrypt;
```

You can decrypt token by calling decrypt method:

```
$encryption = new Encryption('your-key');

//Decrypt the message
$decrypt = $encryption->decrypt($encrypt);
echo $decrypt;
```

You can pass supported adapter to class like:

**Use of OpenSSL**

```
$encryption = new Encryption(new OpenSslEncryption('your-key'));
```

**Use of Sodium**

```
$encryption = new Encryption(new SodiumEncryption('your-key'));
```

Default openSSL will use, you can use any one you want.

Changing the secret entry (recommended)
---------------------------------------

[](#changing-the-secret-entry-recommended)

It is recommended to change the secret entry (or pepper) that will be added to your password. Use `setPepper` to change.

```
$password = new SecurePassword();
$password->setPepper('new_pepper');
```

By default, the `setPepper` method uses OpenSSL encryption. However, you can use Sodium encryption if you want.

```
// Use OpenSSL
$password->setPepper('new_pepper', 'openssl');

// Use Sodium
$password->setPepper('new_pepper', 'sodium');
```

Getting the ideal encryption cost
---------------------------------

[](#getting-the-ideal-encryption-cost)

Here's a quick little function that will help you determine what cost parameter you should be using for your server to make sure you are within this range.

```
$optimal_cost = SecurePassword::getOptimalBcryptCost('my_password');

$password = new SecurePassword([
    'cost' => $optimal_cost
]);
$hash = $password->createHash('my_password')->getHash();
```

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance46

Moderate activity, may be stable

Popularity16

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 81.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~113 days

Recently: every ~56 days

Total

12

Last Release

605d ago

Major Versions

0.2.0 → 1.0.02021-10-12

1.0.1 → 2.0.02022-09-21

2.0.0 → 3.0.02023-11-11

PHP version history (3 changes)0.1.0PHP ^7.3|8.0

2.0.0PHP >=8.0

3.0.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/3b4643dd44cd0ca52917d341a3eb9ab4de7328ff2c2c2c227080c39f6a5606dc?d=identicon)[brenno-duarte](/maintainers/brenno-duarte)

---

Top Contributors

[![brenno-duarte](https://avatars.githubusercontent.com/u/32854266?v=4)](https://github.com/brenno-duarte "brenno-duarte (18 commits)")[![solital](https://avatars.githubusercontent.com/u/63726882?v=4)](https://github.com/solital "solital (4 commits)")

---

Tags

phpphp-passphp-passwordphp-securityphpphp-securityphp-password

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/brenno-duarte-php-secure-password/health.svg)

```
[![Health](https://phpackages.com/badges/brenno-duarte-php-secure-password/health.svg)](https://phpackages.com/packages/brenno-duarte-php-secure-password)
```

###  Alternatives

[pestphp/pest-plugin-stressless

Stressless plugin for Pest

67792.6k16](/packages/pestphp-pest-plugin-stressless)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)