icawebdesign / hibp-php
PHP library for accessing the Have I Been Pwned API.
Requires
- php: ^8.4.1||^8.5
- ext-json: *
- digiservnet/http-response-codes: ^1.0
- guzzlehttp/guzzle: ^7.15.1||^8.0
- guzzlehttp/psr7: ^2.12.3||^3.0
- illuminate/collections: ^12.0||^13.0
- nesbot/carbon: ^3.0
- nikic/php-parser: ^5.8
- psr/http-message: ^1.0||^2.0
- symfony/yaml: ^7.4.12||^8.0.12
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.95
- mockery/mockery: ^1.6
- phpstan/phpstan: ^2.2
- phpstan/phpstan-mockery: ^2.0.0
- phpstan/phpstan-phpunit: ^2.0
- phpunit/phpunit: ^10.5||^11.5||^12.0||^13.0
This package is auto-updated.
Last update: 2026-08-10 13:56:57 UTC
README
HIBP-PHP is a composer library for accessing the Have I Been Pwned and Pwned Passwords APIs (currently v3).
The HIBP API requires an API Key that needs to be purchased at the HIBP site for any lookups that use an email address. This currently means that if you're only using this package for lookups from the PwnedPassword section of the API, then an API key isn't required.
Version 7.x requires PHP >= 8.4.1. If you need to support previous versions of PHP, please use the
icawebdesign/hibp-php:^6.0 tag. This version however, will only receive security fixes.
Version 6.x requires PHP >= 8.1. If you need to support previous versions of PHP, please use the
icawebdesign/hibp-php:^5.0 tag. This version however, will only receive security fixes.
ℹ️ Repo location change
Due to a number of reasons, with the release of v7, HIBP-PHP is moving
from GitHub
to Codeberg.
Requirements
- PHP >= 8.4.1
Installation
composer require icawebdesign/hibp-php:"^7.0"
There are 4 types of entities (essentially DTOs) that can be returned when calls are made regarding breaches, these are:
BreachSiteEntity
class {
string $title;
string $name;
string $domain;
Carbon $breachDate;
Carbon $addedDate;
Carbon $modifiedDate;
int $pwnCount;
string $description;
Collection $dataClasses;
bool $verified;
bool $fabricated;
bool $sensitive;
bool $retired;
bool $spamList;
bool $malware;
string $logoPath;
bool $subscriptionFree;
bool $stealerLog;
?string $attribution;
}
BreachSiteTruncatedEntity
class {
string $name;
}
PwnedPasswordEntity
class {
string $hashSnippet,
int $count,
bool $matched
}
PasteEntity
class {
string $source;
string $id;
string $title;
?Carbon $date;
int $emailCount;
string $link;
}
Usage examples for Breach Sites data
Get all breach sites
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$breachSites = $breach->getAllBreachSites();
This will return a Collection of BreachSiteEntity objects.
Or we can filter for a domain the breach was listed in:
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$breachSites = $breach->getAllBreachSites('adobe.com');
This will return a Collection of BreachSiteEntity objects.
Get single breach site
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$breachSite = $breach->getBreach('adobe');
This will return a single BreachSiteEntity object.
Get list of data classes for breach sites
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$dataClasses = $breach->getAllDataClasses();
This will return an array of Data Classes, eg;
[
"Account balances",
"Address book contacts",
"Age groups",
"Ages",
...
]
Get data for a breached email account
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$data = $breach->getBreachedAccount('test@example.com');
We can retrieve unverified accounts too by specifying true for the second param (not retrieved by default):
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$data = $breach->getBreachedAccount('test@example.com', includeUnverified: true);
We can also filter results back to a specific breached domain by adding a domain as the 3rd param:
use Icawebdesign\Hibp\Breach\Breach;
use Icawebdesign\Hibp\HibpHttp;
$breach = new Breach(new HibpHttp($apiKey));
$data = $breach->getBreachedAccount(
'test@example.com',
includeUnverified: true,
domainFilter: 'adobe.com',
);
These calls will return a Collection of BreachSiteEntity objects.
Usage examples for Pwned Passwords
The PwnedPasswd methods can now take a second param of an array to
specify GuzzleHttp request options.
Get number of times the start of a hash appears in the system matching against a full hash
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$count = $pwnedPassword->rangeFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');
This will return an int of the count.
You can also check against NTLM hashes:
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$count = $pwnedPassword->ntlmRangeFromHash('8846F7EAEE8FB117AD06BDD830B7586C');
Get number of times the start of a hash appears in the system as above, but with padded values to help prevent fingerprinting
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->paddedRangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');
You can also check against NTLM hashes:
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->paddedNtlmRangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');
This will return a Collection of PwnedPasswordEntity objects.
Get a collection of hash data from a start of a hash and matching against a full hash
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->rangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');
This will return a Collection of PwnedPasswordEntity objects.
Get a collection of hash data from a start of a hash and matching against a full hash as above, but with padded values to help prevent fingerprinting
use Icawebdesign\Hibp\Password\PwnedPassword;
use Icawebdesign\Hibp\HibpHttp;
$pwnedPassword = new PwnedPassword(new HibpHttp($apiKey));
$hashData = $pwnedPassword->paddedRangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');
// Strip padded values from results
$hashData = PwnedPassword::stripZeroMatchesData($hashData, '5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');
This will return a Collection of PwnedPasswordEntity objects.
Usage examples for Paste lists
Get a collection of pastes that a specified email account has appeared in
use Icawebdesign\Hibp\Paste\Paste;
use Icawebdesign\Hibp\HibpHttp;
$paste = new Paste(new HibpHttp($apiKey));
$data = $paste->lookup('test@example.com');
This will return a Collection of PasteEntity objects.
Laravel specifics
From v7 of HIBP-PHP, the Laravel facades have been removed. It's a simple package and the facades didn't really offer much over just using it as a framework-agnostic package.
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email ian.h@digiserv.net instead of using the issue tracker.
Credits
Thank you to Artem Fomenko for being the first external contributor to the package providing request options for Guzzle for the PwnedPassword methods.
License
The MIT License (MIT). Please see License File for more information.