https://github.com/mistralys/variable-hasher
PHP utility that can be used to create a hash of an arbitrary set of variables.
https://github.com/mistralys/variable-hasher
caching hashing php
Last synced: 7 months ago
JSON representation
PHP utility that can be used to create a hash of an arbitrary set of variables.
- Host: GitHub
- URL: https://github.com/mistralys/variable-hasher
- Owner: Mistralys
- License: mit
- Created: 2025-09-02T12:58:02.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-02T14:34:24.000Z (11 months ago)
- Last Synced: 2025-09-02T19:43:54.331Z (11 months ago)
- Topics: caching, hashing, php
- Language: PHP
- Homepage:
- Size: 31.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
# Variable hasher
PHP utility that can be used to create a hash of an arbitrary set of variables
to use for runtime caching. It has better performance than serializing the
variables and hashing the result, especially when objects and resources are
involved.
## Requirements
- PHP 8.4 or higher
- [Composer](https://getcomposer.org/) for installation
## Installation
Use Composer to add the dependency to your project:
```bash
composer require mistralys/variable-hasher
```
## Quick start
Any kind of variable can be passed in, from primitives (int, float, string) to
objects and resources, or arrays containing any of these - indexed or associative.
```php
use Mistralys\VariableHasher\VariableHasher;
$intHash = VariableHasher::create(123)->getHash();
$multiHash = VariableHasher::create(123, 'string', 45.67, new stdClass())->getHash();
$array = array(
'key' => 'value',
'another_key' => 123,
'object' => new stdClass()
);
$arrayHash = VariableHasher::create($array)->getHash();
```
## Real-life example
Consider a factory method that creates objects based on a set of parameters.
The same instances must be returned if the same parameters are passed in again.
```php
use Mistralys\VariableHasher\VariableHasher;
class MyObjectFactory
{
private array $instances = array();
public function create(array $params) : MyObject
{
$hash = VariableHasher::create($params)->getHash();
if(isset($this->instances[$hash])) {
return $this->instances[$hash];
}
$instance = new MyObject($params);
$this->instances[$hash] = $instance;
return $instance;
}
}
```
## Order-independence
The order of the variables you pass in does not matter. The same hash will be
generated regardless of the order if the variables are the same.
To illustrate, the following will generate the same hash:
```php
use Mistralys\VariableHasher\VariableHasher;
$hash1 = VariableHasher::create('a', 'b', 'c')->getHash();
$hash2 = VariableHasher::create('c', 'b', 'a')->getHash();
assert($hash1 === $hash2);
```
## Choosing the hash algorithm
By default, MD5 is used to generate the hash. If you need a different algorithm,
you can specify any valid algorithm supported by PHP's `hash()` function.
```php
use Mistralys\VariableHasher\HashingAlgorithms;
use Mistralys\VariableHasher\VariableHasher;
$hash = VariableHasher::create('a', 'b', 'c')
->setAlgorithm(HashingAlgorithms::HASH_SHA3_256)
->getHash();
```
In the example above, the algorithm is set using one of the provided constants.
You can specify any valid algorithm as a string:
```php
use Mistralys\VariableHasher\VariableHasher;
$hash = VariableHasher::create('a', 'b', 'c')
->setAlgorithm('murmur3f') // requires `php-murmurhash` extension
->getHash();
```
> NOTE: The `HashingAlgorithms` class is provided for convenience. It contains
> constants for all algorithms that you can rely on being supported by PHP 8.4
> without having to check `hash_algos()`.
## Get the raw hashing string
If you want to see the raw string that is hashed, you can set the algorithm to
none, which will return the string instead of a hash.
```php
use Mistralys\VariableHasher\HashingAlgorithms;
use Mistralys\VariableHasher\VariableHasher;
$rawString = VariableHasher::create('a', 'b', 'c')
->setAlgorithm(HashingAlgorithms::HASH_NONE)
->getHash();
```
## Memory handling
The arguments are stored internally until you request the hash.
This means that if you pass in large variables, they will remain in memory
until the object is destroyed if you do not request it.
## Warning: Runtime use only
The hashing uses object and resource IDs for performance reasons, which are not
persistent between requests. As a result, the generated hashes cannot be used to
identify a set of variables if it contains objects or resources.
If you need a persistent hash, you should use a different method, such as encoding
the objects to JSON and generating a hash of this serialized data.