Added support for custom data to be passed back by the Verifalia service

Added support for specifying the desired results quality level
Aligned the internal REST client to the Verifalia v1.2 API
Improved documentation for the SDK

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Verifalia
+Copyright (c) 2015-2016 Verifalia - Cobisi Research
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -17,14 +17,45 @@ $ php composer.phar require verifalia/sdk
 
 ### Sample usage ###
 
-The example below shows how to have your PHP application to submit and validate a couple of email addresses using the Verifalia PHP helper library:
+The example below shows how to have your PHP application to submit and validate a single email address using the Verifalia PHP helper library:
 
 ```php
 <?php
 	// Initializes Composer
 
 	require_once 'vendor/autoload.php';
+
+	// Configures the Verifalia SDK, using your sub-account SID and auth token.
+	// Sub-accounts can be managed through the Verifalia dashboard, in the clients area.
+
+	$verifalia = new Verifalia\Client('YOUR-ACCOUNT-SID', 'YOUR-AUTH-TOKEN');
 
+	try {
+		// Submits the email addresses to Verifalia and waits until the engine
+		// complete its validation.
+
+		$job = $verifalia
+			->emailValidations
+			->submit('alice@example.com'), NULL);
+
+		// Displays the validation status code
+
+		echo('Validation status: ' . $job->entries[0]->status);
+	}
+	catch (Exception $ex) {
+		echo "Code: " . $ex->getCode() . " Message: " . $ex->getMessage();
+	}
+?>
+```
+
+The `submit()` function allows to validate multiple addresses easily, in a single pass; for this, just pass an array of strings as shown below:
+
+```php
+<?php
+	// Initializes Composer
+
+	require_once 'vendor/autoload.php';
+
 	// Configures the Verifalia SDK, using your sub-account SID and auth token.
 	// Sub-accounts can be managed through the Verifalia dashboard, in the clients area.
 
@@ -51,6 +82,53 @@ The example below shows how to have your PHP application to submit and validate
 ?>
 ```
 
+Starting from version 1.2, the library also allows to specify custom data (your internal customer or record ID, for example) for each entry to be validated, which are then returned to the caller upon the end of the validation job. To use this feature, just pass a `ValidationEntry` instance (or more than one, by way of an array) to the `submit()` function, specifying your custom string:
+
+```php
+	use Verifalia\EmailAddresses\ValidationEntry;
+
+	// ...
+
+	$job = $verifalia
+		->emailValidations
+		->submit(new ValidationEntry('alice@example.com', 'my custom data'), NULL);
+
+	// Displays the results
+
+	for ($x = 0; $x < count($job->entries); $x++) {
+		$entry = $job->entries[$x];
+		echo($entry->inputData . ' - ' . $entry->status . ' - custom: ' . $entry->custom . "\n");
+	}
+
+	// ...
+?>
+```
+
+Also starting from version 1.2, this SDK allows to specify the desired results quality level for an email validation job. To do that, embed your entries - being them a `ValidationEntry` instance (or more than one, by way of an array) or the email address string (or the array of strings to validate) - inside a new `Validation` instance and pass it to the `submit()` function, specifying the desired level in its constructor, as shown below:
+
+```php
+	use Verifalia\EmailAddresses\ValidationEntry;
+	use Verifalia\EmailAddresses\Validation;
+
+	// ...
+
+	// Submits the validation job, using the "extreme" quality level
+
+	$job = $verifalia
+		->emailValidations
+		->submit(new Validation(array('alice@example.com', 'test@@invalid.tld'), 'extreme'), NULL);
+
+	// Displays the results
+
+	for ($x = 0; $x < count($job->entries); $x++) {
+		$entry = $job->entries[$x];
+		echo($entry->inputData . ' - ' . $entry->status . "\n");
+	}
+
+	// ...
+?>
+```
+
 Internally, the `submit()` function sends the email addresses to the Verifalia servers and then polls them until the validations complete.
 Instead of relying on this automatic polling behavior, you may even manually query the Verifalia servers by way of the `query()` function, as shown below:
 
@@ -72,10 +150,14 @@ Instead of relying on this automatic polling behavior, you may even manually que
 			->emailValidations
 			->submit(array('alice@example.com', 'bob@example.net'));
 
-		// Waits until the whole email validation job is completed
+		// Polls the Verifalia service until the whole email validation job is completed
 
 		while ($job->status != 'completed') {
-			$verifalia
+			// Waits for 5 seconds before issuing a new poll request
+
+			sleep(5000);
+
+			$job = $verifalia
 				->emailValidations
 				->query($job->uniqueID);
 		}

composer.json

