Implemented customizable exception. Closes #13.

Author: ezzatron

src/Eloquent/Enumeration/Enumeration.php

@@ -11,6 +11,8 @@
 
 namespace Eloquent\Enumeration;
 
+use Exception;
+
 /**
  * Base class for C++ style enumerations.
  */
@@ -22,7 +24,7 @@ abstract class Enumeration extends Multiton
      * @param scalar $value The value associated with the member instance.
      *
      * @return Enumeration The first member instance with the supplied value.
-     * @throws UndefinedInstanceException If no associated instance is found.
+     * @throws Exception\UndefinedInstanceException If no associated instance is found.
      */
     public static final function instanceByValue($value)
     {
@@ -32,7 +34,7 @@ public static final function instanceByValue($value)
             }
         }
 
-        throw new Exception\UndefinedInstanceException(get_called_class(), 'value', $value);
+        throw static::createUndefinedInstanceException(get_called_class(), 'value', $value);
     }
 
     /**
@@ -66,7 +68,7 @@ protected static final function initializeMultiton()
      * @param string $key The string key to associate with this member instance.
      * @param scalar $value The value of this member instance.
      *
-     * @throws ExtendsConcreteException If the constructed instance has an invalid inheritance hierarchy.
+     * @throws Exception\ExtendsConcreteException If the constructed instance has an invalid inheritance hierarchy.
      */
     protected function __construct($key, $value)
     {

src/Eloquent/Enumeration/Exception/Exception.php

@@ -11,6 +11,9 @@
 
 namespace Eloquent\Enumeration\Exception;
 
+use Exception;
+use LogicException;
+
 /**
  * The supplied member instance extends an already concrete base class.
  *
@@ -22,12 +25,42 @@ final class ExtendsConcreteException extends LogicException
     /**
      * Construct a new ExtendsConcreteException instance.
      *
-     * @param string $class The class of the supplied instance.
+     * @param string $className The class of the supplied instance.
      * @param string $parentClass The concrete parent class.
-     * @param \Exception $previous The previous exception, if any.
+     * @param Exception $previous The previous exception, if any.
+     */
+    public function __construct($className, $parentClass, Exception $previous = null)
+    {
+        $this->className = $className;
+        $this->parentClass = $parentClass;
+
+        parent::__construct(
+            sprintf(
+                "Class '%s' cannot extend concrete class '%s'.",
+                $this->className(),
+                $this->parentClass()
+            ),
+            0,
+            $previous
+        );
+    }
+
+    /**
+     * @return string
      */
-    public function __construct($class, $parentClass, \Exception $previous = null)
+    public function className()
     {
-        parent::__construct("Class '".$class."' cannot extend concrete class '".$parentClass."'.", $previous);
+        return $this->className;
     }
+
+    /**
+     * @return string
+     */
+    public function parentClass()
+    {
+        return $this->parentClass;
+    }
+
+    private $className;
+    private $parentClass;
 }

src/Eloquent/Enumeration/Exception/ExtendsConcreteException.php

@@ -11,31 +11,65 @@
 
 namespace Eloquent\Enumeration\Exception;
 
+use Exception;
+use LogicException;
+
 /**
  * The requested member instance was not found.
  */
-final class UndefinedInstanceException extends LogicException
+final class UndefinedInstanceException extends LogicException implements UndefinedInstanceExceptionInterface
 {
     /**
      * Construct a new UndefinedInstanceException instance.
      *
-     * @param string $class The class from which the member was requested.
+     * @param string $className The class from which the member was requested.
      * @param string $property The name of the property used to search for the member.
-     * @param string $value The value of the property used to search for the member.
-     * @param \Exception $previous The previous exception, if any.
+     * @param mixed $value The value of the property used to search for the member.
+     * @param Exception $previous The previous exception, if any.
+     */
+    public function __construct($className, $property, $value, Exception $previous = null)
+    {
+        $this->className = $className;
+        $this->property = $property;
+        $this->value = $value;
+
+        parent::__construct(
+            sprintf(
+                "No instance with %s equal to %s defined in class '%s'.",
+                $this->property(),
+                var_export($this->value(), true),
+                $this->className()
+            ),
+            0,
+            $previous
+        );
+    }
+
+    /**
+     * @return string
+     */
+    public function className()
+    {
+        return $this->className;
+    }
+
+    /**
+     * @return string
      */
-    public function __construct($class, $property, $value, \Exception $previous = null)
+    public function property()
     {
-        $message =
-            "No instance with ".
-            $property.
-            " equal to ".
-            var_export($value, true).
-            " defined in class '".
-            $class.
-            "'."
-        ;
-
-      parent::__construct($message, $previous);
+        return $this->property;
     }
+
+    /**
+     * @return mixed
+     */
+    public function value()
+    {
+        return $this->value;
+    }
+
+    private $className;
+    private $property;
+    private $value;
 }

src/Eloquent/Enumeration/Exception/LogicException.php

@@ -0,0 +1,35 @@
+<?php
+
+/*
+ * This file is part of the Enumeration package.
+ *
+ * Copyright © 2012 Erin Millard
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+// @codeCoverageIgnoreStart
+
+namespace Eloquent\Enumeration\Exception;
+
+/**
+ * Interface used to mark all exceptions thrown when an undefined instance is requested.
+ */
+interface UndefinedInstanceExceptionInterface
+{
+    /**
+     * @return string
+     */
+    public function className();
+
+    /**
+     * @return string
+     */
+    public function property();
+
+    /**
+     * @return mixed
+     */
+    public function value();
+}

