Skip to content
A clean and simple PHP library for interacting with all HaveIBeenPwned.com's API endpoints
PHP
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.
.circleci
src
tests
.gitignore
README.md
composer.json
phpunit.xml

README.md

Pwned CircleCI Coverage Status

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

Setup

<?php

// Require composers autoloader
require_once './vendor/autoload.php';

// Initiate a new instance of the Pwned class
$pwned = new \MFlor\Pwned\Pwned();

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
$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
$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()->occurences('password1');
// Returns the number occurences of the given password has been found in leaks

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\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

Code Description
400 Bad request — the account does not comply with an acceptable format (i.e. it's an empty string)
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

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

You can’t perform that action at this time.