@@ -1,6 +1,6 @@
 {
 	"name": "verifalia/sdk",
-	"version": "1.1",
+	"version": "1.2",
 	"description": "Verifalia REST API - PHP SDK and helper library for email validation",
 	"homepage": "http://verifalia.com",
 	"keywords": ["verifalia", "email", "validation", "verification", "free", "service", "saas", "list", "hygiene", "cleaning", "mx", "smtp", "mailbox", "scrub"],

lib/Verifalia/EmailAddresses/Validation.php

@@ -0,0 +1,36 @@
+<?php
+	namespace Verifalia\EmailAddresses;
+
+	class Validation {
+		public $entries = NULL;
+		public $quality = NULL;
+
+		public function __construct($entries, $quality = NULL)
+		{
+			$this->entries = array();
+			$this->quality = $quality;
+
+			if (is_array($entries)) {
+				for($x = 0; $x < count($entries); $x++) {
+					$this->addEntry($entries[$x]);
+				}
+			}
+			else {
+				$this->addEntry($entries);
+			}
+		}
+
+		private function addEntry($entry)
+		{
+			if (is_string($entry)) {
+				array_push($this->entries, new ValidationEntry($entry));
+			}
+			else if ($entry instanceof ValidationEntry) {
+				array_push($this->entries, $entry);
+			}
+			else {
+				throw new InvalidArgumentException('Invalid input entries, please review the data you are about to submit to Verifalia.');
+			}
+		}
+	}
+?>

lib/Verifalia/EmailAddresses/ValidationEntry.php

@@ -0,0 +1,14 @@
+<?php
+	namespace Verifalia\EmailAddresses;
+
+	class ValidationEntry {
+		public $inputData = NULL;
+		public $custom = NULL;
+
+		public function __construct($inputData, $custom = NULL)
+		{
+			$this->inputData = $inputData;
+			$this->custom = $custom;
+		}	
+	}
+?>

lib/Verifalia/EmailAddresses/ValidationRestClient.php

@@ -19,28 +19,23 @@ class ValidationRestClient extends \Verifalia\Rest\RestClient {
 		/** 
 		* Submits email addresses to the Verifalia email validation engine.
 		*
-		* @param string|array $emailAddresses The email address(es) to validate.
+		* @param string|array|\Verifalia\EmailAddresses\Validation|\Verifalia\EmailAddresses\ValidationEntry $entries The email address(es) to validate.
 		* @param \Verifalia\WaitForCompletionOptions $waitForCompletionOptions The waiting option for the completion of the email validation job.
 		* @return object An object describing the validation job (which may have been already completed upon returning).
 		*/		
-		function submit($emailAddresses, $waitForCompletionOptions = \Verifalia\WaitForCompletionOptions::DONT_WAIT) {
+		function submit($entries, $waitForCompletionOptions = \Verifalia\WaitForCompletionOptions::DONT_WAIT) {
 			// Builds the input json structure
 
-			$entries = array();
-
-			if (is_array($emailAddresses)) {
-				for($x = 0; $x < count($emailAddresses); $x++) {
-					array_push($entries, array('inputData' => (string)$emailAddresses[$x]));
-				}
-			}
-			else if (is_string($emailAddresses)) {
-				array_push($entries, array('inputData' => $emailAddresses));
+			$validation = NULL;
+
+			if ($entries instanceof Validation) {
+				$validation = $entries;
 			}
 			else {
-				throw new InvalidArgumentException('submit() only accepts strings or array of strings.');
+				$validation = new Validation($entries);
 			}
 
-			$data = array('entries' => $entries);
+			$data = array('entries' => $validation->entries, 'quality' => $validation->quality);
 
 			// Sends the request to the Verifalia servers
 
@@ -53,7 +48,7 @@ function submit($emailAddresses, $waitForCompletionOptions = \Verifalia\WaitForC
 			else {
 				$timeout = $waitForCompletionOptions->timeout;
 			}
-
+			
 			$result = $this->sendRequest("/email-validations",
 				json_encode($data),
 				self::HTTP_METHOD_POST,
@@ -94,7 +89,7 @@ function submit($emailAddresses, $waitForCompletionOptions = \Verifalia\WaitForC
 		/** 
 		* Queries about a specific email validation job, submitted by way of the submit() function.
 		*
-		* @param string|array $emailAddresses The email address(es) to validate.
+		* @param string $uniqueID The identifier of the validation job to retrieve.
 		* @param \Verifalia\WaitForCompletionOptions $waitForCompletionOptions The waiting option for the completion of the email validation job.
 		* @return object An object describing the validation job.
 		*/		

lib/Verifalia/Rest/RestClient.php

@@ -2,9 +2,9 @@
 	namespace Verifalia\Rest;
 
 	abstract class RestClient {
-		const DEFAULT_API_VERSION = 'v1.1';
+		const DEFAULT_API_VERSION = 'v1.2';
 		const DEFAULT_BASE_URL = 'https://api.verifalia.com/';
-		const USER_AGENT = 'verifalia-rest-client/php/1.0';
+		const USER_AGENT = 'verifalia-rest-client/php/1.2';
 
 		// Supported HTTP status codes