Merge branch 'master' of github.com:marc-mabe/php-enum into EnumMap

Author: marc-mabe

.travis.yml

@@ -1,7 +1,6 @@
 language: php
 
 php:
-  - 5.2
   - 5.3
   - 5.4
   - 5.5

README.md

@@ -6,7 +6,7 @@
 [![Latest Unstable Version](https://poser.pugx.org/marc-mabe/php-enum/v/unstable.png)](https://packagist.org/packages/marc-mabe/php-enum)
 [![Dependency Status](https://www.versioneye.com/php/marc-mabe:php-enum/dev-master/badge.png)](https://www.versioneye.com/php/marc-mabe:php-enum/dev-master)
 
-This is a native PHP implementation to add enumeration support to PHP 5.x.
+This is a native PHP implementation to add enumeration support to PHP >= 5.3
 It's an abstract class that needs to be extended to use it.
 
 
@@ -32,7 +32,7 @@ It's an abstract class that needs to be extended to use it.
 
 # API
 
-    abstract class MabeEnum_Enum
+    abstract class MabeEnum\Enum
     {
         /**
          * Constructor
@@ -80,7 +80,7 @@ It's an abstract class that needs to be extended to use it.
          * @param string $name            The name of the constant to instantiate
          * @param array  $args            This should be an empty array (no arguments)
          * @throws BadMethodCallException If the called method hasn't the same name as a constant
-         * @return MabeEnum_Enum          The instantiated enum
+         * @return MabeEnum\Enum          The instantiated enum
          */
         final public static __callStatic($name, array $args);
     }
@@ -129,7 +129,9 @@ It's an abstract class that needs to be extended to use it.
 
 ## The way of php-enum:
 
-    class UserStatusEnum extends MabeEnum_Enum
+    use MabeEnum\Enum;
+    
+    class UserStatusEnum extends Enum
     {
         const INACTIVE = 0;
         const ACTIVE   = 1;
@@ -149,23 +151,23 @@ It's an abstract class that needs to be extended to use it.
         {
             if (!$this->status) {
                 // init default status
-                $this->status = new UserStatusEnum(UserStatusEnum::INACTIVE);
+                $this->status = UserStatusEnum::INACTIVE();
             }
             return $this->status;
         }
     }
 
     $user = new User();
     echo 'Default user status: ' . $user->getStatus() . '(' . $user->getStatus()->getValue() . ')' . PHP_EOL;
-    $user->setStatus(new UserStatusEnum(UserStatusEnum::ACTIVE));
+    $user->setStatus(UserStatusEnum::ACTIVE());
     echo 'Changed user status: ' . $user->getStatus() . '(' . $user->getStatus()->getValue() . ')' . PHP_EOL;
 
 **PRINTS**
 
     Default user status: INACTIVE (0)
     Changed user status: ACTIVE (1)
 
-* Validation will be already done on basic class ```MabeEnum_Enum```
+* Validation will be already done on basic class ```MabeEnum\Enum```
 * Using type-hint makes arguments save
 * Human readable name of a value is simple accessable
 
@@ -194,7 +196,9 @@ and extract it.
 This example defines the constant ```ONE``` with value ```1``` as default
 value.
 
-    class MyEnumWithDefaultValue extends MabeEnum_Enum
+    use MabeEnum\Enum;
+    
+    class MyEnumWithDefaultValue extends Enum
     {
         const ONE = 1;
         const TWO = 2;
@@ -209,7 +213,9 @@ value.
 
 It's also possible to extend other enumerations.
 
-    class MyEnum extends MabeEnum_Enum
+    use MabeEnum\Enum;
+    
+    class MyEnum extends Enum
     {
         const ONE = 1;
         const TWO = 2;
@@ -222,10 +228,12 @@ It's also possible to extend other enumerations.
 
 ## Simplified instantiation
 
-With PHP >= 5.3 it possible to call one of the defined constants like a method
+It's possible to call one of the defined constants like a method
 and you will get the instantiated enum as a result.
 
-    class MyEnum extends MabeEnum_Enum
+    use MabeEnum\Enum;
+    
+    class MyEnum extends Enum
     {
         const ONE = 1;
         const TWO = 2;

composer.json

@@ -17,15 +17,15 @@
     }],
     "license": "BSD-3-Clause",
     "require": {
-        "php": ">=5.0",
+        "php": ">=5.3",
         "ext-reflection": "*"
     },
     "require-dev": {
         "phpunit/phpunit": ">=3.6"
     },
     "autoload": {
         "psr-0": {
-            "MabeEnum_": "src/"
+            "MabeEnum\\": "src/"
         }
     }
 }

src/MabeEnum/Enum.php

@@ -1,16 +1,23 @@
 <?php
 
+namespace MabeEnum;
+
+use ReflectionClass;
+use InvalidArgumentException;
+use LogicException;
+use BadMethodCallException;
+
 /**
  * Class to implement enumerations for PHP 5 (without SplEnum)
  *
  * @link http://github.com/marc-mabe/php-enum for the canonical source repository
  * @copyright Copyright (c) 2012 Marc Bennewitz
  * @license http://github.com/marc-mabe/php-enum/blob/master/LICENSE.txt New BSD License
  */
-abstract class MabeEnum_Enum
+abstract class Enum
 {
     /**
-     * The current selected value
+     * The selected value
      * @var null|scalar
      */
     private $value;
@@ -22,46 +29,53 @@ abstract class MabeEnum_Enum
     private $ordinal;
 
     /**
-     * An array of available constants
-     * @var null|array
+     * An array of available constants by class
+     * @var array ["$class" => ["$const" => $value, ...], ...]
+     */
+    private static $constants = array();
+
+    /**
+     * Already instantiated enums
+     * @param array ["$class.$value" => MabeEnum\Enum, ...]
      */
-    private $constants;
+    private static $instances = array();
 
     /**
      * Constructor
      * 
      * @param scalar $value The value to select
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException On an unknwon or invalid value
+     * @throws LogicException           On ambiguous constant values
      */
-    public function __construct($value)
+    final private function __construct($value)
     {
-        $reflectionClass = new ReflectionClass($this);
-        $constants       = $reflectionClass->getConstants();
-
-        // This is required to make sure that constants of base classes will be the first
-        while ( ($reflectionClass = $reflectionClass->getParentClass()) ) {
-            $constants = $reflectionClass->getConstants() + $constants;
-        }
-        $this->constants = $constants;
-
-        // TODO: Check that constant values are equal (non strict comparison)
-
         // find and set the given value
         // set the defined value because of non strict comparison
-        $const = array_search($value, $this->constants);
+        $constants = static::getConstants();
+        $const     = array_search($value, $constants);
         if ($const === false) {
             throw new InvalidArgumentException("Unknown value '{$value}'");
         }
-        $this->value = $this->constants[$const];
+        $this->value = $constants[$const];
     }
 
     /**
-     * Get all available constants
-     * @return array
+     * Get the selected value
+     * @return string
+     * @see getValue()
+     */
+    final public function __toString()
+    {
+        return (string) $this->value;
+    }
+
+    /**
+     * @throws LogicException Enums are not cloneable
+     *                        because instances are implemented as singletons
      */
-    final public function getConstants()
+    final private function __clone()
     {
-        return $this->constants;
+        throw new LogicException('Enums are not cloneable');
     }
 
     /**
@@ -79,9 +93,13 @@ final public function getValue()
      */
     final public function getName()
     {
-        return array_search($this->value, $this->constants, true);
+        return array_search($this->value, $this::getConstants(), true);
     }
 
+    /**
+     * Get the ordinal number of the selected value
+     * @return int
+     */
     final public function getOrdinal()
     {
         if ($this->ordinal !== null) {
@@ -91,7 +109,7 @@ final public function getOrdinal()
         // detect ordinal
         $ordinal = 0;
         $value   = $this->value;
-        foreach ($this->constants as $constValue) {
+        foreach ($this::getConstants() as $constValue) {
             if ($value === $constValue) {
                 break;
             }
@@ -103,13 +121,89 @@ final public function getOrdinal()
     }
 
     /**
-     * Get the current selected constant name
-     * @return string
-     * @see getName()
+     * Get an enum of the given value
+     *
+     * @param scalar $value
+     * @return Enum
+     * @throws InvalidArgumentException On an unknwon or invalid value
+     * @throws LogicException           On ambiguous constant values
      */
-    final public function __toString()
+    static public function get($value)
     {
-        return (string) $this->value;
+        $class = get_called_class();
+        $id    = $class . '.' . $value;
+        if (isset(self::$instances[$id])) {
+            return self::$instances[$id];
+        }
+
+        $instance = new $class($value);
+        self::$instances[$id] = $instance;
+        return $instance;
+    }
+
+    /**
+     * Clears all instantiated enums
+     *
+     * NOTE: This can break singleton behavior ... use it with caution!
+     *
+     * @param null|string $class
+     * @return void
+     */
+    final static function clear()
+    {
+        $class  = get_called_class();
+
+        // clear instantiated enums
+        $prefix       = $class . '.';
+        $prefixLength = strlen($prefix);
+        foreach (self::$instances as $id => $enum) {
+            if (strncasecmp($prefix, $id, $prefixLength) === 0) {
+                unset(self::$instances[$id]);
+            }
+        }
+
+        // clear constants buffer
+        foreach (self::$constants as $constantsClass => & $constants) {
+            if (strcasecmp($class, $constantsClass) === 0) {
+                unset(self::$constants[$constantsClass]);
+                break;
+            }
+        }
+    }
+
+    /**
+     * Get all available constants
+     * @return array
+     * @throws LogicException On ambiguous constant values
+     */
+    final static public function getConstants()
+    {
+        $class = get_called_class();
+        if (isset(self::$constants[$class])) {
+            return self::$constants[$class];
+        }
+
+        $reflection = new ReflectionClass($class);
+        $constants  = $reflection->getConstants();
+
+        // Constant values needs to be unique
+        if (max(array_count_values($constants)) > 1) {
+            $ambiguous = array_map(function ($v) use ($constants) {
+                return implode('/', array_keys($constants, $v)) . '=' . $v;
+            }, array_unique(array_diff_assoc($constants, array_unique($constants))));
+            throw new LogicException(sprintf(
+                'All possible values needs to be unique. The following are ambiguous: %s',
+                implode(', ', $ambiguous)
+            ));
+        }
+
+        // This is required to make sure that constants of base classes will be the first
+        while ( ($reflection = $reflection->getParentClass()) ) {
+            $constants = $reflection->getConstants() + $constants;
+        }
+
+        self::$constants[$class] = $constants;
+        return $constants;
     }
 
     /**
@@ -118,19 +212,18 @@ final public function __toString()
      * This will be called automatically on calling a method
      * with the same name of a defined constant.
      *
-     * NOTE: THIS WORKS FOR PHP >= 5.3 ONLY
-     *
      * @param string $const The name of the constant to instantiate the enum with
      * @param array  $args  There should be no arguments
-     * @throws BadMethodCallException
+     * @throws BadMethodCallException On an unknown constant name (method name)
+     * @throws LogicException         On ambiguous constant values
      */
     final public static function __callStatic($const, array $args)
     {
-        $class      = get_called_class();
-        $classConst = $class . '::' . $const;
+        $classConst = 'static::' . $const;
         if (!defined($classConst)) {
-            throw new BadMethodCallException($classConst . ' not defined');
+            $class = get_called_class();
+            throw new BadMethodCallException($class . '::' . $const . ' not defined');
         }
-        return new $class(constant($classConst));
+        return static::get(constant($classConst));
     }
 }

tests/Bootstrap.php

@@ -11,11 +11,11 @@
 
 function autoload($className)
 {
-    $test = dirname(__FILE__) . '/../src/' . str_replace('_', '/', $className) . '.php';
+    $test = dirname(__FILE__) . '/../src/' . str_replace('\\', '/', $className) . '.php';
     if (file_exists($test)) {
         require $test;
     }
-    $test = dirname(__FILE__) . '/' . str_replace('_', '/', $className) . '.php';
+    $test = dirname(__FILE__) . '/' . str_replace('\\', '/', $className) . '.php';
     if (file_exists($test)) {
         require $test;
     }