The Hibp sdk provides an easy-to-use interface for interacting with Have I Been Pwned - HIBP API.
It wraps API responses in class response objects and supports fakes for testing purposes.
Requires PHP 8.2+
Install via the Composer package manager:
composer require bright/hibp-sdkThe Hibp::make will create client factory and ready to making requests
use Bright\Hibp\Hibp;
$apiKey = 'your-hibp-api-key';
Hibp::make($apiKey)->breaches(); //Breaches object
Hibp::make($apiKey)->breaches()->toArray(); //array of breach
Hibp::make($apiKey)->breaches()[0]->name // get the name
Hibp::make($apiKey)->breaches()[0]->Name // get the name
// Get a single breach
Hibp::make($apiKey)->breach('Adobe');
//Get account breached
Hibp::make($apiKey)->breachedaccount('youremail@example.com'); //Breaches object
Hibp::make($apiKey)->breachedaccount('youremail@example.com')->toArray();Create a new client using factory to advance configuration for http request
Hibp::factory()
->withApiKey('your-api-key')
->withHeaders(['CustomHeader' => 'value'])
->withUserAgent('MyApp')
->withTimeout(30)
->make() // create client
->breaches();All available method for chain with the client factory
Hibp::factory()
->withApiKey('your-api-key')
->withQueryParameters(['foo' => 'bar'])
->withHeaders([])
->withTimeout(30)
->withBaseUri('https://haveibeenpwned.com/api/v3')
->withUserAgent('MyApp')
->withHttpClient(new \GuzzleHttp\Client)
->withOptions(['referer' => false]) // https://docs.guzzlephp.org/en/stable/request-options.html
->withHandler('...') // guzzle handler
->withMiddleware('') // https://docs.guzzlephp.org/en/stable/handlers-and-middleware.html
->make() // create client
->breaches(); // Get breaches$breaches = $client->breachedaccount('user@example.com');
$breaches[0]->name // breached name
$breaches[0]->name // breached name
$breaches->toArray() // All breached array items
$breaches[0]->toArray() // The breach array- Returns a
Breachescollection. - Handles 404 gracefully (returns empty collection).
$breaches = $client->breacheddomain('example.com');- Returns an array of breached emails for the verified domain.
$allBreaches = $client->breaches();- Returns all breaches as a
Breachescollection.
$breach = $client->breach('Adobe');- Returns a
Breachobject for the specified breach name.
$latest = $client->latestbreach();- Returns the most recently added breach.
$dataClasses = $client->dataclasses();- Returns all data classes in the system as an array.
$pastes = $client->pasteaccount('user@example.com');- Returns an array of pastes associated with the account.
$status = $client->subscriptionStatus();- Returns the subscription status of your API key.
$result = $client->range('5BAA6');- Uses k-anonymity API to check if a password has been pwned.
- Returns a JSON array of suffixes and counts.
Create fake response using Hibp::fake helper:
use Bright\Hibp\Hibp;
Hibp::fake('/breachedaccount/user@example.com', [
['Name' => 'Adobe', 'PwnCount' => 12345]
]);
$client = Hibp::make('fake-api-key');
$breaches = $client->breachedaccount('user@example.com');
print_r($breaches->toArray());
//for endpoints fake
$data = [['Name' => 'Adobe']];
Hibp::fake('*', $data);
Hibp::fake('*', Hibp::response($data, 500, ['fake-header' => 'fake-value']));- Fakes can be specific to endpoints or use
'*'for a catch-all. Factory::clearFakes()clears all fake responses.
- 404 for no breaches: HIBP returns 404 if no breaches exist; client returns empty collection.
- Rate limits: Ensure API key allows the requested number of queries per minute.
- Invalid API key: Returns 401 Unauthorized. Check
Hibp::make($apiKey). - Network errors: Wrapped as a Response object with status code and message.
- Fork the repository
- Make your changes
- Submit a pull request with a clear description
MIT License © 2025 Bright