README

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 for installation

Installation

Use Composer to add the dependency to your project:

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.

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.

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:

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.

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:

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.

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.

mistralys / variable-hasher

Maintainers

Details