coodde/mail-checker

Flexible PHP package for complex mail validation

0.1.1 2024-11-19 19:16 UTC

Requires

• php: >8.0.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

MIT

• Svyatoslav Ryzhok

• package
• php
• email
• validator
• checker

README

PHP Mail Checker

This package provides simple checker for emails, to validate mail providers.

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
  • Vanilla
  • 
  • 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/mail-checker

1. Check your composer.json file

(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\MailChecker\MailChecker;
use Coodde\MailChecker\Regions;
use Coodde\MailChecker\Exceptions\MailCheckException;
use Coodde\MailChecker\Exceptions\RegionMailCheckException;

$mailChecker = new MailChecker([], [], [Regions::RUSSIA]);

// This will return boolean value
$result = $mailChecker->allowed('[e-mail]');
// or
$result = $mailChecker->forbidden('[e-mail]');

// Also you can catch exception
try {
  $mailChecker->validate('[e-mail]');
} catch (RegionMailCheckException $e) {
  echo "Forbidden region";
} catch (MailCheckException $e) {
  echo "Wrong mail format (not validated before checking)";
} catch (\Exception $e) {
  echo "Unhandled exception";
}

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

use Coodde\MailChecker\MailChecker;
use Coodde\MailChecker\Regions;
use Coodde\MailChecker\Exceptions\MailCheckException;
use Coodde\MailChecker\Exceptions\DomainMailCheckException;
use Coodde\MailChecker\Exceptions\ListingMailCheckException;
use Coodde\MailChecker\Exceptions\RegionMailCheckException;

$mailChecker = new MailChecker([], ['ru', 'mail.by'], []);

// This will return boolean value
$result = $mailChecker->allowed('[e-mail]');
// or
$result = $mailChecker->forbidden('[e-mail]');
$result = $mailChecker->forbidden('[e-mail]');

// Also you can catch exception
try {
  $mailChecker->validate('[e-mail]');
} catch (DomainMailCheckException $e) {
  echo "Forbidden domain";
} catch (MailCheckException $e) {
  echo "Wrong mail format (not validated before checking)";
} catch (\Exception $e) {
  echo "Unhandled exception";
}

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

use Coodde\MailChecker\MailChecker;
use Coodde\MailChecker\Regions;
use Coodde\MailChecker\Exceptions\MailCheckException;
use Coodde\MailChecker\Exceptions\ListingMailCheckException;

$mailChecker = new MailChecker([MailChecker::CATEGORY_DANGEROUS, MailChecker::CATEGORY_SUSPICIOUS], [], []);

// This will return boolean value
$result = $mailChecker->allowed('[e-mail]');
// or
$result = $mailChecker->forbidden('[e-mail]');

// Also you can catch exception
try {
  $mailChecker->validate('[e-mail]');
} catch (ListingMailCheckException $e) {
  echo "Dangerous mail provider";
} catch (MailCheckException $e) {
  echo "Wrong mail format (not validated before checking)";
} catch (\Exception $e) {
  echo "Unhandled exception";
}

Alternative way to configure restrictions:

$mailChecker = new MailChecker();

// Forbid countries
$mailChecker->forbidRegions([Regions::RUSSIA]);

// Forbid categories
$mailChecker->forbidCategories([
  MailChecker::CATEGORY_PAID,
  MailChecker::CATEGORY_TEMPORARY,
]);

// Forbid domains
$mailChecker->forbidDomains(['mail.ru']);

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

(back to top)

Roadmap

• Checking by countries
• Checking by domains
• Prepared lists
  • Paid - mail providers with non-free subscription
  • Dangerous - usually spaming servers / domains
  • Public - popular free services like gmail, outlook, etc
  • Temporary - services for mails which will be removed soon after creation
• 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 MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Svyatoslav Ryzhok - [e-mail]

Platform Link: https://coodde.com

(back to top)