Download the PHP package legitphp/hash-money without Composer
On this page you can find all versions of the php package legitphp/hash-money. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download legitphp/hash-money
More information about legitphp/hash-money
Files in legitphp/hash-money
Package hash-money
Short Description A performance-oriented PHP package for image hashing algorithms using VIPS.
License MIT
Homepage https://github.com/mferrara/hash-money
Informations about the package hash-money
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 Hash (pHash), Difference Hash (dHash), and Color Histogram Hash
- 🔒 Type Safety: Value objects ensure you can't compare incompatible hashes
- 🎯 Configurable Bit Sizes: Support for 8, 16, 32, and 64-bit hashes
- ⚡ 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
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
Requirements
Installation
You can install the package via composer:
Installing libvips
Ubuntu/Debian:
macOS:
Then install the PHP extension:
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
Batch Processing
Performance Optimization
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
- 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
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
Hash Type | Best For | Speed | Key Features |
---|---|---|---|
pHash | Near-duplicate detection, scaled/compressed variants | Medium | Robust to compression, scaling, minor edits |
dHash | Quick similarity checks, cropped images | Fast | Good for crops, sensitive to rotation |
ColorHistogram | Color-based matching, filter detection | Fast | Catches recolored/filtered versions |
MashedHash | Comprehensive matching, reducing false positives | Medium | 11 features including borders, textures, layout |
Recommended Combinations
For social media images:
For copyright detection:
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.