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.

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

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

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