validate.php

<?php
declare(strict_types=1);

/**
 * EmailValidator
 *
 * Validates an email address against:
 *  - RFC syntax (filter_var)
 *  - Length limits (RFC 5321: 64 local / 255 domain / 254 total)
 *  - An allow-list of known providers (optional)
 *  - A deny-list of common disposable providers
 *  - DNS records (MX with A/AAAA fallback)
 *
 * Returns a structured result instead of a single bool, while still
 * exposing a backward-compatible isValid() helper.
 */
final class EmailValidator
{
    /** Default allow-list of trusted providers. Pass [] to disable the check. */
    public const DEFAULT_ALLOWED_PROVIDERS = [
        'gmail.com',
        'googlemail.com',
        'hotmail.com',
        'outlook.com',
        'outlook.sa',
        'live.com',
        'msn.com',
        'aol.com',
        'protonmail.com',
        'proton.me',
        'icloud.com',
        'yahoo.com',
    ];

    /** Common disposable / throw-away domains to block. */
    public const DISPOSABLE_PROVIDERS = [
        'mailinator.com',
        'guerrillamail.com',
        'tempmail.com',
        '10minutemail.com',
        'trashmail.com',
        'yopmail.com',
        'getnada.com',
        'sharklasers.com',
    ];

    /** @var string[] */
    private array $allowedProviders;

    /** @var string[] */
    private array $disposableProviders;

    private bool $checkDns;

    /**
     * @param string[]|null $allowedProviders   null = use defaults, [] = allow any
     * @param string[]      $disposableProviders
     */
    public function __construct(
        ?array $allowedProviders = null,
        array $disposableProviders = self::DISPOSABLE_PROVIDERS,
        bool $checkDns = true
    ) {
        $this->allowedProviders = array_map(
            'strtolower',
            $allowedProviders ?? self::DEFAULT_ALLOWED_PROVIDERS
        );
        $this->disposableProviders = array_map('strtolower', $disposableProviders);
        $this->checkDns = $checkDns;
    }

    /**
     * Validate an email and return a structured result.
     *
     * @return array{valid: bool, normalized: ?string, errors: string[]}
     */
    public function validate(mixed $email): array
    {
        $errors = [];

        if (!is_string($email)) {
            return ['valid' => false, 'normalized' => null, 'errors' => ['email_not_string']];
        }

        $email = trim($email);
        if ($email === '') {
            return ['valid' => false, 'normalized' => null, 'errors' => ['email_empty']];
        }

        $sanitized = filter_var($email, FILTER_SANITIZE_EMAIL);
        if ($sanitized !== $email) {
            $errors[] = 'email_contains_invalid_chars';
        }

        $filtered = filter_var($sanitized, FILTER_VALIDATE_EMAIL);
        if ($filtered === false) {
            $errors[] = 'email_syntax_invalid';
            return ['valid' => false, 'normalized' => null, 'errors' => $errors];
        }

        $atPos = strrpos($filtered, '@');
        if ($atPos === false) {
            return ['valid' => false, 'normalized' => null, 'errors' => ['email_missing_at']];
        }

        $local  = substr($filtered, 0, $atPos);
        $domain = strtolower(substr($filtered, $atPos + 1));
        $normalized = $local . '@' . $domain;

        // RFC 5321 length limits
        if (strlen($normalized) > 254) {
            $errors[] = 'email_too_long';
        }
        if (strlen($local) === 0 || strlen($local) > 64) {
            $errors[] = 'local_part_length_invalid';
        }
        if (strlen($domain) === 0 || strlen($domain) > 255) {
            $errors[] = 'domain_length_invalid';
        }
        if (!str_contains($domain, '.')) {
            $errors[] = 'domain_missing_tld';
        }

        if (in_array($domain, $this->disposableProviders, true)) {
            $errors[] = 'domain_disposable';
        }

        if ($this->allowedProviders !== [] && !in_array($domain, $this->allowedProviders, true)) {
            $errors[] = 'domain_not_allowed';
        }

        if ($errors === [] && $this->checkDns && !$this->domainHasMailRecords($domain)) {
            $errors[] = 'domain_no_dns_records';
        }

        return [
            'valid'      => $errors === [],
            'normalized' => $errors === [] ? $normalized : null,
            'errors'     => $errors,
        ];
    }

    /** Backward-compatible boolean check. */
    public function isValid(mixed $email): bool
    {
        return $this->validate($email)['valid'];
    }

    private function domainHasMailRecords(string $domain): bool
    {
        // Prefer MX, then fall back to A / AAAA per RFC 5321 §5.
        if (checkdnsrr($domain, 'MX')) {
            return true;
        }
        return checkdnsrr($domain, 'A') || checkdnsrr($domain, 'AAAA');
    }
}

?>