Download the PHP package legitphp/hash-money without Composer

Hash Money 💰

Cache rules everything around me.

Onions? Eggs? What do you like with your hash?

Hash Money

We're serving up a performance-oriented and opinionated collection of similarity hashing algorithms for PHP. Whether you're comparing images, finding duplicates, or measuring how alike things are - we got you covered. We're riding dirty with php-vips for maximum speed. Get your FFI poppin'.

Features

• 🚀 Multiple Algorithms: Perceptual (pHash), Difference (dHash), Color Histogram, Mashed, Block Mean, and PDQ hashes
• 🧬 Composite Hashes: Concatenate several algorithms into a wider multi-view fingerprint (e.g. 256-bit pHash + dHash + ColorHistogram + BlockMean)
• 🔎 LSH + MIH helpers: Split hashes into band / chunk keys for indexed similarity search at scale
• 🔒 Type Safety: Value objects ensure you can't compare incompatible hashes
• 🎯 Configurable Bit Sizes: 8 / 16 / 32 / 64-bit integer hashes, plus wider 128 / 256-bit hashes via HashValue::fromBytes()
• ⚡ High Performance: Optimized VIPS operations for speed
• 🛠️ Clean API: Simple static methods with full IDE support
• 🧩 Extensible: Strategy pattern makes adding new algorithms easy

Algorithms

Perceptual Hash (pHash)

DCT-based algorithm that's robust to scaling, aspect ratio changes, and minor color variations. Best for finding near-duplicate images.

• Uses Discrete Cosine Transform (DCT)
• More computationally intensive but highly accurate
• Excellent for matching images with color/brightness variations
• Based on the work from VincentChalnot/PerceptualHash

Difference Hash (dHash)

Gradient-based algorithm that's faster than pHash and good at detecting similar images. It works by comparing adjacent pixels to encode the image structure.

• Analyzes gradient changes between adjacent pixels
• Faster computation than pHash
• Good for detecting cropped or slightly modified images
• More sensitive to rotation than pHash

Color Histogram Hash

Color distribution-based algorithm that captures global color patterns in images. Particularly effective for finding images with similar color palettes.

• Uses HSV color space for robustness to illumination changes
• Quantizes colors into bins (8×4×4 by default)
• Excellent for detecting color-shifted or filtered variants
• Complements spatial hashes by focusing on color information
• Enhanced bit distribution: Now uses all 64 bits effectively with proper mixing
• Improved uniqueness: Fixed algorithm provides much better hash diversity

MashedHash 🥔

A comprehensive image fingerprint that "mashes" together multiple image characteristics into a single 64-bit hash. This algorithm analyzes 11 different aspects of an image to create a rich signature that captures both content and style.

Bit Layout (64 bits total):

• Bits 0-3: Colorfulness level (0-15) - Detects grayscale vs vibrant images
• Bits 4-7: Edge density (0-15) - Measures detail and texture complexity
• Bits 8-11: Entropy/complexity (0-15) - Identifies simple vs complex compositions
• Bits 12-14: Aspect ratio class (0-7) - Captures image orientation and format
• Bit 15: Border flag - Detects images with uniform borders (common in social media)
• Bits 16-31: Color distribution (16 bits) - Analyzes RGB channel characteristics
• Bits 32-39: Spatial color layout (8 bits) - Tracks dominant colors by quadrant
• Bits 40-47: Brightness pattern (8 bits) - Encodes luminance distribution
• Bits 48-55: Texture features (8 bits) - Captures directional patterns
• Bits 56-59: Dominant color count (0-15) - Estimates color palette size
• Bits 60-63: Special indicators (4 bits) - Flags for text, uniform regions, etc.

Why use MashedHash?

• Rich metadata: Unlike single-feature hashes, it captures multiple image properties
• Versatile matching: Can identify similar images even with different modifications
• Social media ready: Detects common edits like borders, filters, and crops
• Fast comparison: Despite encoding 11 features, it's still just a 64-bit integer
• Complementary: Works best when combined with pHash or dHash for robust matching

