Download the PHP package raul3k/disposable-email-blocker-core without Composer

Disposable Email Blocker - Core

Fast disposable/temporary email detection with full Public Suffix List (PSL) support, pattern matching, caching, and whitelist capabilities.

Table of Contents

• Features
• Installation
• Quick Start
• Builder
• Detailed Check Results
• Batch Operations
• Pattern-Based Detection
• Whitelist Support
• Caching
• Custom Checkers
• Working with Sources
• Updating the Public Suffix List
• Domain Info
• Domain Normalization
• Framework Integration
• Development
• License

Features

• Fast O(1) lookups using hash-based domain checking
• Full PSL support - correctly handles subdomains and public suffixes
• IDN/Punycode support - international domain names are handled correctly
• Pattern matching - detect suspicious domain patterns via regex
• Whitelist support - allow specific domains to bypass checks
• Caching layer - PSR-6/PSR-16 compatible cache adapters
• Detailed results - CheckResult with matched checker info
• Batch operations - efficiently check multiple emails at once
• Multiple checkers - file-based, callback-based, or chain multiple checkers
• Domain parsing - DomainInfo for detailed domain analysis (PSL, subdomain, IDN)
• Extensible sources - built-in sources + custom parsers for any format
• CLI tools - bin/update-domains to fetch and merge domain lists, bin/update-psl to update the Public Suffix List
• Framework agnostic - use with any PHP project

Installation

Quick Start

Builder

The fluent builder is the recommended way to compose checkers:

Available builder methods:

• withBundledDomains() - use the bundled ~159k domain list
• withDomainsFile(string $path) - use a custom domains file
• withPatternDetection(?array $patterns = null) - enable regex pattern matching
• withChecker(CheckerInterface $checker) - add any custom checker
• withCallback(callable $callback) - add a callback-based checker
• withWhitelist(array $domains) - whitelist specific domains
• withFileCache(string $directory, ?int $ttl = 3600) - enable file-based caching
• withCache(CacheInterface $cache, ?int $ttl = 3600) - use a custom cache
• withNormalizer(DomainNormalizer $normalizer) - use a custom normalizer

Detailed Check Results

Get detailed information about the check result:

Batch Operations

Check multiple emails efficiently:

Pattern-Based Detection

Detect suspicious domain patterns using regex:

Whitelist Support

Allow specific domains to bypass disposable checks:

Caching

Add caching to improve performance for repeated checks:

PSR-6/PSR-16 Cache Adapters

Use any PSR-compatible cache:

Custom Checkers

Using a Callback (Redis, Database, API, etc.)

Implementing CheckerInterface

For reusable or complex checkers, implement the interface directly:

Using a Custom File

Chaining Multiple Checkers

Working with Sources

Sources provide lists of disposable domains. The library includes several pre-configured sources.

Available Built-in Sources

Fetching from Sources

Adding Custom Sources

Updating the Bundled Domain List

Use the CLI tool to fetch domains from all sources and update the bundled list:

You can customize sources via a disposable-blocker.php config file in your project root:

Updating the Public Suffix List

The library bundles a copy of the Public Suffix List for domain normalization. To update it:

The script downloads from the canonical source, validates the content (size, structure, and parse checks), and writes the updated file.

A GitHub Actions workflow runs monthly to keep the bundled PSL current via automated PRs.

Domain Info

Parse and inspect domain details using the Public Suffix List:

Domain Normalization

The library normalizes domains using the Public Suffix List to correctly extract registrable domains:

Framework Integration

For Laravel integration, see:

• raul3k/disposable-email-blocker-laravel

Development

License

MIT License. See LICENSE for details.