SimHashPHP

Install the library using Composer to manage dependencies in your PHP project.

composer require tga/simhash-php

The String32Tokenizer implements the following methods:

• tokenize(string $element): string: Converts the input string into a 32-character hexadecimal token using crc32b hashing.
• supportsElement(mixed $element): bool: Returns true if the element is a string.
• supportsSize(int $size): bool: Returns true only if the requested token size is exactly 32.

The SimpleTextExtractor class implements ExtractorInterface and provides a simple way to split a string into an array of words. It works by slugifying the input text (converting it to a URL-friendly format) and then splitting the resulting string by the hyphen (-) character. This is useful for preparing plain text for similarity hash computation.

use Tga\SimHash\Extractor\SimpleTextExtractor;

$extractor = new SimpleTextExtractor();
$words = $extractor->extract("Hello World! This is a test.");
// Result will be an array of slugified words: ['hello', 'world', 'this', 'is', 'a', 'test']

The String64Tokenizer is an implementation of TokenizerInterface designed to process strings into 64-bit tokens. It uses the CRC64 algorithm to generate a hash and returns the result as a 64-character binary string (padded with zeros) representing the bit sequence.

This tokenizer is suitable when your SimHash implementation requires fixed-size 64-bit tokens derived from string elements.

use Tga\SimHash\Tokenizer\String64Tokenizer;

$tokenizer = new String64Tokenizer();
$token = $tokenizer->tokenize("your string here");
// $token is a 64-character string of '0's and '1's

The Fingerprint class provides methods to export the hash into different formats:

• getBinary(): Returns the binary representation as a string, padded with leading zeros to match the specified $size.
• getDecimal(): Returns the fingerprint as a float.
• getHexa(): Returns the hexadecimal representation as a string.
• __toString(): Automatically returns the binary string representation when the object is cast to a string.

The GaussianComparator implements the ComparatorInterface and calculates a similarity index between 0 and 1 based on a Gaussian distribution. It measures how many bits differ between two fingerprints and maps that difference to a probability density.

Usage

1. Instantiate the comparator with a $deviation (default is 4). The deviation controls the sensitivity of the similarity score.
2. Call compare(Fingerprint $fp1, Fingerprint $fp2).

Constraints

• Both Fingerprint objects must have the same size. If they differ, a \LogicException is thrown.

use Tga\SimHash\Comparator\GaussianComparator;

// Initialize with a deviation of 4 (default)
$comparator = new GaussianComparator(4);

// Compare two fingerprints to get a similarity index between 0 and 1
$similarity = $comparator->compare($fingerprint1, $fingerprint2);

The SimHash class allows you to extend its behavior by providing your own implementations of the TokenizerInterface and VectorizerInterface.

• Tokenizers: Use addTokenizer(Tokenizer\TokenizerInterface $tokenizer) to add a new tokenizer to the internal stack. The class iterates through tokenizers and selects the first one that satisfies supportsElement($element) and supportsSize($size).
• Vectorizer: Use setVectorizer(Vectorizer\VectorizerInterface $vectorizer) to replace the default vectorizer with your own implementation.

use Tga\SimHash\SimHash;
use Tga\SimHash\Tokenizer\TokenizerInterface;
use Tga\SimHash\Vectorizer\VectorizerInterface;

$simhash = new SimHash();

// Inject a custom tokenizer
$simhash->addTokenizer($myCustomTokenizer);

// Inject a custom vectorizer
$simhash->setVectorizer($myCustomVectorizer);

The DefaultVectorizer is the standard implementation of the VectorizerInterface. It converts an array of tokens into a numerical vector of a specified size.

It works by:

1. Calculating weights for each token based on their frequency in the input array (more frequent tokens have higher weights).
2. Iterating through the weighted tokens and updating a vector of length $size.
3. For each bit in a token: if the bit is '1', the weight is added to the vector at that index; if the bit is '0', the weight is subtracted.

This produces a weighted vector suitable for SimHash calculations.

use Tga\SimHash\Vectorizer\DefaultVectorizer;

$vectorizer = new DefaultVectorizer();
$tokens = ['1010', '1100', '1010'];
$size = 4;

$vector = $vectorizer->vectorize($tokens, $size);

The String32Tokenizer is an implementation of TokenizerInterface designed to process strings into 32-bit tokens. It uses the crc32b hash algorithm and returns a 32-character hexadecimal string (padded with leading zeros).

Use this tokenizer when your SimHash implementation requires fixed-size 32-bit tokens derived from string elements.

use Tga\
SimHash\
Tokenizer\
String32Tokenizer;

$tokenizer = new String32Tokenizer();
$token = $tokenizer->tokenize("your string here");
// Returns a 32-character hex string