Breaking: Split exceptions.php into separate files and renamed exceptions.

Breaking: Rename Specs to SpecCollection and make it immutable.
Better null handling.
Spec: deprecate accessor methods; use read-only property accessors instead.

Author: Craig Manley

README.md

@@ -60,7 +60,7 @@ $error = null;
 try {
 	save_student_score($_POST);
 }
-catch (Validate\ValidationException $e) {
+catch (Validate\Exception\ValidationException $e) {
 	$error = $e->getMessage();
 }
 if ($error) {

TODO

@@ -1,7 +1,7 @@
-Put exceptions in their own files and own namespace subdir.
-Rename Specs to SpecCollection and make it immutable.
-Perhaps rename or move Validation into a subdir of Spec so that it is more obvious that it is a component of Spec.
+Spec: perhaps replace allow_empty and optional with allow_empty_strings and allow_null
+Spec: remove accessor methods since the __get attribute accessor is enough.
+Perhaps rename Validation to Constraints or SpecConstraints.
+In progress: Put exceptions in their own files and own namespace subdir.
 Create proper unit tests according to conventions.
-See other TODOs in classes.
 Check and improve markdown documentation and see it if can be generated.
 Improve examples.

eg/specs.php

@@ -1,18 +1,18 @@
 <?php
 /**
-* Example class that demonstrates the use of the Specs class.
-* The Specs class is simply a collection of Spec objects.
-* Specs objects can be used as arrays since they implement the Countable, IteratorAggregate, and ArrayAccess interfaces.
+* Example class that demonstrates the use of the SpecCollection class.
+* The SpecCollection class is simply a collection of Spec objects.
+* SpecCollection objects can be used as arrays since they implement the Countable, IteratorAggregate, and ArrayAccess interfaces.
 */
-require_once(__DIR__ . '/../src/Specs.php');
+require_once(__DIR__ . '/../src/SpecCollection.php');
 
 
-# A Specs object can be created in 3 possible ways, all having the same effect.
+# A SpecCollection object can be created in 3 possible ways, all having the same effect.
 # The contructor is given an associative array of name => Spec pairs
 
 
-# This is the easy/lazy and my preferred way to create a Specs object with it's embedded Spec objects.
-$specs_easy = new Validate\Specs(array(
+# This is the easy/lazy and my preferred way to create a SpecCollection object with it's embedded Spec objects.
+$specs_easy = new Validate\SpecCollection(array(
 	'firstname'	=> array(
 		'description'	=> 'First name',
 		'mb_max_length'	=> 10,
@@ -29,8 +29,8 @@
 ));
 
 
-# This is the less lazy way to create a Specs object with it's embedded Spec objects.
-$specs_lazy = new Validate\Specs(array(
+# This is the less lazy way to create a SpecCollection object with it's embedded Spec objects.
+$specs_lazy = new Validate\SpecCollection(array(
 	'firstname'	=> (new Validate\Spec(array(
 		'description'	=> 'First name',
 		'validation'	=> array(
@@ -51,8 +51,8 @@
 ));
 
 
-# This is the proper and most verbose way to create a Specs object with it's embedded Spec objects.
-$specs_proper = new Validate\Specs(array(
+# This is the proper and most verbose way to create a SpecCollection object with it's embedded Spec objects.
+$specs_proper = new Validate\SpecCollection(array(
 	'firstname'	=> (new Validate\Spec(array(
 		'description'	=> 'First name',
 		'validation'	=> (new Validate\Validation(array(
@@ -80,7 +80,7 @@
 
 # Check if all the Spec objects are indeed identical:
 if (count(array_unique(array_map(function($specs) { return var_export($specs,true); }, array($specs_easy, $specs_lazy, $specs_proper) ))) != 1) {
-	die("The Specs objects are not identical!\n");
+	die("The SpecCollection objects are not identical!\n");
 }
 
 
@@ -142,6 +142,12 @@
 
 
 $verbose = true;
+
+foreach ($specs as $k => &$spec) {
+	$spec = new Validate\Spec(['type' => 'float']);	# does nothing to $specs as the iterator works on a copy
+	unset($spec);
+}
+
 foreach ($tests as $name => $test) {
 	$input = $test['input'];
 	$verbose && print "Test: $name\n";

eg/validator_after.php

@@ -60,7 +60,7 @@
 		$record = $validator->validate($record);
 		print 'After validation: ' . print_r($record,true);
 	}
-	catch (Validate\ValidationException $e) {
+	catch (Validate\Exception\ValidationException $e) {
 		print 'Error at record ' . $i . ': ' . $e->getMessage() . "\n";
 		continue;
 	}

eg/validator_before.php

@@ -60,7 +60,7 @@
 		$record = $validator->validate($record);
 		print 'After validation: ' . print_r($record,true);
 	}
-	catch (Validate\ValidationException $e) {
+	catch (Validate\Exception\ValidationException $e) {
 		print 'Error at record ' . $i . ': ' . $e->getMessage() . "\n";
 		continue;
 	}

src/Exception/NamedValueException.php

@@ -0,0 +1,58 @@
+<?php
+/**
+* Contains the Validate\Exception\NamedValueException class.
+*
+* @author    Craig Manley
+* @copyright Copyright © 2018, Craig Manley (www.craigmanley.com)
+* @license   http://www.opensource.org/licenses/mit-license.php Licensed under MIT
+*/
+namespace Validate\Exception;
+
+
+/**
+* @ignore Require dependencies.
+*/
+require_once(__DIR__ . '/ValueException.php');
+
+
+/**
+* NamedValueException class.
+* Extends ValueException by also including the name of the parameter/key of the value that failed validation.
+*
+* @package	cmanley
+*/
+class NamedValueException extends ValueException {
+	protected $name;
+
+	/**
+	* Constructor.
+	*
+	* @param string $name the parameter/key name
+	* @param string $check name of check that failed
+	* @param mixed $value the value that isn't valid
+	* @param string $message optional custom message
+	* @param array $options
+	*/
+	public function __construct($name, $check, $value, $message = null) {
+		$this->name  = $name;
+		$this->check = $check;
+		$this->value = $value;
+		if (is_null($message)) {
+			$message = 'Parameter "' . $name . '" failed validation "' . $check . '" for ' . gettype($this->value) . ' value';
+			if (is_scalar($value)) {
+				$message .= ' ' . $this->getStringPlaceholderValue();
+			}
+		}
+		parent::__construct($check, $value, $message);
+	}
+
+
+	/**
+	* Return the name of the key, if known, that caused the failure.
+	*
+	* @return string|null
+	*/
+	public function getName() {
+		return $this->name;
+	}
+}

src/Exception/ValidationException.php

@@ -0,0 +1,15 @@
+<?php
+/**
+* Contains the Validate\Exception\ValidationException class.
+*
+* @author    Craig Manley
+* @copyright Copyright © 2018, Craig Manley (www.craigmanley.com)
+* @license   http://www.opensource.org/licenses/mit-license.php Licensed under MIT
+*/
+namespace Validate\Exception;
+
+
+/**
+* Base class of all exceptions in this namespace.
+*/
+class ValidationException extends \Exception {}

src/exceptions.php src/Exception/ValueException.php

@@ -1,31 +1,28 @@
 <?php
 /**
-* Contains the ValidationException based classes.
+* Contains the Validate\Exception\ValueException class.
 *
 * @author    Craig Manley
-* @copyright Copyright © 2016, Craig Manley (www.craigmanley.com)
+* @copyright Copyright © 2018, Craig Manley (www.craigmanley.com)
 * @license   http://www.opensource.org/licenses/mit-license.php Licensed under MIT
 */
-namespace Validate;
+namespace Validate\Exception;
 
 
 /**
-* ValidationException class
-*
-* @package Validate
+* @ignore Require dependencies.
 */
-class ValidationException extends \Exception {}
-
-
+require_once(__DIR__ . '/ValidationException.php');
 
 
 /**
-* ValidationCheckException class.
+* ValueException class. Encapsulates the check name, value, and message of the failed validation.
 */
-class ValidationCheckException extends ValidationException {
+class ValueException extends ValidationException {
 	protected $check;
 	protected $value;
 
+
 	/**
 	* Constructor.
 	*
@@ -38,14 +35,15 @@ public function __construct($check, $value, $message = null) {
 		$this->check = $check;
 		$this->value = $value;
 		if (is_null($message)) {
-			$message = 'Failed validation check "' . $check . '" for ' . gettype($this->value) . ' value';
+			$message = 'Failed validation "' . $check . '" for ' . gettype($this->value) . ' value';
 			if (is_scalar($value)) {
 				$message .= ' ' . $this->getStringPlaceholderValue();
 			}
 		}
 		parent::__construct($message);
 	}
 
+
 	/**
 	* Return the name of the check that failed.
 	*
@@ -55,6 +53,7 @@ public function getCheck() {
 		return $this->check;
 	}
 
+
 	/**
 	* Return a string representation of the scalar value that caused the failure, for use in error messages.
 	* If the value was not a scalar, then null is returned.
@@ -76,6 +75,7 @@ public function getStringPlaceholderValue() {
 		return null;
 	}
 
+
 	/**
 	* Return the value that caused the failure.
 	*
@@ -85,6 +85,7 @@ public function getValue() {
 		return $this->value;
 	}
 
+
 	/**
 	* Return a simplified string representation of the value that caused the failure.
 	*
@@ -100,48 +101,3 @@ public function getValueSimple() {
 		return gettype($this->value);
 	}
 }
-
-
-
-
-
-/**
-* ValidationNamedCheckException class.
-*
-* @package	cmanley
-*/
-class ValidationNamedCheckException extends ValidationCheckException {
-	protected $name;
-
-	/**
-	* Constructor.
-	*
-	* @param string $name the parameter/key name
-	* @param string $check name of check that failed
-	* @param mixed $value the value that isn't valid
-	* @param string $message optional custom message
-	* @param array $options
-	*/
-	public function __construct($name, $check, $value, $message = null) {
-		$this->name  = $name;
-		$this->check = $check;
-		$this->value = $value;
-		if (is_null($message)) {
-			$message = 'Parameter "' . $name . '" failed validation check "' . $check . '" for ' . gettype($this->value) . ' value';
-			if (is_scalar($value)) {
-				$message .= ' ' . $this->getStringPlaceholderValue();
-			}
-		}
-		parent::__construct($check, $value, $message);
-	}
-
-
-	/**
-	* Return the name of the key, if known, that caused the failure.
-	*
-	* @return string|null
-	*/
-	public function getName() {
-		return $this->name;
-	}
-}