README

Domain-specific validation for email local-part (username) in Laravel. App developers register validator classes that declare their applicable domains, and the package plugs into Laravel's Validator via a simple email_username rule.

Might be useful to reduce hard-bounced emails caused by invalid email addresses entered by user, might not.

90% codes (including this README) are generated by GitHub Copilot. Use at your own risk. PRs welcome.

Install

composer require littleskinchina/laravel-email-username-validator

Publish the config:

php artisan vendor:publish --tag=config --provider="LittleSkin\\LaravelEmailUsernameValidator\\EmailUsernameValidatorServiceProvider"

Configure

Edit config/email-username-validator.php and list your rule classes:

return [
    'rules' => [
        App\EmailUsernameRules\GmailRule::class,
        App\EmailUsernameRules\OutlookRule::class,
    ],
    // More config options available, see comments on config file for details
];

A rule class must implement LittleSkin\\LaravelEmailUsernameValidator\\Contracts\\EmailUsernameRule:

use LittleSkin\LaravelEmailUsernameValidator\Contracts\EmailUsernameRule;

class ExampleRule implements EmailUsernameRule
{
    // Domains this rule applies to, exact or wildcard
    public static function domains(): array
    {
        return [
            'example.com',
            '*.example.com',
        ];
    }

    public function passes(string $username, string $domain, array $parameters = []): bool
    {
        // Example: require at least 6 chars length
        return strlen($username) >= 6;
    }
}

A single rule can cover multiple domains via its domains() return value.

You can also implement EmailUsernameRuleWithMessage to provide rule-specific failure messages:

class ExampleRuleWithMessage extends ExampleRule implements EmailUsernameRuleWithMessage {
    public function message(): string
    {
        return 'The email address is invalid.';
    }
}

Predefined rules

The package includes some predefined rules for common email providers under namespace LittleSkin\LaravelEmailUsernameValidator\Rules. See src/Rules for details.

Some predefined rules might be too relaxed or too strict. Feel free to modify or create your own rules as needed.

Again, PRs are welcome.

Use in validation

Suggested to use with Laravel's built-in email rule, which validates overall email format and DNS records.

$request->validate([
    'email' => ['required', 'email:strict,dns', 'email_username'],
]);

Semantics:

Each domain resolves to at most one rule (the first concrete match wins, otherwise the first wildcard match).
If no rules match a domain, behavior is controlled by unknown-domain-pass.

Customizing messages and localization

Implement EmailUsernameRuleWithMessage to provide a rule-specific failure message. That message wins over config/localization.
Otherwise the package uses the 'messages' config entry, resolved via Laravel's translator if it matches a translation key.
Default translations ship under the namespace email-username, or you can point to your own key or literal.
The :attribute and :domain placeholders will be replaced automatically by the Validator replacer.

Copyright

Licensed under MIT.

littleskinchina / laravel-email-username-validator

Maintainers

Details