diff --git a/README.md b/README.md index 8f4d484..0225d5b 100644 --- a/README.md +++ b/README.md @@ -24,18 +24,39 @@ php artisan vendor:publish --provider="Kouz\LaravelMailgunValidation\ServiceProv ## Basic Usage Use the following rule to validate your email fields. The rule will first check the address against -PHP's [FILTER_VALIDATE_EMAIL](http://php.net/manual/en/filter.filters.validate.php) and then will call -the Mailgun API. +PHP's [FILTER_VALIDATE_EMAIL](http://php.net/manual/en/filter.filters.validate.php) and then will call the Mailgun API. -**mailgun_email:role,disposable,mailbox,strict** -The field under validation must be formatted as an e-mail address. The following flags can be added to -apply additional validation: +``` +$request->validate([ + 'email' => ['required', 'mailgun_email'], +]); +``` + +Further flags can added to the rule to make the validation more strict. + +``` +$request->validate([ + 'email' => ['required', 'mailgun_email:role,disposable,mailbox,strict'], +]); +``` -* **role** Don't allow role-based addresses. +Each flag if present, will add the following validation rules: + +* **role** Don't allow role-based addresses such as ‘admin’, ‘sales’, ‘webmaster’... * **disposable** Don't allow disposable email domains. -* **mailbox** Verify mailbox. Add strict flag to ensure that Mailgun was able to verify a mailbox and didn't return "Unknown". +* **mailbox** A call is made to the ESP to verify the mailboxes existence. Add strict flag to ensure that Mailgun was able to verify a mailbox and didn't return "Unknown". * **strict** Always require a response from Mailgun to validate. By default if a API request fails, the validation will pass. The strict flag ensures that a Mailgun response was recieved. +## Recommended Usage +The following configuration will try to check if the email addresses mailbox exists and is not a disposable email address. If +Mailgun is not contactable or Mailgun can't perform the mailbox check, the validation will fall back on PHP's FILTER_VALIDATE_EMAIL. + +``` +$request->validate([ + 'email' => ['required', 'mailgun_email:disposable,mailbox'], +]); +``` + ## License This project is licensed under a MIT License which you can find [in this LICENSE](https://github.com/TheoKouzelis/laravel-mailgun-email-validation/blob/master/LICENSE).