src/Eloquent/Enumeration/Exception/UndefinedInstanceException.php

@@ -38,7 +38,7 @@ public static final function multitonInstances()
      * @param string $key The string key associated with the member instance.
      *
      * @return Multiton The member instance associated with the given string key.
-     * @throws UndefinedInstanceException If no associated instance is found.
+     * @throws Exception\UndefinedInstanceException If no associated instance is found.
      */
     public static final function instanceByKey($key)
     {
@@ -47,7 +47,7 @@ public static final function instanceByKey($key)
             return $instances[$key];
         }
 
-        throw new Exception\UndefinedInstanceException(get_called_class(), 'key', $key);
+        throw static::createUndefinedInstanceException(get_called_class(), 'key', $key);
     }
 
     /**
@@ -57,15 +57,16 @@ public static final function instanceByKey($key)
      * @param mixed $value The value to match.
      *
      * @return Multiton The first member instance for which $instance->{$property}() === $value.
-     * @throws UndefinedInstanceException If no associated instance is found.
+     * @throws Exception\UndefinedInstanceException If no associated instance is found.
      */
     public static final function instanceBy($property, $value) {
         foreach (static::multitonInstances() as $instance) {
             if ($instance->{$property}() === $value) {
                 return $instance;
             }
         }
-        throw new Exception\UndefinedInstanceException(get_called_class(), $property, $value);
+
+        throw static::createUndefinedInstanceException(get_called_class(), $property, $value);
     }
 
     /**
@@ -74,15 +75,16 @@ public static final function instanceBy($property, $value) {
      * @param callback $predicate The predicate applies to the multiton instance to find a match.
      *
      * @return Multiton The first member instance for which $predicate($instance) evaluates to boolean true.
-     * @throws UndefinedInstanceException If no associated instance is found.
+     * @throws Exception\UndefinedInstanceException If no associated instance is found.
      */
     public static final function instanceByPredicate($predicate) {
         foreach (static::multitonInstances() as $instance) {
             if ($predicate($instance)) {
                 return $instance;
             }
         }
-        throw new Exception\UndefinedInstanceException(get_called_class(), '<callback>', '<callback>');
+
+        throw static::createUndefinedInstanceException(get_called_class(), '<callback>', '<callback>');
     }
 
     /**
@@ -92,7 +94,7 @@ public static final function instanceByPredicate($predicate) {
      * @param array $arguments Ignored.
      *
      * @return Multiton The member instance associated with the given string key.
-     * @throws UndefinedInstanceException If no associated instance is found.
+     * @throws Exception\UndefinedInstanceException If no associated instance is found.
      */
     public static final function __callStatic($key, array $arguments)
     {
@@ -131,6 +133,26 @@ public function __toString()
      */
     protected static function initializeMultiton() {}
 
+    /**
+     * Override this method in child classes to implement custom undefined
+     * instance exceptions for a multiton class.
+     *
+     * @param string $className
+     * @param string $property
+     * @param mixed $value
+     * @param Exception|null $previous
+     *
+     * @return Exception\UndefinedInstanceExceptionInterface
+     */
+    protected static function createUndefinedInstanceException(
+        $className,
+        $property,
+        $value,
+        Exception $previous = null
+    ) {
+        return new Exception\UndefinedInstanceException($className, $property, $value, $previous);
+    }
+
     /**
      * Construct and register a new multiton member instance.
      *
@@ -141,7 +163,7 @@ protected static function initializeMultiton() {}
      *
      * @param string $key The string key to associate with this member instance.
      *
-     * @throws ExtendsConcreteException If the constructed instance has an invalid inheritance hierarchy.
+     * @throws Exception\ExtendsConcreteException If the constructed instance has an invalid inheritance hierarchy.
      */
     protected function __construct($key)
     {
@@ -158,7 +180,7 @@ protected function __construct($key)
      * also handle registration of the instance.
      *
      * @param Multiton $instance The instance to register.
-     * @throws ExtendsConcreteException If the supplied instance has an invalid inheritance hierarchy.
+     * @throws Exception\ExtendsConcreteException If the supplied instance has an invalid inheritance hierarchy.
      */
     private static function registerMultiton(self $instance)
     {

src/Eloquent/Enumeration/Exception/UndefinedInstanceExceptionInterface.php

@@ -13,17 +13,16 @@
 
 use Eloquent\Enumeration\Test\Fixture\InvalidEnumeration;
 use Eloquent\Enumeration\Test\Fixture\ValidEnumeration;
+use PHPUnit_Framework_TestCase;
+use ReflectionClass;
 
-/**
- * @covers Eloquent\Enumeration\Enumeration
- */
-class EnumerationTest extends \PHPUnit_Framework_TestCase
+class EnumerationTest extends PHPUnit_Framework_TestCase
 {
     protected function setUp()
     {
         parent::setUp();
 
-        $reflector = new \ReflectionClass(__NAMESPACE__.'\Multiton');
+        $reflector = new ReflectionClass(__NAMESPACE__.'\Multiton');
         $instancesProperty = $reflector->getProperty('instances');
         $instancesProperty->setAccessible(true);
         $instancesProperty->setValue(null, array());