PHPackages spatie/pixelmatch-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Image & Media](/categories/media) 4. / 5. spatie/pixelmatch-php ActiveLibrary[Image & Media](/categories/media) spatie/pixelmatch-php ===================== Compare images using PHP 1.2.1(8mo ago)58110.0k—1.4%6[1 PRs](https://github.com/spatie/pixelmatch-php/pulls)8MITPHPPHP ^8.1CI passing Since Sep 11Pushed 4w ago2 watchersCompare [ Source](https://github.com/spatie/pixelmatch-php)[ Packagist](https://packagist.org/packages/spatie/pixelmatch-php)[ Docs](https://github.com/spatie/pixelmatch-php)[ GitHub Sponsors](https://github.com/spatie)[ RSS](/packages/spatie-pixelmatch-php/feed)WikiDiscussions main Synced 2w ago READMEChangelog (6)Dependencies (5)Versions (8)Used By (8) Compare images using PHP ======================== [](#compare-images-using-php) [![Latest Version on Packagist](https://camo.githubusercontent.com/a0ef2711b89ef4e72ba39acd3a9b31b8d39840116b19e7fd70af3274e239a07a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f706978656c6d617463682d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/pixelmatch-php)[![Tests](https://github.com/spatie/pixelmatch-php/actions/workflows/run-tests.yml/badge.svg)](https://github.com/spatie/pixelmatch-php/actions/workflows/run-tests.yml)[![Total Downloads](https://camo.githubusercontent.com/b3122348785ff22de07efbbbb4c530e83c3c104f6b6d2dbef0354d40c699eb2e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f706978656c6d617463682d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/pixelmatch-php) This package can compare two images and return the percentage of matching pixels. It's a PHP wrapper around the [Pixelmatch](https://github.com/mapbox/pixelmatch) JavaScript library. Here's a quick example on how to use the package. ``` use Spatie\Pixelmatch\Pixelmatch; $pixelmatch = Pixelmatch::new("path/to/file1.png", "path/to/file2.png"); $pixelmatch->matchedPixelPercentage(); // returns a float, for example 97.5 $pixelmatch->mismatchedPixelPercentage(); // returns a float, for example 2.5 ``` Support us ---------- [](#support-us) [![](https://camo.githubusercontent.com/d6ce4e782aeaeb8049f9fcc4fbaade4de2ffc3f005666a326024f0e47ce8d9f0/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f706978656c6d617463682d7068702e6a70673f743d31)](https://spatie.be/github-ad-click/pixelmatch-php) We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us). We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards). Installation ------------ [](#installation) You can install the package via composer: ``` composer require spatie/pixelmatch-php ``` In your project, or on your server, you must have the JavaScript package [`Pixelmatch`](https://github.com/mapbox/Pixelmatch) installed. ``` npm install pixelmatch ``` ... or Yarn. ``` yarn add pixelmatch ``` Make sure you have installed Node 16 or higher. Usage ----- [](#usage) Here's how you can get the percentage of matching pixels between two images. ``` use Spatie\Pixelmatch\Pixelmatch; $pixelmatch = Pixelmatch::new("path/to/file1.png", "path/to/file2.png"); $pixelmatch->matchedPixelPercentage(); // returns a float, for example 97.5 $pixelmatch->mismatchedPixelPercentage(); // returns a float, for example 2.5 ``` To get the amount of matched and mismatched pixels, you can use these methods. ``` use Spatie\Pixelmatch\Pixelmatch; $pixelmatch = Pixelmatch::new("path/to/file1.png", "path/to/file2.png"); $pixelmatch->matchedPixels(); // returns an int $pixelmatch->mismatchedPixels(); // returns an int ``` You can use the `matches function` to check if the images match. ``` use Spatie\Pixelmatch\Pixelmatch; $pixelmatch = Pixelmatch::new("path/to/file1.png", "path/to/file2.png"); $pixelmatch->matches(); // returns a boolean $pixelmatch->doesNotMatch(); // returns a boolean ``` ### Setting a threshold [](#setting-a-threshold) To set the threshold for the amount of mismatching pixels, you can use the `threshold` method. Higher values will make the comparison more sensitive. The threshold should be between 0 and 1. If you don't set a threshold, we'll use the default value of `0.1`. ``` $pixelmatch->threshold(0.05); ``` ### Ignoring anti-aliasing [](#ignoring-anti-aliasing) To ignore anti-aliased pixels, you can use the `includeAa` method. ``` $pixelmatch->includeAa(); ``` Limitations ----------- [](#limitations) The package can only compare png images. Images with different dimensions cannot be compared. If you try to do this, a `Spatie\Pixelmatch\Exceptions\CouldNotCompare` exception will be thrown. Testing ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [Niels Vanpachtenbeke](https://github.com/nielsvanpach) - [Freek Van der Herten](https://github.com/freekmurze) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 55 — FairBetter than 97% of packages Maintenance79 Regular maintenance activity Popularity45 Moderate usage in the ecosystem Community29 Small or concentrated contributor base Maturity58 Maturing project, gaining track record Bus Factor1 Top contributor holds 54.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~161 days Recently: every ~201 days Total 6 Last Release 266d ago Major Versions 0.0.2 → 1.0.02023-09-11 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie) --- Top Contributors [![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (85 commits)")[![Nielsvanpach](https://avatars.githubusercontent.com/u/10651054?v=4)](https://github.com/Nielsvanpach "Nielsvanpach (28 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (23 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (10 commits)")[![Chris8934](https://avatars.githubusercontent.com/u/44963939?v=4)](https://github.com/Chris8934 "Chris8934 (3 commits)")[![thecaliskan](https://avatars.githubusercontent.com/u/13554944?v=4)](https://github.com/thecaliskan "thecaliskan (2 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (2 commits)")[![riasvdv](https://avatars.githubusercontent.com/u/3626559?v=4)](https://github.com/riasvdv "riasvdv (1 commits)")[![onlime](https://avatars.githubusercontent.com/u/2759561?v=4)](https://github.com/onlime "onlime (1 commits)") --- Tags imagesphppixelmatchspatieimagespixelmatch-phpPixelmatch ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/spatie-pixelmatch-php/health.svg) ``` [![Health](https://phpackages.com/badges/spatie-pixelmatch-php/health.svg)](https://phpackages.com/packages/spatie-pixelmatch-php) ``` ### Alternatives [matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.7k39.6k](/packages/matomo-matomo)[spatie/image Manipulate images with an expressive API 1.4k63.1M206](/packages/spatie-image)[spatie/image-optimizer Easily optimize images using PHP 2.9k82.5M181](/packages/spatie-image-optimizer)[spatie/laravel-health Monitor the health of a Laravel application 88212.7M188](/packages/spatie-laravel-health)[spatie/flare-client-php Send PHP errors to Flare 178166.2M24](/packages/spatie-flare-client-php)[tempest/framework The PHP framework that gets out of your way. 2.3k37.6k21](/packages/tempest-framework) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)