coodde/laravel-email-checker

Validates email addresses belong to their domains

0.1.6 2024-12-26 15:14 UTC

Requires

• php: >8.0.0
• coodde/mail-checker: >0.1
• illuminate/support: ^10.0
• illuminate/validation: ^10.0

Requires (Dev)

• laravel/pint: ^1.18.1
• pestphp/pest: ^2.0
• pestphp/pest-plugin-type-coverage: ^2.0
• phpstan/phpstan: ^1.12.7
• rector/rector: ^1.2.8

Apache-2.0

• Svyatoslav Ryzhok

• email
• validator
• validation
• laravel
• email domain
• email checker

README

Laravel Email Checker

Validates email addresses belong to their domain.

Report Bug · Request Feature

Table of Contents

1. About The Package
   • Built With
2. Getting Started
   • Requires
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

Flexible and simple library for checking email addresses. Usual framework validators are usually checking email correctness, but this library is implementing other kind of validation.

It can check is mail:

• registered in mail provider from forbidden country;
• registered in forbidden domain (all possible levels);
• used for spam or scam (dangerous), temporary, had suspicious behaviour, is registered on paid or public (like gmail) mail provider.

Of course, you can always propose new domains to add into listed in the "data" directory.

Key feautures:

• fast search - binary search in the pre-sorted dictionaries (in comparison with other popular libraries with linear search)
• flexible configurations - not only one strict list
• low memory usage - disctionaries are not loaded fully into memory (as in other popular libraries)
• frequent updates
• easy collaboration
• large disctionary- 60k+ of domains (not only public email providers) in the dictionary

(back to top)

Built With

This library supports several languages and frameworks.

• PHP
  • 
  • Laravel (current)
  • Symfony (planned)
  • Phalcon (planned)
• JS / TS
  • Vanilla (planned)
  • (planned)
  • (planned)
  • (planned)
  • (planned)
  • (planned)
• Ruby
  • Ruby on Rails (planned)
• Perl
  • Vanilla (planned)

(back to top)

Getting Started

Simple steps to start use the library.

Requires

Check that library works on your PHP version:

• PHP 8.0+
• Composer

Installation

Below is an simple list of step to install library.

1. Open your project directory in the terminal
2. Install package

composer require coodde/laravel-mail-checker

1. Check your composer.json file
2. Check your app.php, that ServiceProvider is installed
3. Check your config directory, that config file mail-checker.php is created

(back to top)

Usage

This table will help to understand possible usage of library and all default values:

Here you will find different cases of usage.

Checking that mail address registered in Russian mail provider:

use Coodde\LaravelMailChecker\Rules\MailRegionsValidation;
use Coodde\LaravelMailChecker\Regions;

public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'email' => ['required', new MailRegionsValidation([Regions::RUSSIA])],
    ]);
 
    // OR with configs from env, ex. (country code) - MAIL_CHECKER_REGIONS=ru

    $validated = $request->validate([
        'email' => ['required', new MailRegionsValidation()],
    ]);
 
    // Request is valid...
 
    return redirect('/list');
}

Checking that mail address registered in "ru" or "mail.by" domains:

use Coodde\LaravelMailChecker\Rules\MailDomainsValidation;
use Coodde\LaravelMailChecker\Regions;

public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'email' => ['required', new MailDomainsValidation(['ru', 'mail.by'])],
    ]);
 
    // OR with configs from env, ex. - MAIL_CHECKER_DOMAINS=ru,mail.by

    $validated = $request->validate([
        'email' => ['required', new MailDomainsValidation()],
    ]);

    // Request is valid...
 
    return redirect('/list');
}

Checking that mail address is placed in dangerous or suspicious lists:

use Coodde\LaravelMailChecker\Rules\MailListedValidation;
use Coodde\LaravelMailChecker\Regions;

public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'email' => ['required', new MailListedValidation([MailListedValidation::CATEGORY_DANGEROUS, MailListedValidation::CATEGORY_SUSPICIOUS])],
    ]);

    // OR with configs from env, ex. - MAIL_CHECKER_CATEGORIES=dangerous,suspicious

    $validated = $request->validate([
        'email' => ['required', new MailListedValidation()],
    ]);
 
    // Request is valid...
 
    return redirect('/list');
}

Complex validation to allow only corporate emails, :

use Coodde\LaravelMailChecker\Rules\MailValidation;
use Coodde\LaravelMailChecker\Regions;

public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'email' => [
        	'required',
        	new MailValidation(
        		[
        			MailListedValidation::CATEGORY_DANGEROUS,
        			MailListedValidation::CATEGORY_SUSPICIOUS,
        			MailListedValidation::CATEGORY_TEMPORARY,
        			MailListedValidation::CATEGORY_PAID,
        			MailListedValidation::CATEGORY_PUBLIC,
        		],
        		[
        			'fb.com',
        		],
        		[
        			Regions::RUSSIA,
        			Regions::BELARUS,
        		],
        	),
       	],
    ]);

    // OR with separate validators

    $validated = $request->validate([
        'email' => [
        	'required',
        	new MailListedValidation([
    			MailListedValidation::CATEGORY_DANGEROUS,
    			MailListedValidation::CATEGORY_SUSPICIOUS,
    			MailListedValidation::CATEGORY_TEMPORARY,
    			MailListedValidation::CATEGORY_PAID,
    			MailListedValidation::CATEGORY_PUBLIC,
        	]),
        	new MailDomainsValidation([
    			'fb.com',
    		]),
        	new MailRegionsValidation([
    			Regions::RUSSIA,
    			Regions::BELARUS,
    		]),
       	],
    ]);
 
    // Request is valid...
 
    return redirect('/list');
}

Of course you can combine restrictioned domains, countries, and categories

(back to top)

Roadmap

• Checking by countries
• Checking by domains
• Prepared lists
  • Dangerous - usually scaming servers / domains
  • Suspicios - usually spaming servers / domains
  • Paid - mail providers with non-free subscription
  • Temporary - services for mails which will be removed soon after creation
  • Public - popular free services like gmail, outlook, etc
• Checking by prepaired lists
  • From files - it uses binary search without file content buffering
  • From cache - cache files with lists compiled into php file
  • From memory - storing lists in memcache
  • From database - by using PDO library+

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

✅ Run refactors using Rector

composer refacto

⚗️ Run static analysis using PHPStan:

composer test:types

✅ Run unit tests using PEST

composer test:unit

🚀 Run the entire test suite:

composer test

Top contributors:

(back to top)

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

(back to top)

Contact

Svyatoslav Ryzhok - [e-mail]

Platform Link: https://coodde.com

(back to top)