• Stars
    star
    1,940
  • Rank 22,738 (Top 0.5 %)
  • Language
    PHP
  • License
    MIT License
  • Created over 9 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

๐ŸŒ„ Perceptual image hashing for PHP

ImageHash

Latest Stable Version Build Status Coverage Status Donate

A perceptual hash is a fingerprint of a multimedia file derived from various features from its content. Unlike cryptographic hash functions which rely on the avalanche effect of small changes in input leading to drastic changes in the output, perceptual hashes are "close" to one another if the features are similar.

Perceptual hashes are a different concept compared to cryptographic hash functions like MD5 and SHA1. With cryptographic hashes, the hash values are random. The data used to generate the hash acts like a random seed, so the same data will generate the same result, but different data will create different results. Comparing two SHA1 hash values really only tells you two things. If the hashes are different, then the data is different. And if the hashes are the same, then the data is likely the same. In contrast, perceptual hashes can be compared -- giving you a sense of similarity between the two data sets.

This code was inspired/based on:

Requirements

  • PHP 7.1 or higher
  • The gd or imagick extension
  • Optionally, install the GMP extension for faster fingerprint comparisons

Installation

This package has not reached a stable version yet, backwards compatibility may be broken between 0.x releases. Make sure to lock your version if you intend to use this in production!

Install using composer:

composer require jenssegers/imagehash

Usage

The library comes with 4 built-in hashing implementations:

  • Jenssegers\ImageHash\Implementations\AverageHash - Hash based the average image color
  • Jenssegers\ImageHash\Implementations\DifferenceHash - Hash based on the previous pixel
  • Jenssegers\ImageHash\Implementations\BlockHash - Hash based on blockhash.io Still under development
  • Jenssegers\ImageHash\Implementations\PerceptualHash - The original pHash Still under development

Choose one of these implementations. If you don't know which one to use, try the DifferenceHash implementation. Some implementations allow some configuration, be sure to check the constructor.

use Jenssegers\ImageHash\ImageHash;
use Jenssegers\ImageHash\Implementations\DifferenceHash;

$hasher = new ImageHash(new DifferenceHash());
$hash = $hasher->hash('path/to/image.jpg');

echo $hash;
// or
echo $hash->toHex();

The resulting Hash object, is a hexadecimal image fingerprint that can be stored in your database once calculated. The hamming distance is used to compare two image fingerprints for similarities. Low distance values will indicate that the images are similar or the same, high distance values indicate that the images are different. Use the following method to detect if images are similar or not:

$distance = $hasher->distance($hash1, $hash2);
// or
$distance = $hash1->distance($hash2);

Equal images will not always have a distance of 0, so you will need to decide at which distance you will evaluate images as equal. For the image set that I tested, a max distance of 5 was acceptable. But this will depend on the implementation, the images and the number of images. For example; when comparing a small set of images, a lower maximum distances should be acceptable as the chances of false positives are quite low. If however you are comparing a large amount of images, 5 might already be too much.

The Hash object can return the internal binary hash in a couple of different format:

echo $hash->toHex(); // 7878787c7c707c3c
echo $hash->toBits(); // 0111100001111000011110000111110001111100011100000111110000111100
echo $hash->toInt(); // 8680820757815655484
echo $hash->toBytes(); // "\x0F\x07ฦ’ฦ’\x03\x0F\x07\x00"

Choose your preference for storing your hashes in your database. If you want to reconstruct a Hash object from a previous calculated value, use:

$hash = Hash::fromHex('7878787c7c707c3c');
$hash = Hash::fromBin('0111100001111000011110000111110001111100011100000111110000111100');
$hash = Hash::fromInt('8680820757815655484');

Demo

These images are similar:

Equals1 Equals2

Image 1 hash: 3c3e0e1a3a1e1e1e (0011110000111110000011100001101000111010000111100001111000011110)
Image 2 hash: 3c3e0e3e3e1e1e1e (0011110000111110000011100011111000111110000111100001111000011110)
Hamming distance: 3

These images are different:

Equals1 Equals2

Image 1 hash: 69684858535b7575 (0010100010101000101010001010100010101011001010110101011100110111)
Image 2 hash: e1e1e2a7bbaf6faf (0111000011110000111100101101001101011011011101010011010101001111)
Hamming distance: 32

Security contact information

To report a security vulnerability, follow these steps.

More Repositories

1

agent

๐Ÿ‘ฎ A PHP desktop/mobile user agent parser with support for Laravel, based on Mobiledetect
PHP
4,417
star
2

date

๐Ÿ—“ A library to help you work with dates in multiple languages, based on Carbon.
PHP
1,813
star
3

optimus

๐Ÿค– Id obfuscation based on Knuth's multiplicative hashing method for PHP.
PHP
1,254
star
4

php-proxy

A PHP proxy script with https and post support
PHP
922
star
5

blade

๐Ÿ”ช A standalone version of Laravel's Blade templating engine for use outside of Laravel.
PHP
752
star
6

model

This model provides an eloquent-like base class that can be used to build custom models in Laravel and other frameworks
PHP
348
star
7

RTL8188-hostapd

hostapd for Realtek RTL8188
C
334
star
8

laravel-rollbar

Rollbar error monitoring integration for Laravel projects
PHP
333
star
9

laravel-ab

A server-side A/B testing tool for Laravel.
PHP
285
star
10

captain

โš“๏ธ Easily start and stop docker compose projects
Go
231
star
11

codeigniter-hmvc-modules

Create HMVC modules with this lightweight extension for Codeiginter 2
PHP
187
star
12

codeigniter-advanced-images

Resize and crop images on the fly
PHP
181
star
13

dashboard

A server dashboard for Ubuntu
PHP
136
star
14

codeigniter-template-library

A template library for Codeigniter
PHP
107
star
15

laravel-raven

Sentry (Raven) error monitoring integration for Laravel projects
PHP
91
star
16

laravel-mongodb-session

A MongoDB session driver for Laravel
PHP
75
star
17

codeigniter-authentication-library

A secure authentication library for CodeIgniter
PHP
67
star
18

laravel-oauth

A Laravel OAuth 1 & 2 library
PHP
65
star
19

laravel-mongodb-sentry

An extension for Laravel-MongoDB that lets you work with Sentry
PHP
53
star
20

codeigniter-message-library

Store and display error or information messages to display on the current page or next page
PHP
51
star
21

lean

Use the PHP League's Container package with auto-wiring support as the core container in Slim 3
PHP
31
star
22

laravel-mongodb-core

A MongoDB based query builder for Laravel
PHP
25
star
23

php-chef

Opscode Chef API PHP library
PHP
20
star
24

chef-patch

Helps you replace text and lines in files from Chef recipes.
Ruby
20
star
25

palenight.zsh-theme

My custom zsh theme
13
star
26

laravel-mongodb-lite

A lightweight MongoDB database library and model for Laravel 4
PHP
11
star
27

vagrant

My personal Vagrant development environment
HTML
7
star
28

docker

My personal Docker setup
5
star
29

docker-php-cs-fixer

A tool to automatically fix PHP coding standards issues
4
star
30

quotebot

Quotebot for slack
TypeScript
4
star
31

ddd-oke-cars

PHP
4
star
32

docker-php

Custom PHP docker image with some basic extensions
Dockerfile
4
star
33

cryptonope

Replace crypto words with random things
JavaScript
3
star
34

homebrew-custom

Custom homebrew formulas
Ruby
2
star
35

spacegray-monokai

A Monokai color scheme for Sublime's Spacegray theme
1
star