Gray coding note: Ordinal integer fields (colorfulness, edge density, entropy, aspect ratio, RGB channel levels, brightness, texture, dominant colors) are stored in reflected-binary Gray code so adjacent quantization levels differ by exactly one bit. Reading raw bit fields directly sees the Gray-coded representation; use MashedHash::decode($hash) to read semantic values.

Block Mean Hash

Spatial-domain fingerprint: resize the image to a √bits × √bits grayscale grid, compute the mean luminance of the whole grid, then set one bit per cell based on whether that cell is brighter than the overall mean.

• Supports 8 / 16 / 32 / 64 / 128 / 256-bit output
• Retains "where the bright/dark regions live" through luminance changes and JPEG re-encoding
• Statistically independent from pHash (frequency-domain) and dHash (gradient-domain) — ideal as a 4th chunk in a composite hash

PDQ Hash

Industrial-scale 256-bit perceptual hash from Meta ThreatExchange. Closely related to pHash but designed for billions-scale matching:

• Larger output — 256 bits vs. pHash's 64. Far lower birthday-collision rate at scale; you can store millions of hashes without the false-positive drift you'd see at 64 bits.
• Quality metric — alongside the hash, PDQ reports a gradient-derived reliability score in [0, 100]. Meta recommends discarding hashes with quality below 50 (uniform/blurry images, where the median threshold isn't meaningful). Accessible via PdqHash::quality($hash) or $hash->getMetadata('pdq_quality').
• Eight dihedral hashes — PdqHash::hashesFromFile() returns all rotation and flip variants in a single pass.
• Recommended match threshold — Hamming distance ≤ 31 of 256 bits.
• Pipeline — Rec. 601 luminance → two-pass Jarosz 1-D box filter (a tent approximation, Wojciech Jarosz, "Fast Image Convolutions", SIGGRAPH 2001) → 64×64 decimation → 16×16 DCT-II → median threshold.

This is an independent port of Meta's BSD-3-Clause reference. See LICENSE.md for the third-party notice.

Composite Hash

Concatenates several algorithms' 64-bit output into one wider fingerprint with independent signal types in each chunk. The default composition is the 256-bit "quartet" pHash + dHash + ColorHistogram + BlockMean:

Chunk boundaries are preserved in the HashValue's chunks metadata so LSH helpers can band each chunk separately. See the LSH helpers section below.

Requirements

• PHP 8.3+ (64-bit required)
• libvips 8.7+
• php-vips extension 2.5+

Installation

You can install the package via composer:

Installing libvips

Ubuntu/Debian:

macOS:

Then install the PHP extension:

Versioning

Hash Money follows semantic versioning. Pin with "legitphp/hash-money": "^1.1" to take patch releases and additive minor releases automatically while opting in to majors deliberately.

If you're rolling out at scale (~100K+ images), also read PRE_BATCH_REVIEW.md before generating a production dataset — the guide covers version prerequisites, timing calibration, distribution/collision checks, and a go/no-go checklist.

Usage

Basic Usage

Configurable Hash Sizes

Smaller hash sizes are faster to compute and compare but may produce more false positives. Choose based on your needs:

• 64-bit: Best for production use with large image databases
• 32-bit: Good balance for most applications
• 16-bit: Suitable for quick similarity checks
• 8-bit: Only for rough categorization

Type Safety

Configure VIPS

Distance Interpretation

The Hamming distance between two hashes indicates how similar the images are.

Advanced Usage

Working with Hash Values

The HashValue class provides a rich API for working with hash results:

Batch Processing

Performance Optimization

Enhanced HashValue Features

The HashValue class includes advanced features for flexible hash manipulation and storage:

Factory Methods and Serialization

Create HashValue objects from various formats:

Metadata Support

Attach metadata to hash values for richer data management:

Bitwise Analysis

Examine hash properties at the bit level:

Advanced Comparisons

Built-in methods for sophisticated hash comparison:

Scaling to Large Datasets (LSH + MIH)

Once you have millions of hashes in a database, naïve BIT_COUNT(a ^ b) <= k scans become prohibitively slow. Two helpers are provided for building indexed similarity search:

Multi-Index Hashing (MIH) — best for 64-bit hashes, small thresholds

For Hamming threshold k bits on a 64-bit hash, split the hash into m > k equal chunks. Pigeonhole: any two hashes within k bits must have at least one chunk matching exactly. Index each chunk as its own BIGINT column and query with m equality lookups, union the results, then verify the full Hamming distance on the small candidate set:

MIH is typically 2–3 orders of magnitude faster than full-table BIT_COUNT scans for k ≤ 8 on 64-bit hashes. For larger thresholds or wider hashes, use LSH banding instead.

LSH Banding — best for composite / wider hashes

For a wide hash, split into B bands of R bits each. Each band's bytes become a bucket key; two hashes are "candidates" when they share any bucket key. Lsh::bandsByChunk() is composite-aware — it sub-bands each semantic chunk independently so candidates are "matched on at least one of structure, edges, color, or layout":

Tune bands vs. chunks against your dataset — more bands raises recall but inflates the candidate set. A reasonable starting point for a 256-bit composite is 16 bands (B=16, R=16 → 65,536 buckets per band).

Candidate-filtering is usually done in the database; see docs/LARAVEL_BRIDGE.md for a proposed Laravel package that wires all of this (Eloquent cast, migrations, scopes, pluggable MySQL-chunked / MySQL-banded drivers) on top of this library.

Real-World Examples

Database Storage Pattern

Store and retrieve hashes efficiently:

API Integration

Send and receive hashes via APIs:

Duplicate Detection System

Build a complete duplicate detection workflow:

Example Scripts and Benchmarks

Hash Generation Example

The package includes a comprehensive example script for testing hash generation:

Testing

Run the test suite using Pest:

For code formatting:

Performance Considerations

• DHash is typically 2-3x faster than Perceptual Hash
• Color Histogram Hash is comparable to DHash in speed
• MashedHash is slightly slower but provides the richest feature set
• PDQ is the slowest of the algorithms (~150–200 ms/image at the default 512×512 working size) — the Jarosz tent filter and 16×16 DCT run in pure PHP, not libvips. Tune via PdqHash::configure(['workingSize' => 256]) to halve the cost at the expense of less Jarosz blur. Worth the headroom for production near-dup detection where 256-bit signal and quality filtering matter.
• Smaller bit sizes compute faster but may reduce accuracy
• VIPS caching significantly improves performance for batch operations
• The package automatically detects CPU cores for optimal concurrency

Rolling Out at Scale

Before generating hashes for a large production dataset (~100K images or more), run the calibration and validation steps in PRE_BATCH_REVIEW.md inside your consumer project. The guide covers version prerequisites, timing extrapolation, hash-distribution sanity checks, known-pair validation, failure-mode probes, database/query-plan review, and a go/no-go checklist. It's intended to be executable by either a human operator or an AI coding agent working in the consumer repo, and produces a single report that justifies the decision to run the full batch.

Use Cases

• Duplicate Detection: Find exact or near-duplicate images in large collections
• Content Moderation: Detect previously flagged images even after modifications
• Image Organization: Group similar images automatically
• Copyright Protection: Identify unauthorized use of images
• Quality Control: Detect corrupted or incorrectly processed images

Choosing the Right Hash

Recommended Combinations

For social media images:

For copyright detection:

For large-scale similarity search with LSH:

For industrial-scale near-duplicate detection with PDQ:

PDQ produces a 256-bit HashValue directly — no getValue()-style int accessor; use toHex(), getBytes(), or toBase64() for storage. Wide LSH banding works exactly like for CompositeHash outputs: pass the HashValue to Lsh::bands($hash, $bandCount).

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Mike Ferrara
• Vincent Chalnot
• Jens Segers
• Anatoly Pashin
• jcupitt
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Acknowledgments

Special thanks to the authors and contributors of the libraries that made this package possible, particularly the VIPS team for their incredible image processing library.