mflor / pwned
A clean and simple PHP library for interacting with all HaveIBeenPwned.com's API endpoints
Fund package maintenance!
Ko Fi
www.buymeacoffee.com/mflor
Installs: 10 392
Dependents: 1
Suggesters: 0
Security: 0
Stars: 16
Watchers: 1
Forks: 1
Open Issues: 0
Requires
- php: ^7.4|^8.0
- ext-json: *
- guzzlehttp/guzzle: ^7.0
Requires (Dev)
- fakerphp/faker: ^1.14
- phpunit/phpunit: ^9.0
README
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.
Installation
Install the library with composer:
composer require mflor/pwned
Authorisation
Authorisation 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.
Setup
<?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);
Usage
Breaches
// 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('test@example.com'); // 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('test@example.com', $options); // Get all data classes $pwned->breaches()->getDataClasses(); // ["Account balances","Address book contacts","Age groups","Ages"...]
Pastes
// Get all pastes by account (Requires API key) $pwned->pastes()->byAccount('test@example.com') // Returns an array of Paste Models (see MFlor/Pwned/Models/Paste.php)
Passwords
// 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 leaks
Both 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
Exceptions
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
Testing
You can run all tests by executing either of the following commands:
$ composer test $ ./vendor/bin/phpunit # If you already have phpunit installed globally $ phpunit
License
MIT