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.

---

Table of Contents

• Features
• Installation
• Requirements
• Quick Start
• API Reference
  • checkEmail
  • getBreaches
  • breachAnalytics
  • checkPassword
• 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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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

• XposedOrNot Website
• API Documentation
• Packagist Package
• GitHub Repository
• XposedOrNot API Repository

---

Made with care by XposedOrNot