PHPackages                             randomphp/hashing - 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. [Security](/categories/security)
4. /
5. randomphp/hashing

ActiveLibrary[Security](/categories/security)

randomphp/hashing
=================

A small, dependency-light PHP library that wraps PHP’s built-in password\_hash() / password\_verify() functions.

1.0.2(4mo ago)00UNLICENSEPHPPHP >=8.4

Since Feb 15Pushed 4mo agoCompare

[ Source](https://codeberg.org/RandomPHP/hashing.git)[ Packagist](https://packagist.org/packages/randomphp/hashing)[ RSS](/packages/randomphp-hashing/feed)WikiDiscussions master Synced today

READMEChangelog (3)Dependencies (1)Versions (4)Used By (0)

[![RandomPHP](./assets/randomphp_text.png)](./assets/randomphp_text.png)

RandomPHP Hashing
=================

[](#randomphp-hashing)

A small, dependency-light PHP library that wraps PHP’s built-in [password\_hash()](https://www.php.net/manual/en/function.password-hash.php) / [password\_verify()](https://www.php.net/manual/en/function.password-verify.php) functions with:

- Strongly-typed hash objects (`HashInterface`)
- Algorithm objects you can pass around (`HashingAlgorithmInterface`)
- Automatic algorithm detection from an existing hash string
- A “needs rehash” workflow
- Optional Doctrine DBAL type for mapping hashes to value objects

Supported algorithms out of the box:

- **Argon2id** (`PASSWORD_ARGON2ID`)
- **Argon2i** (`PASSWORD_ARGON2I`)
- **bcrypt** (`PASSWORD_BCRYPT`)

---

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

[](#requirements)

- **PHP 8.4+**
- PHP must be compiled with the relevant password algorithms:
    - bcrypt is generally always available
    - Argon2 support depends on your PHP build (if unavailable, `password_hash()` will fail for Argon2)

Optional:

- **doctrine/dbal** (only if you want the `HashType` DBAL type)

---

Installation
------------

[](#installation)

Install via Composer:

```
composer require randomphp/hashing
```

---

Basic usage
-----------

[](#basic-usage)

### Hash a password

[](#hash-a-password)

Pick an algorithm, hash a clear-text password, and store the resulting string:

```
use RandomPHP\Hashing\Algorithm\Argon2IDHashingAlgorithm;

$algo = Argon2IDHashingAlgorithm::make(
    memory: 65536,     // kibibytes
    iterations: 4,
    parallelism: 2,
);

$hash = $algo->hash($password);

// Store as string:
$stored = $hash->toString(); // or (string)$hash
```

### Verify a password

[](#verify-a-password)

Turn the stored string back into a `Hash` value object and verify:

```
use RandomPHP\Hashing\Hash;

$hash = Hash::make($stored);

if ($hash->verify($passwordAttempt)) {
    // ok
}
```

`Hash::make()` automatically detects the algorithm **from the hash string** and attaches the decoded algorithm instance to the hash.

### Rehash when parameters change

[](#rehash-when-parameters-change)

If you update your hashing parameters, you can check whether an existing hash should be rehashed:

```
use RandomPHP\Hashing\Algorithm\Argon2IDHashingAlgorithm;
use RandomPHP\Hashing\Hash;

$hash = Hash::make($stored);

$newAlgo = Argon2IDHashingAlgorithm::make(
    memory: 131072,
    iterations: 4,
    parallelism: 2,
);

if (!$hash->verify($passwordAttempt)) {
    // Do not continue the password did not match the hash.
}

if ($hash->needsRehash($newAlgo)) {
    $rehash = $newAlgo->hash($passwordAttempt);
    $stored = $rehash->toString(); // replace stored hash
}
```

`needsRehash()` is implemented by comparing the decoded algorithm parameters to your desired algorithm via `HashingAlgorithmInterface::match()`.

---

Algorithms
----------

[](#algorithms)

### Argon2id / Argon2i

[](#argon2id--argon2i)

```
use RandomPHP\Hashing\Algorithm\Argon2IDHashingAlgorithm;
use RandomPHP\Hashing\Algorithm\Argon2IHashingAlgorithm;

$argon2id = Argon2IDHashingAlgorithm::make(65536, 4, 2);
$argon2i  = Argon2IHashingAlgorithm::make(65536, 4, 2);
```

Notes:

- Internally the library relies on PHP’s `password_hash()` and `password_verify()`.
- When decoding an Argon2 hash, the library parses:
    - version (`v=...`)
    - memory cost (`m=...`)
    - time cost / iterations (`t=...`)
    - parallelism / threads (`p=...`)
    - salt length and key length (derived from the base64 parts)

### bcrypt

[](#bcrypt)

```
use RandomPHP\Hashing\Algorithm\BcryptHashingAlgorithm;

$bcrypt = BcryptHashingAlgorithm::make(cost: 12);
```

When decoding, bcrypt hashes are recognized via the prefix (e.g. `$2y$12$...`) and the cost is extracted.

---

Working with untrusted hash strings
-----------------------------------

[](#working-with-untrusted-hash-strings)

This library keeps a small in-memory cache of algorithm instances (`AlgoCache`) so identical parameter sets don’t create multiple objects.

If you are decoding hashes coming from an **untrusted** source (for example: user input, external payloads), you should disable the cache to avoid unbounded growth:

```
use RandomPHP\Hashing\AlgoCache;
use RandomPHP\Hashing\Hash;

$hash = AlgoCache::disabled(fn () => Hash::make($untrustedHashString));
```

You can also toggle it globally:

```
use RandomPHP\Hashing\AlgoCache;

AlgoCache::toggle(false); // disable
AlgoCache::toggle(true);  // enable
```

---

Serialization
-------------

[](#serialization)

- `Hash` implements `Stringable` and `JsonSerializable`.
    - Casting to string returns the hash string
    - `json_encode($hash)` serializes as the hash string

Algorithm instances can be serialized to arrays:

```
$payload = $algo->toArray();
$restored = $algo::fromArray($payload); // returns an algorithm instance or null
```

---

Doctrine DBAL integration
-------------------------

[](#doctrine-dbal-integration)

If you use Doctrine DBAL, the library includes a custom type:

- `RandomPHP\Hashing\Doctrine\HashType`
- Type name: `hash`

Register the type (example):

```
use Doctrine\DBAL\Types\Type;
use RandomPHP\Hashing\Doctrine\HashType;

if (!Type::hasType(HashType::NAME)) {
    Type::addType(HashType::NAME, HashType::class);
}
```

Then map your column as a string type with the `hash` DBAL type and use `HashInterface` in your entities/DTOs. The type will:

- Convert DB values (string) to `Hash::make($value)`
- Convert PHP values (`HashInterface` or string) back to the DB string

---

Extending: custom algorithms
----------------------------

[](#extending-custom-algorithms)

You can add your own `HashingAlgorithmInterface` implementation and register it so `Hash::make()` can detect it:

```
use RandomPHP\Hashing\Hash;

Hash::registerAlgorithm(MyCustomAlgorithm::class);
```

Your algorithm must implement the [HashingAlgorithmInterface](./src/Interface/HashingAlgorithmInterface.php)

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance75

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~1 days

Total

3

Last Release

136d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/3b609f3ed19dc97ded31d443bdc4ff2f391b51da426c664782c79bb195bc64c9?d=identicon)[sicet7](/maintainers/sicet7)

---

Top Contributors

[![sicet7](https://avatars.githubusercontent.com/u/7220364?v=4)](https://github.com/sicet7 "sicet7 (5 commits)")

---

Tags

argon2argon2idbcrypthashhashingphpphp-libraryphp8

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/randomphp-hashing/health.svg)

```
[![Health](https://phpackages.com/badges/randomphp-hashing/health.svg)](https://phpackages.com/packages/randomphp-hashing)
```

###  Alternatives

[mews/purifier

Laravel 5/6/7/8/9/10 HtmlPurifier Package

2.0k18.7M142](/packages/mews-purifier)[paragonie/ecc

PHP Elliptic Curve Cryptography library

24820.0k37](/packages/paragonie-ecc)

PHPackages © 2026

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