Skip to content
PHP library for accessing the Have I Been Pwned API.
PHP Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
_ci Add custom PHPMD rules and fix BreachNotFound exception constructor Oct 12, 2018
_phpmd
src Add API key to Laravel-specific service providers Jul 24, 2019
tests Add longer delay between tests for API rate limit Jul 24, 2019
.gitignore WIP: Update to use HIBP API v3 Jul 21, 2019
.gitlab-ci.yml Add HIBP API key as CI variable Jul 24, 2019
CHANGELOG.md
CONTRIBUTING.md
LICENSE Update license file. May 10, 2018
README.md Update README.md with extra info badges Aug 16, 2019
composer.json WIP: Update to use HIBP API v3 Jul 21, 2019
phpcs.xml Add missing PHPCS config Oct 8, 2018
phpunit.xml.dist Refactor directory and fix tests Mar 13, 2019

README.md

PHP library for Have I Been Pwned and Pwned Passwords.

pipeline status Latest Stable Version Total Downloads License

HIBP-PHP is a composer library for accessing the Have I Been Pwned and Pwned Passwords APIs.

The HIBP API now 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.

The minimum PHP version for this package is now 7.2.0.

Requirements

  • PHP 7.2.0+

Installation

composer require icawebdesign/hibp-php

Usage examples for Breach Sites data

Get all breach sites

use Icawebdesign\Hibp\Breach;

$breach = new Breach($apiKey);
$breachSites = $breach->getAllBreachSites();

Or we can filter for a domain the breach was listed in:

use Icawebdesign\Hibp\Breach;

$breach = new Breach($apiKey);
$breachSites = $breach->getAllBreachSites('adobe.com');

Get single breach site

use Icawebdesign\Hibp\Breach;

$breach = new Breach($apiKey);
$breachSite = $breach->getBreach('adobe');

Get list of data classes for breach sites

use Icawebdesign\Hibp\Breach;

$breach = new Breach($apiKey);
$dataClasses = $breach->getAllDataClasses();

Get data for a breached email account

use Icawebdesign\Hibp\Breach;

$breach = new Breach($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 = new Breach($apiKey);
$data = $breach->getBreachedAccount('test@example.com', 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 = new Breach($apiKey);
$data = $breach->getBreachedAccount('test@example.com', true, 'adobe.com');

Usage examples for Pwned Passwords

Get number of times the start of a hash appears in the system matching against a full hash

use Icawebdesign\Hibp\PwnedPassword;

$pwnedPassword = new PwnedPassword();
$count = $pwnedPassword->rangeFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');

Get a collection of hash data from a start of a hash and matching against a full hash

use Icawebdesign\Hibp\PwnedPassword;

$pwnedPassword = new PwnedPassword();
$hashData = $pwnedPassword->rangeDataFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');

Usage examples for Paste lists

Get a collection of pastes that a specified email account has appeared in

use Icawebdesign\Hibp\Paste;

$paste = new Paste($apiKey);
$data = $paste->lookup('test@example.com');

Laravel specifics

If using the package within a Laravel application, you can use the provided facades. First, you need to add your HIBP API key to your .env file, or your preferred method for adding values to your server environment variables.

HIBP_API_KEY=abcdefgh123456789

You can then use the facades to call the relevant methods:

// Breach
$breachSites = Breach::getAllBreachSites();

// Paste
$paste = Paste::lookup('test@example.com');

// PwnedPassword
$count = PwnedPassword::rangeFromHash('5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8');

Deprecations

The range() and rangeData() methods have been deprecated in the PwnedPassword class and will be removed in version 4.0.0.

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@ianh.io instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

You can’t perform that action at this time.