Differential D14481 Diff 35023 src/object/PhutilEnum.php

Changeset View

Standalone View

src/object/PhutilEnum.php

This file was added.

				<?php

				/**
				* A basic implementation of an "enum".
				*
				* This class is largely based on [[https://github.com/myclabs/php-enum \|
				* myclabs/php-enum]], which aims to be a "PHP Enum implementation inspired
				* from [[http://php.net/manual/en/class.splenum.php \| SplEnum]]".
				*
				* @task assert Assertions
				* @task construct Construction
				* @task enum Enumeration
				*/
				abstract class PhutilEnum {

				private $key;
				private $value;

				/**
				* Cache enumeration values.
				*
				* This class follows a singleton pattern so that we can do this:
				*
				* ```lang=php
				* $enum === SomeEnum::SOME_VALUE();
				* ```
				*/
				protected static $cache = array();

				/**
				* A flag to indicate whether a @{class:PhutilEnum} implementation is valid.
				*
				* See @{method:assertValidImplementation} for further details.
				*/
				protected static $validImplementations = array();

				/**
				* Creates a new enumeration value.
				*
				* @param wild Enum value.
				* @task construct
				*/
				final private function __construct($value) {
				if (!idx(self::$validImplementations, get_called_class())) {
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0.
				try {
				static::assertValidImplementation();
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				} catch (PhutilInvalidEnumImplementationException $ex) {
				static::$validImplementations[get_called_class()] = false;
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0.
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				throw $ex;
				}

				static::$validImplementations[get_called_class()] = true;
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0.
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				}

				$this->key = static::search($value);
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				$this->value = $value;
				}

				/**
				* Returns a @{class:PhutilEnum} instance from a class constant.
				*
				* TODO
				Lint: TODO Comment Inline Actions This comment has a TODO. Lint: TODO Comment: This comment has a TODO.
				*
				* @param string
				* @param list<wild>
				* @return static
				* @task construct
				*/
				final public static function __callStatic($name, $arguments) {
				$array = static::toArray();
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.

				if (isset($array[$name])) {
				return static::initializeEnum($array[$name]);
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				}

				throw new BadMethodCallException(
				pht(
				'No static method or enumeration constant "%s" in %s',
				$name,
				get_called_class()));
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0.
				}

				/**
				* Returns the enumeration value, as a string.
				*
				* @return string
				*/
				final public function __toString() {
				return (string)$this->value;
				}

				/**
				* TODO
				Lint: TODO Comment Inline Actions This comment has a TODO. Lint: TODO Comment: This comment has a TODO.
				*
				* @param wild
				* @return ???
				* @task construct
				*/
				final private static function initializeEnum($value) {
				if (!array_key_exists($value, static::$cache)) {
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				static::$cache[$value] = new static($value);
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				}

				return static::$cache[$value];
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				}

				/**
				* Returns the enumeration key.
				*
				* @return wild
				* @task enum
				*/
				final public function getKey() {
				return $this->key;
				}

				/**
				* Returns the enumeration value.
				*
				* @return wild
				* @task enum
				*/
				final public function getValue() {
				return $this->value;
				}

				/**
				* Returns the names (keys) of all constants in the enumerator class.
				*
				* @return array
				* @task enum
				*/
				final public static function keys() {
				return array_keys(static::toArray());
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				}

				/**
				* Returns instances of the @{class:PhutilEnum} class for all enumeration
				* constants.
				*
				* @return map<wild, PhutilEnum> Constant name in key, @{class:PhutilEnum}
				* instance in value.
				* @task enum
				*/
				final public static function values() {
				$values = array();

				foreach (static::toArray() as $key => $value) {
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				$values[$key] = static::initializeEnum($value);
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.
				}

				return $values;
				}

				/**
				* Returns all possible enumeration values as an array.
				*
				* @return map<wild, wild> Constant name in key, constant value in value.
				* @task enum
				*/
				final public static function toArray() {
				$class = get_called_class();
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0.
				return id(new ReflectionClass($class))->getConstants();
				}

				/**
				* Return the enumeration key for a specified value.
				*
				* NOTE: This method assumes that enumeration values are unique, see
				* @{method:assertValidImplementation}.
				*
				* @param wild The specification value to search for.
				* @return wild The enumeration key, or `null` is the specified value does
				* not exist.
				* @task enum
				*/
				final private static function search($value) {
				$key = array_search($value, static::toArray(), true);
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.

				if ($key === false) {
				$key = null;
				}

				return $key;
				}

				/**
				* Asserts that a @{class:PhutilEnum} implementation is valid.
				*
				* Specifically, this method asserts that enumeration values are unique. For
				* example, the following @{class:PhutilEnum} implementation is invalid:
				*
				* ```lang=php, counterexample
				* final class PhutilInvalidEnum extends PhutilEnum {
				* const SOMETHING = 'value';
				* const SOMETHING_ELSE = 'value';
				* }
				* ```
				*
				* @return void
				* @task assert
				*/
				final private static function assertValidImplementation() {
				$array = static::toArray();
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `static::` was not introduced until PHP 5.3.

				if (array_values($array) != array_unique(array_values($array))) {
				throw new PhutilInvalidEnumImplementationException(
				pht(
				'%s is not a valid %s implementation. Valid %s implementation '.
				'must have unique enumeration value.',
				get_called_class(),
				Lint: PHP Compatibility Inline Actions This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0. Lint: PHP Compatibility: This codebase targets PHP 5.2.3, but `get_called_class()` was not introduced until PHP 5.3.0.
				__CLASS__,
				__CLASS__));
				}
				}

				}