Pwned

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

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

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