A clean and simple PHP library for interacting with all HaveIBeenPwned.com's API endpoints
This package wraps the entire HaveIBeenPwned API in a simple, easy to use, PHP library, that can be used in any project.
Many other packages wrapping the API, are either supposed to be used in a framework, or only wraps the password checker.
Install the library with composer:
composer require mflor/pwnedAuthorisation is required for all APIs that enable searching HIBP by email address, namely retrieving all breaches for an account and retrieving all pastes for an account. An HIBP subscription key is required to make an authorised call and can be obtained on the API key page.
<?php
// Require composers autoloader
require_once './vendor/autoload.php';
// Initiate a new instance of the Pwned class
// It can be instantiated without an API key
// but then account-specific braches and pastes
// will result in unauthorized exceptions.
$pwned = new \MFlor\Pwned\Pwned($apiKey = null);// Get all breaches
$pwned->breaches()->getAll();
// Returns an array of Breach Models (see MFlor/Pwned/Models/Breach.php)
// Get all breaches by a specific domain
$pwned->breaches()->byDomain('adobe.com');
// Returns an array of Breach Models (see MFlor/Pwned/Models/Breach.php)
// Get a breach by its name
$pwned->breaches()->byName('Adobe');
// Returns a Breach Model (see MFlor/Pwned/Models/Breach.php)
// Get breaches by account (Requires API key)
$pwned->breaches()->byAccount('[email protected]');
// Returns an array of Breach Models (see MFlor/Pwned/Models/Breach.php)
// Options for breaches by account:
$options = [
'truncateResponse' => true // Show full breach or just the name (Default: true)
'domain' => 'adobe.com' // Filter results by a domain (Default: null)
'includeUnverified' => true // Include unverified breaches (Default: false)
];
$pwned->breaches()->byAccount('[email protected]', $options);
// Get all data classes
$pwned->breaches()->getDataClasses();
// ["Account balances","Address book contacts","Age groups","Ages"...]// Get all pastes by account (Requires API key)
$pwned->pastes()->byAccount('[email protected]')
// Returns an array of Paste Models (see MFlor/Pwned/Models/Paste.php)// Search for passwords (By the first five characters of a sha1 hash)
$pwned->passwords()->search('e38ad');
// Returns an array of Password Models (see MFlor/Pwned/Models/Password.php)
$pwned->passwords()->occurrences('password1');
// Returns the number occurrences of the given password has been found in leaksBoth search and occurrences takes a second boolean parameter, to disable padding for request. Be aware, that this is less secure, than having the padding enabled, which is default. Read more about the padding in Troy Hunt's blog post
This package will throw custom exceptions if a Client Error occures.
\Mflor\Pwned\Exceptions\BadRequestException is thrown on status code 400
\Mflor\Pwned\Exceptions\UnauthorizedException is thrown on status code 401
\Mflor\Pwned\Exceptions\ForbiddenException is thrown on status code 403
\Mflor\Pwned\Exceptions\NotFoundException is thrown on status code 404
\Mflor\Pwned\Exceptions\TooManyRequestsException is thrown on status code 429
\Mflor\Pwned\Exceptions\ServiceUnavailableException is thrown on status code 503
| Code | Description |
|---|---|
| 400 | Bad request — the account does not comply with an acceptable format (i.e. it's an empty string) |
| 401 | Unauthorised — either no API key was provided or it wasn't valid |
| 403 | Forbidden — no user agent has been specified in the request |
| 404 | Not found — the account could not be found and has therefore not been pwned |
| 429 | Too many requests — the rate limit has been exceeded |
| 503 | Service unavailable — usually returned by Cloudflare if the underlying service is not available |
You can run all tests by executing either of the following commands:
$ composer test
$ ./vendor/bin/phpunit
# If you already have phpunit installed globally
$ phpunitMIT
