README

xposedornot-php

Official PHP SDK for the XposedOrNot API
Check if your email has been exposed in data breaches

Note: This SDK uses the free public API from XposedOrNot.com - a free service to check if your email has been compromised in data breaches. Visit the XposedOrNot website to learn more about the service and check your email manually.

Features
Installation
Requirements
Quick Start
API Reference
Error Handling
Rate Limits
Configuration
Contributing
License
Links

Features

Simple API - Easy-to-use methods for checking email breaches, browsing breaches, and verifying passwords
Free and Plus support - Works with the free public API out of the box; add an API key for Plus features
Detailed Analytics - Get breach details, risk scores, and metrics
Password Privacy - Passwords are hashed locally with Keccak-512; only a 10-char prefix is sent (k-anonymity)
Error Handling - Typed exception classes for every failure scenario
Configurable - Timeout, retries, custom headers, and base URL overrides
Secure - HTTPS enforced, input validation, no sensitive data transmitted in plaintext

Installation

composer require xposedornot/xposedornot-php

Requirements

PHP 8.1 or higher
Composer

Quick Start

use XposedOrNot\XposedOrNot;

$client = new XposedOrNot();

// Check if an email has been breached
$result = $client->checkEmail('test@example.com');

if (!empty($result->breaches)) {
    echo "Email found in " . count($result->breaches) . " breaches:\n";
    foreach ($result->breaches as $breach) {
        echo "  - {$breach}\n";
    }
} else {
    echo "Good news! Email not found in any known breaches.\n";
}

API Reference

Constructor

use XposedOrNot\XposedOrNot;
use XposedOrNot\Configuration;

// Default configuration (free API)
$client = new XposedOrNot();

// Custom configuration
$config = new Configuration(apiKey: 'your-api-key');
$client = new XposedOrNot($config);

Methods

`checkEmail($email)`

Check if an email address has been exposed in data breaches. Uses the free API when no API key is configured; uses the Plus API with detailed results when an API key is set.

// Free API - returns breach names
$result = $client->checkEmail('user@example.com');
print_r($result->breaches);

// Plus API - returns detailed breach information
$config = new Configuration(apiKey: 'your-api-key');
$client = new XposedOrNot($config);

$result = $client->checkEmail('user@example.com');

foreach ($result->breaches as $breach) {
    echo "{$breach->breachId} - {$breach->domain} ({$breach->xposedRecords} records)\n";
}

`getBreaches($domain)`

Get a list of all known data breaches, optionally filtered by domain.

// Get all breaches
$breaches = $client->getBreaches();

// Filter by domain
$breaches = $client->getBreaches('adobe.com');

Returns: Array of BreachInfo objects with properties such as breachID, domain, exposedData, exposedRecords, breachedDate, and more.

`breachAnalytics($email)`

Get detailed breach analytics for an email address, including risk scores and metrics.

$analytics = $client->breachAnalytics('user@example.com');

echo "Exposed breaches: " . count($analytics->exposedBreaches) . "\n";
echo "Breach metrics:\n";
print_r($analytics->breachMetrics);

`checkPassword($password)`

Check if a password has been exposed in known data breaches. The password is hashed locally using Keccak-512 and only a 10-character prefix of the hash is sent to the API (k-anonymity).

$result = $client->checkPassword('mypassword');

if ($result->count > 0) {
    echo "Password has been exposed {$result->count} times.\n";
} else {
    echo "Password not found in any known breaches.\n";
}

Error Handling

The library provides typed exception classes for different failure scenarios:

use XposedOrNot\Exceptions\{
    XposedOrNotException,
    ValidationException,
    AuthenticationException,
    NotFoundException,
    RateLimitException,
    NetworkException,
    ApiException,
};

try {
    $result = $client->checkEmail('invalid-email');
} catch (ValidationException $e) {
    echo "Invalid input: " . $e->getMessage();
} catch (AuthenticationException $e) {
    echo "Invalid or missing API key: " . $e->getMessage();
} catch (NotFoundException $e) {
    echo "Email not found in any breaches.";
} catch (RateLimitException $e) {
    echo "Rate limit exceeded. Try again later.";
} catch (NetworkException $e) {
    echo "Network error: " . $e->getMessage();
} catch (ApiException $e) {
    echo "API error: " . $e->getMessage();
} catch (XposedOrNotException $e) {
    echo "General error: " . $e->getMessage();
}

Exception Classes

Exception Class	Description
`XposedOrNotException`	Base exception class for all errors
`ValidationException`	Invalid input (e.g., malformed email address)
`AuthenticationException`	Invalid or missing API key
`NotFoundException`	Resource not found (e.g., email not in any breach)
`RateLimitException`	API rate limit exceeded after retries
`NetworkException`	Network connectivity issues
`ApiException`	General API error

Rate Limits

The XposedOrNot API has the following rate limits:

2 requests per second
50-100 requests per hour
100-1000 requests per day

The client includes automatic client-side rate limiting (1 request per second for the free API) and retry with exponential backoff (1s, 2s, 4s) for HTTP 429 responses.

Configuration

All configuration is handled through the Configuration class:

use XposedOrNot\Configuration;

$config = new Configuration(
    baseUrl: 'https://api.xposedornot.com',                // Free API base URL
    plusBaseUrl: 'https://plus-api.xposedornot.com',       // Plus API base URL
    passwordBaseUrl: 'https://passwords.xposedornot.com/api', // Password API base URL
    timeout: 30,          // Request timeout in seconds
    maxRetries: 3,        // Max retries on 429 (rate limit)
    apiKey: null,         // API key for Plus API
    headers: [],          // Custom headers
);

$client = new XposedOrNot($config);

Configuration Options

Option	Type	Default	Description
`baseUrl`	`string`	`'https://api.xposedornot.com'`	Base URL for the free API
`plusBaseUrl`	`string`	`'https://plus-api.xposedornot.com'`	Base URL for the Plus API
`passwordBaseUrl`	`string`	`'https://passwords.xposedornot.com/api'`	Base URL for the password API
`timeout`	`int`	`30`	Request timeout in seconds
`maxRetries`	`int`	`3`	Maximum retry attempts on rate limit (429)
`apiKey`	`string\|null`	`null`	API key for Plus API access
`headers`	`array`	`[]`	Custom headers to include in all requests

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/XposedOrNot/XposedOrNot-PHP.git
cd XposedOrNot-PHP

# Install dependencies
composer install

# Run tests
./vendor/bin/phpunit

# Run static analysis (if configured)
composer analyse

License

MIT - see the LICENSE file for details.

Links

Made with care by XposedOrNot

xposedornot / xposedornot-php

Maintainers

Package info

Statistics

Security