Initial commit

.gitignore

@@ -0,0 +1,7 @@
+/vendor/
+.idea/
+.DS_Store
+.editorconfig
+.vscode
+.phpunit.cache
+.phpunit.result.cache

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Ray Hughes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,92 @@
+# sendgrid-validation
+[![Packagist](https://img.shields.io/packagist/v/rayhughes/sendgrid-validation.svg)](https://packagist.org/packages/rayhughes/sendgrid-validation)
+[![Minimum PHP Version](https://img.shields.io/badge/php-%3E%3D%207.4-8892BF.svg)](https://php.net/)
+[![Licensed under the MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/RayHughes/moneypot-api/blob/master/LICENSE)
+
+A PHP library to validate email addresses using the Twilio SendGrid [Email Validation API](https://docs.sendgrid.com/ui/managing-contacts/email-address-validation).
+
+## Prerequisites
+- Twilio SendGrid [Email Validation API Key](https://docs.sendgrid.com/ui/managing-contacts/email-address-validation#generating-your-email-validation-api-key)
+- PHP 7.4 or greater
+- [Composer](http://getcomposer.org/)
+
+## Installation
+
+```bash
+composer require rayhughes/sendgrid-validation
+```
+
+## Usage
+
+### Basic
+`EmailValidation()` initialized with default thresholds.
+```php
+use SendGridValidation\EmailValidation;
+use SendGridValidation\Service\SendGridService;
+
+$validation = new EmailValidation(new SendGridService('api-key'));
+
+print_r($validation->validate('[email protected]'));
+
+/** Outputs
+    SendGridValidation\Dto\EmailValidationDto
+    (
+        [isValid] => true
+        [isValidRisk] => true
+        [isValidScore] => true
+        [isDisposable] => false
+        [hasSuggestion] => false
+        [suggestion] => null
+    )
+**/
+````
+`EmailValidation()->validate()` returns an instance of `EmailValidationDto()`
+
+#### EmailValidationDto()
+
+- `$isValid` - Calculated `true` if validation result meets specified thresholds.
+- `$isValidRisk` - Calculated `true` specified risk criteria
+- `$isValidScore` - Calculated `true` if within minimum score threshold.
+- `$isDisposable` - Calculated `true` if an email is considered to be disposable.
+- `$hasSuggestion` - Calculated `true` if a suggestion is available.
+- `$suggestion` - Calculated email suggestion if available. 
+
+```php
+class EmailValidationDto
+{
+    public bool $isValid = false;
+
+    public bool $isValidRisk = false;
+
+    public bool $isValidScore = false;
+
+    public bool $isDisposable = false;
+
+    public bool $hasSuggestion = false;
+
+    public ?string $suggestion = null;
+}
+```
+
+### Advanced
+`EmailValidation()` can be initialized with optional parameters to validate against developer specified thresholds.
+
+- `$allowRisky` - When `true`, considers risky emails `valid` if other conditions are met.
+- `$allowDisposable`- When `true`, considers disposable emails `valid` if other conditions are met.
+- `$checkValidScore` - When `true`, checks SendGrid `valid` emails against the minimum score threshold.
+- `$minSCore` - Default `0.30`. considers emails `invalid` if the minimum score threshold is not met.
+
+```php
+use SendGridValidation\EmailValidation;
+use SendGridValidation\Service\SendGridService;
+
+$validation = new EmailValidation(
+    new SendGridService($apiKey),
+    true, // bool $allowRisky = true,
+    true, // bool $allowDisposable = true,
+    true, // bool $checkValidScore = false,
+    EmailValidation::MIN_SCORE // float $minScore = self::MIN_SCORE (0.30)
+);
+
+$validation->validate($email);
+```

composer.json

@@ -0,0 +1,39 @@
+{
+    "name": "rayhughes/sendgrid-validation",
+    "description": "A PHP library to validate email addresses using the Twilio SendGrid Email Validation API.",
+    "type": "library",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Ray Hughes"
+        }
+    ],
+    "keywords": [
+        "sendgrid",
+        "twilio sendGrid",
+        "sendGrid email validation",
+        "validation api",
+        "email validation"
+    ],
+    "require": {
+        "php": "^7.4",
+        "ext-json": "*",
+        "ext-curl": "*",
+        "ext-mbstring": "*",
+        "guzzlehttp/guzzle": "^7.3"
+    },
+    "require-dev": {
+        "vimeo/psalm": "^4.10",
+        "phpunit/phpunit": "^9.5"
+    },
+    "autoload": {
+        "psr-4": {
+            "SendGridValidation\\": "src"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "SendGridValidation\\Tests\\": "tests"
+        }
+    }
+}