{"id":37266070,"url":"https://github.com/stymiee/email-validator","last_synced_at":"2026-01-16T00:32:27.578Z","repository":{"id":46952879,"uuid":"278899889","full_name":"stymiee/email-validator","owner":"stymiee","description":"The Email Validator library builds upon PHP's built in `filter_var($emailAddress, FILTER_VALIDATE_EMAIL);` by adding a default MX record check. It also offers additional validation against disposable email addresses, free email address providers, and a custom banned domain list.","archived":false,"fork":false,"pushed_at":"2025-06-11T00:45:21.000Z","size":112,"stargazers_count":32,"open_issues_count":1,"forks_count":8,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-29T13:32:15.148Z","etag":null,"topics":["email","email-validation","php","validation"],"latest_commit_sha":null,"homepage":"https://stymiee.dev","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stymiee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-07-11T16:30:09.000Z","updated_at":"2025-07-19T21:34:17.000Z","dependencies_parsed_at":"2024-04-08T22:33:32.443Z","dependency_job_id":"0928c3dc-254f-44ea-8218-aa5ee8b5f3ea","html_url":"https://github.com/stymiee/email-validator","commit_stats":{"total_commits":58,"total_committers":2,"mean_commits":29.0,"dds":0.03448275862068961,"last_synced_commit":"017a53567aadc82e51773b887d0dff381aae5f2e"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/stymiee/email-validator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stymiee%2Femail-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stymiee%2Femail-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stymiee%2Femail-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stymiee%2Femail-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stymiee","download_url":"https://codeload.github.com/stymiee/email-validator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stymiee%2Femail-validator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28421215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","email-validation","php","validation"],"created_at":"2026-01-16T00:32:26.117Z","updated_at":"2026-01-16T00:32:27.573Z","avatar_url":"https://github.com/stymiee.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Latest Stable Version](https://poser.pugx.org/stymiee/email-validator/v/stable.svg)](https://packagist.org/packages/stymiee/email-validator)\n[![Total Downloads](https://poser.pugx.org/stymiee/email-validator/downloads)](https://packagist.org/packages/stymiee/email-validator)\n![Build](https://github.com/stymiee/email-validator/workflows/Build/badge.svg)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/stymiee/email-validator/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/stymiee/email-validator/?branch=master)\n[![License](https://poser.pugx.org/stymiee/email-validator/license)](https://packagist.org/packages/stymiee/email-validator)\n\n# PHP Email Validator (email-validator)\n\nThe PHP Email Validator will validate an email address for all or some of the following conditions:\n\n- is in a valid format (supports both RFC 5321 and RFC 5322)\n- has configured MX records (optional)\n- is not a disposable email address (optional)\n- is not a free email account (optional)\n- is not a banned email domain (optional)\n- flag Gmail accounts that use the \"plus trick\" and return a sanitized email address\n\nThe Email Validator is configurable, so you have full control over how much validation will occur.\n\n## Requirements\n\n- PHP 7.4 or newer (v1.1.4 will work with PHP 7.2 or newer)\n\n## Installation\n\nSimply add a dependency on `stymiee/email-validator` to your project's `composer.json` file if you use\n[Composer](https://getcomposer.org/) to manage the dependencies of your project.\n\nHere is a minimal example of a `composer.json` file that just defines a dependency on PHP Simple Encryption:\n```json\n{\n    \"require\": {\n        \"stymiee/email-validator\": \"^2\"\n    }\n}\n```\n## Functional Description\n\nThe Email Validator library builds upon PHP's built in `filter_var($emailAddress, FILTER_VALIDATE_EMAIL);` by adding a \ndefault MX record check. It also offers additional validation against disposable email addresses, free email address \nproviders, and a custom banned domain list.\n\n### Validate MX \n\nIf `checkMxRecords` is set to `true` in the configuration (see below) the domain name will be validated to ensure it \nexists and has MX records configured. If the domain does not exist or no MX records exist the odds are the email address\nis not in use.\n\n### Restrict Disposable Email Addresses\n\nMany users who are abusing a system, or not using that system as intended, can use a disposable email service who \nprovides a short-lived (approximately 10 minutes) email address to be used for registrations or user confirmations. If\n`checkDisposableEmail` is set to `true` in the configuration (see below) the domain name will be validated to ensure \nit is not associated with a disposable email address provider. \n\nYou can add you own domains to this list if you find the public list providers do not have one you\nhave identified in their lists. Examples are provided in the `examples` directory which demonstrate how to do this.\n\n### Restrict Free Email Address Providers\n\nMany users who are abusing a system, or not using that system as intended, can use a free email service who \nprovides a free email address which is immediately available to be used for registrations or user confirmations. If\n`checkFreeEmail` is set to `true` in the configuration (see below) the domain name will be validated to ensure \nit is not associated with a free email address provider. \n\nYou can add you own domains to this list if you find the public list providers do not have one you\nhave identified in their lists. Examples are provided in the `examples` directory which demonstrate how to do this.\n\n### Restrict Banned Domains\n\nIf you have users from a domain abusing your system, or you have business rules that require the blocking of certain \ndomains (i.e. public email providers like Gmail or Yahoo mail), you can block then by setting `checkBannedListedEmail` \nto `true` in the configuration (see below) and providing an array of banned domains. Examples are provided in the \n`examples` directory which demonstrate how to do this.\n\n### Flag Gmail Addresses Using The \"Plus Trick\"\n\nGmail offers the ability to create unique email addresses within a Google account by adding a `+` character and unique\nidentifier after the username portion of the email address. If not explicitly checked for a user can create an unlimited \namount of unique email addresses that all belong to the same account. \n\nA special check can be performed when a Gmail account is used and a sanitized email address (e.g. one without the \"plus \ntrick\") can be obtained and then checked for uniqueness in your system.\n\n### Configuration\n\nTo configure the Email Validator you can pass an array with the follow parameters/values:\n\n#### checkMxRecords\n\nA boolean value that enables/disables MX record validation. Enabled by default.\n\n#### checkBannedListedEmail\n\nA boolean value that enables/disables banned domain validation. Disabled by default.\n\n#### checkDisposableEmail\n\nA boolean value that enables/disables disposable email address validation. Disabled by default.\n\n#### checkFreeEmail\n\nA boolean value that enables/disables free email address provider validation. Disabled by default.\n\n#### localDisposableOnly\n\nA boolean value that when set to `true` will not retrieve third party disposable email provider lists. Use this if you \ncache the list of providers locally which is useful when performance matters. Disabled by default.\n\n#### LocalFreeOnly\n\nA boolean value that when set to `true` will not retrieve third party free email provider lists. Use this if you \ncache the list of providers locally which is useful when performance matters. Disabled by default.\n\n#### bannedList\n\nAn array of domains that are not allowed to be used for email addresses.\n\n#### disposableList\n\nAn array of domains that are suspected disposable email address providers.\n\n#### freeList\n\nAn array of domains that are free email address providers.\n\n**Example**\n```php\n$config = [\n    'checkMxRecords' =\u003e true,\n    'checkBannedListedEmail' =\u003e true,\n    'checkDisposableEmail' =\u003e true,\n    'checkFreeEmail' =\u003e true,\n    'bannedList' =\u003e $bannedDomainList,\n    'disposableList' =\u003e $customDisposableEmailList,\n    'freeList' =\u003e $customFreeEmailList,\n];\n$emailValidator = new EmailValidator($config);\n````\n### Example\n```php\n\u003c?php\n\nnamespace EmailValidator;\n\nrequire('../vendor/autoload.php');\n\n$customDisposableEmailList = [\n    'example.com',\n];\n\n$bannedDomainList = [\n    'domain.com',\n];\n\n$customFreeEmailList = [\n    'example2.com',\n];\n\n$testEmailAddresses = [\n    'test@domain.com',\n    'test@johnconde.net',\n    'test@gmail.com',\n    'test@hotmail.com',\n    'test@outlook.com',\n    'test@yahoo.com',\n    'test@domain.com',\n    'test@mxfuel.com',\n    'test@example.com',\n    'test@example2.com',\n    'test@nobugmail.com',\n    'test@cellurl.com',\n    'test@10minutemail.com',\n    'test+example@gmail.com',\n];\n\n$config = [\n    'checkMxRecords' =\u003e true,\n    'checkBannedListedEmail' =\u003e true,\n    'checkDisposableEmail' =\u003e true,\n    'checkFreeEmail' =\u003e true,\n    'bannedList' =\u003e $bannedDomainList,\n    'disposableList' =\u003e $customDisposableEmailList,\n    'freeList' =\u003e $customFreeEmailList,\n];\n$emailValidator = new EmailValidator($config);\n\nforeach ($testEmailAddresses as $emailAddress) {\n    $emailIsValid = $emailValidator-\u003evalidate($emailAddress);\n    echo  ($emailIsValid) ? 'Email is valid' : $emailValidator-\u003egetErrorReason();\n    if ($emailValidator-\u003eisGmailWithPlusChar()) {\n        printf(\n            ' (Sanitized address: %s)',\n            $emailValidator-\u003egetGmailAddressWithoutPlus()\n        );\n    }\n    echo PHP_EOL;\n}\n```\n    \n**Output**\n```\nDomain is banned\nEmail is valid\nDomain is used by free email providers\nDomain is used by free email providers\nDomain is used by free email providers\nDomain is used by free email providers\nDomain is banned\nDomain does not accept email\nDomain is used by disposable email providers\nDomain is used by free email providers\nDomain is used by disposable email providers\nDomain does not accept email\nDomain is used by disposable email providers\nDomain is used by free email providers (Sanitized address: test@gmail.com)\n```\n## Custom Validators\n\nYou can create your own custom validators by extending the `AValidator` class. Here's an example:\n\n```php\nuse EmailValidator\\Validator\\AValidator;\nuse EmailValidator\\EmailAddress;\nuse EmailValidator\\Policy;\n\nclass MyCustomValidator extends AValidator\n{\n    public function validate(EmailAddress $email): bool\n    {\n        // Your custom validation logic here\n        return $email-\u003egetDomain() === 'example.com';\n    }\n}\n\n// Register your custom validator\n$emailValidator = new EmailValidator();\n$emailValidator-\u003eregisterValidator(new MyCustomValidator(new Policy()));\n\n// Use it like any other validator\n$isValid = $emailValidator-\u003evalidate('user@example.com');\n```\n\nCustom validators will be run after all built-in validators. If a custom validator fails, the error code will be set to `EmailValidator::FAIL_CUSTOM` and the error message will be \"Failed custom validation\".\n\n### Best Practices\n\n1. Keep your validation logic focused and single-purpose\n2. Use the Policy class to make your validator configurable\n3. Handle null domains and invalid emails gracefully\n4. Add appropriate unit tests for your custom validator\n5. Document your validator's requirements and behavior\n\n### Example Use Cases\n\n- Domain-specific validation rules\n- Custom business logic for email validation\n- Integration with external services\n- Special character restrictions\n- Custom format requirements\n\n### RFC 5322 Validation\n\nThe library supports full RFC 5322 email validation, which includes:\n- Quoted strings in local parts\n- Comments in local parts and domains\n- Domain literals (IPv4 and IPv6)\n- International domain names (IDNA 2008)\n\n**Example using RFC 5322 validation**\n```php\n\u003c?php\n\nnamespace EmailValidator;\n\nrequire('../vendor/autoload.php');\n\n$config = [\n    'checkMxRecords' =\u003e true,\n    'useRfc5322' =\u003e true  // Enable RFC 5322 validation\n];\n$emailValidator = new EmailValidator($config);\n\n$testEmailAddresses = [\n    // Standard email addresses\n    'user@example.com',\n    \n    // Quoted strings\n    '\"John Doe\"@example.com',\n    '\"very.unusual.@.unusual.com\"@example.com',\n    \n    // Comments\n    'user(comment)@example.com',\n    'user@(comment)example.com',\n    \n    // Domain literals\n    'user@[192.0.2.1]',\n    'user@[IPv6:2001:db8::1]',\n    \n    // International domains\n    'user@münchen.de',\n    'user@xn--mnchen-3ya.de'  // Punycode\n];\n\nforeach ($testEmailAddresses as $emailAddress) {\n    $emailIsValid = $emailValidator-\u003evalidate($emailAddress);\n    echo ($emailIsValid) ? 'Email is valid' : $emailValidator-\u003egetErrorReason();\n    echo PHP_EOL;\n}\n```\n\nThe RFC 5322 validator supports:\n\n1. **Quoted Strings**\n   - Allows special characters and whitespace in local part when quoted\n   - Example: `\"John Doe\"@example.com`\n   - Example: `\"very.unusual.@.unusual.com\"@example.com`\n\n2. **Comments**\n   - Supports comments in both local part and domain\n   - Example: `user(comment)@example.com`\n   - Example: `user@(comment)example.com`\n\n3. **Domain Literals**\n   - Supports both IPv4 and IPv6 addresses\n   - Example: `user@[192.0.2.1]`\n   - Example: `user@[IPv6:2001:db8::1]`\n\n4. **International Domains**\n   - Full IDNA 2008 support\n   - Handles both Unicode and Punycode\n   - Example: `user@münchen.de`\n   - Example: `user@xn--mnchen-3ya.de`\n\n## Notes\n\nThe email address is checked against a list of known disposable email address providers which are aggregated from\npublic disposable email address provider lists. This requires making HTTP requests to get the lists when validating\nthe address.\n\n## Support\n\nIf you require assistance using this library start by viewing the [HELP.md](HELP.md) file included in this package. It\nincludes common problems and solutions as well how to ask for additional assistance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstymiee%2Femail-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstymiee%2Femail-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstymiee%2Femail-validator/lists"}