omnishield/disposable API reference

Omnishield\Disposable

DisposableGateway class

final class DisposableGateway implements ReputationInterface DisposableGateway.php:19

Whether an e-mail's domain is a disposable one: the site's allow list first, then its deny list, then the list. Nothing leaves the site, nothing is called: the list is a file.

A disposable domain is known with full confidence - it is on a list, not reported now and then: frequency 0, confidence 100, reasons [email, disposable], and the part of the domain that matched in data.

DisposableGateway::__construct()

public function __construct(readonly DisposableList $list = new DisposableList(), array $allow = [], array $deny = [])

DisposableGateway::getName()

public function getName(): string

DisposableGateway::getTitle()

public function getTitle(): string

DisposableGateway::capabilities()

public function capabilities(): Capabilities

DisposableGateway::lookup()

public function lookup(Identity $identity): Reputation

DisposableGateway::isDisposable()

public function isDisposable(string $emailOrDomain): bool

DisposableGatewayFactory class

final class DisposableGatewayFactory extends GatewayFactory DisposableGatewayFactory.php:21

Disposable e-mail domains: a list read from a file, no call.

options: list: ~ # a file of the application's (a refreshed copy); the one shipped in the package otherwise allow: [example-school.org] # never disposable for this site, whatever the list says deny: [throwaway.example] # disposable for this site, whatever the list says

allow and deny take a list, or one comma-separated string (an environment variable); a domain takes in its subdomains.

Options

DisposableList class

final class DisposableList DisposableList.php:18

A list of disposable e-mail domains, one per line, read once per process: the one shipped in data/domains.txt (disposable-email-domains, CC0), or a file of the application's - a refreshed copy.

A domain is on the list when it, or a domain above it, is: the list holds second-level domains, so mailinator.com takes in eu.mailinator.com.

const SOURCE = 'https://raw.githubusercontent.com/disposable-email-domains/disposable-email-domains/main/disposable_email_blocklist.conf'

Where the list is kept up to date.

public readonly string $path

DisposableList::__construct()

public function __construct(public readonly string $path = __DIR__ . '/data/domains.txt')

DisposableList::match()

public function match(string $domain): ?string

The part of the domain that is on the list - itself or a domain above it -, or null.

DisposableList::count()

public function count(): int

DisposableList::find()

public static function find(array $domains, string $domain): ?string

The part of $domain found among $domains, itself or a parent of at least two labels.

DisposableList::parse()

public static function parse(iterable $lines): array

Domains as a set: lower case, comments and blank lines left out.

DisposableList::refresh()

public static function refresh(string $path, ?HttpClientInterface $http = null, string $source = self::SOURCE): int

Downloads the list's latest state and writes it to $path in one move (a temporary file renamed): a request reading the list meanwhile reads the old one or the new one, never half of either.

$http

the application's client; PHP's own streams without one

Returns

the domains written