{"id":22764610,"url":"https://github.com/kuria/enum","last_synced_at":"2025-03-30T10:14:14.831Z","repository":{"id":57009934,"uuid":"95931977","full_name":"kuria/enum","owner":"kuria","description":"Emulated enumeration objects in PHP","archived":false,"fork":false,"pushed_at":"2023-04-22T14:38:49.000Z","size":31,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-06T06:04:39.232Z","etag":null,"topics":["enum","enumeration","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kuria.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-01T00:07:42.000Z","updated_at":"2023-09-19T17:45:20.000Z","dependencies_parsed_at":"2025-02-05T12:12:05.351Z","dependency_job_id":"828deb03-8072-4265-bca5-00377befc72c","html_url":"https://github.com/kuria/enum","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuria%2Fenum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuria%2Fenum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuria%2Fenum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuria%2Fenum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuria","download_url":"https://codeload.github.com/kuria/enum/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246301995,"owners_count":20755514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["enum","enumeration","php"],"created_at":"2024-12-11T12:09:29.146Z","updated_at":"2025-03-30T10:14:14.813Z","avatar_url":"https://github.com/kuria.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Enum\n####\n\nEmulated enumeration objects in PHP.\n\nThe interface is similar to `SplEnum \u003chttp://php.net/manual/en/class.splenum.php\u003e`_\nbut doesn't require any PHP extensions and provides more functionality.\n\n.. image:: https://travis-ci.com/kuria/enum.svg?branch=master\n   :target: https://travis-ci.com/kuria/enum\n\n.. contents::\n\n\nFeatures\n********\n\n- immutability\n- ensured unique keys and values\n- simple to use (just extend a class and define some class constants)\n- many methods related to keys\n- values and their enumeration, maps and checking\n- enum instances\n- detailed exception messages\n\n\nRequirements\n************\n\n- PHP 7.1+\n\n\nUsage\n*****\n\n.. _Enum:\n\n``Enum``\n========\n\nThe static ``Enum`` class provides access to the defined key-value pairs.\n\n\nDefining an enum class\n----------------------\n\n.. code:: php\n\n   \u003c?php\n\n   use Kuria\\Enum\\Enum;\n\n   abstract class DayOfTheWeek extends Enum\n   {\n       const MONDAY = 0;\n       const TUESDAY = 1;\n       const WEDNESDAY = 2;\n       const THURSDAY = 3;\n       const FRIDAY = 4;\n       const SATURDAY = 5;\n       const SUNDAY = 6;\n   }\n\n.. NOTE::\n\n   Private and protected constants are ignored.\n\n\nCustom key-value source\n^^^^^^^^^^^^^^^^^^^^^^^\n\nTo define key-value pairs using some other source than class constants, override the static\n``determineKeyToValueMap()`` method:\n\n.. code:: php\n\n   \u003c?php\n\n   use Kuria\\Enum\\Enum;\n\n   abstract class Example extends Enum\n   {\n      protected static function determineKeyToValueMap(): array\n      {\n           return [\n               'FOO' =\u003e 'bar',\n               'BAZ' =\u003e 'qux',\n               'QUUX' =\u003e 'quuz',\n           ];\n      }\n   }\n\n\nSupported value types\n---------------------\n\nOnly string, integer and null values are supported.\n\nValues must be unique when used as an array key. See `Value type coercion`_.\n\nValues are looked up and compared with the same type-coercion rules as\nPHP array keys. See `Value type coercion`_.\n\n\nMethod overview\n---------------\n\nChecking keys and values\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nVerify the existence of a key or a value:\n\n.. code:: php\n\n   \u003c?php\n\n   var_dump(\n       DayOfTheWeek::hasKey('MONDAY'),\n       DayOfTheWeek::hasValue(0)\n   );\n\nOutput:\n\n::\n\n  bool(true)\n  bool(true)\n\n\nEnsuring existence of keys and values\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nMake sure a key or a value exists, otherwise throw an exception:\n\n.. code:: php\n\n   \u003c?php\n\n   DayOfTheWeek::ensureKey('MONDAY');\n   DayOfTheWeek::ensureValue(0);\n\nSee `Error handling`_.\n\n\nGetting keys for values or values for keys\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nKeys and values can be looked up using their counterpart:\n\n.. code:: php\n\n   \u003c?php\n\n   var_dump(\n       DayOfTheWeek::getValue('FRIDAY'),\n       DayOfTheWeek::getKey(4)\n   );\n\nOutput:\n\n::\n\n  int(4)\n  string(6) \"FRIDAY\"\n\n.. NOTE::\n\n   If the key or value doesn't exist, an exception will be thrown. See `Error handling`_.\n\n   To get ``NULL`` instead of an exception, use the ``findValue()`` or ``findKey()``\n   method instead.\n\n\nGetting key/value lists and maps\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: php\n\n   \u003c?php\n\n   echo 'DayOfTheWeek::getKeys(): '; print_r(DayOfTheWeek::getKeys());\n   echo 'DayOfTheWeek::getValues(): '; print_r(DayOfTheWeek::getValues());\n   echo 'DayOfTheWeek::getMap(): '; print_r(DayOfTheWeek::getMap());\n   echo 'DayOfTheWeek::getKeyMap(): '; print_r(DayOfTheWeek::getKeyMap());\n   echo 'DayOfTheWeek::getValueMap(): '; print_r(DayOfTheWeek::getValueMap());\n\nOutput:\n\n::\n\n  DayOfTheWeek::getKeys(): Array\n  (\n      [0] =\u003e MONDAY\n      [1] =\u003e TUESDAY\n      [2] =\u003e WEDNESDAY\n      [3] =\u003e THURSDAY\n      [4] =\u003e FRIDAY\n      [5] =\u003e SATURDAY\n      [6] =\u003e SUNDAY\n  )\n  DayOfTheWeek::getValues(): Array\n  (\n      [0] =\u003e 0\n      [1] =\u003e 1\n      [2] =\u003e 2\n      [3] =\u003e 3\n      [4] =\u003e 4\n      [5] =\u003e 5\n      [6] =\u003e 6\n  )\n  DayOfTheWeek::getMap(): Array\n  (\n      [MONDAY] =\u003e 0\n      [TUESDAY] =\u003e 1\n      [WEDNESDAY] =\u003e 2\n      [THURSDAY] =\u003e 3\n      [FRIDAY] =\u003e 4\n      [SATURDAY] =\u003e 5\n      [SUNDAY] =\u003e 6\n  )\n  DayOfTheWeek::getKeyMap(): Array\n  (\n      [MONDAY] =\u003e 1\n      [TUESDAY] =\u003e 1\n      [WEDNESDAY] =\u003e 1\n      [THURSDAY] =\u003e 1\n      [FRIDAY] =\u003e 1\n      [SATURDAY] =\u003e 1\n      [SUNDAY] =\u003e 1\n  )\n  DayOfTheWeek::getValueMap(): Array\n  (\n      [0] =\u003e MONDAY\n      [1] =\u003e TUESDAY\n      [2] =\u003e WEDNESDAY\n      [3] =\u003e THURSDAY\n      [4] =\u003e FRIDAY\n      [5] =\u003e SATURDAY\n      [6] =\u003e SUNDAY\n  )\n\n\nGetting pairs\n^^^^^^^^^^^^^\n\nA pair is an array with a single key and the corresponding value. They can be retrieved using either\nthe key or the value:\n\n.. code:: php\n\n   \u003c?php\n\n   var_dump(DayOfTheWeek::getPair(DayOfTheWeek::MONDAY));\n   var_dump(DayOfTheWeek::getPairByKey('FRIDAY'));\n\nOutput:\n\n::\n\n  array(1) {\n    [\"MONDAY\"]=\u003e\n    int(0)\n  }\n  array(1) {\n    [\"FRIDAY\"]=\u003e\n    int(4)\n  }\n\n\nCounting members\n^^^^^^^^^^^^^^^^\n\n.. code:: php\n\n   \u003c?php\n\n   var_dump(DayOfTheWeek::count());\n\nOutput:\n\n::\n\n  int(7)\n\n\n.. _EnumObject:\n\n``EnumObject``\n==============\n\nThe ``EnumObject`` class extends from Enum_ and adds factory methods to create instances.\n\n\nDefining an enum object class\n-----------------------------\n\n.. code:: php\n\n   \u003c?php\n\n   use Kuria\\Enum\\EnumObject;\n\n   /**\n    * @method static static RED()\n    * @method static static GREEN()\n    * @method static static BLUE()\n    */\n   class Color extends EnumObject\n   {\n       const RED = 'r';\n       const GREEN = 'g';\n       const BLUE = 'b';\n   }\n\n.. NOTE::\n\n   The ``@method`` annotations are not required, but they will aid in code-completion and inspection.\n\n   See `Magic static factory methods \u003cUsing the magic static factory method_\u003e`_.\n\n\nCreating instances\n------------------\n\nInstances can be created by one of the factory methods. Those instances are cached internally\nand reused, so that multiple calls to the factory methods with the same key or value will yield\nthe same instance.\n\nEnum instances cannot be cloned.\n\n\nUsing a value\n^^^^^^^^^^^^^\n\n.. code:: php\n\n   \u003c?php\n\n   $color = Color::fromValue(Color::RED);\n\n   var_dump($color);\n\nOutput:\n\n::\n\n  object(Foo\\Color)#5 (2) {\n    [\"key\"]=\u003e\n    string(3) \"RED\"\n    [\"value\"]=\u003e\n    string(1) \"r\"\n  }\n\n\nUsing a key\n^^^^^^^^^^^\n\n.. code:: php\n\n   \u003c?php\n\n   $color = Color::fromKey('GREEN');\n\n   var_dump($color);\n\nOutput:\n\n::\n\n  object(Foo\\Color)#3 (2) {\n    [\"key\"]=\u003e\n    string(5) \"GREEN\"\n    [\"value\"]=\u003e\n    string(1) \"g\"\n  }\n\n\nUsing the magic static factory method\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nFor every key there is a static method with the same name, which returns an instance\nfor that key-value pair.\n\n.. code:: php\n\n   \u003c?php\n\n   $color = Color::BLUE();\n\n   var_dump($color);\n\n\nOutput:\n\n::\n\n  object(Foo\\Color)#5 (2) {\n    [\"key\"]=\u003e\n    string(4) \"BLUE\"\n    [\"value\"]=\u003e\n    string(1) \"b\"\n  }\n\n.. WARNING::\n\n   Magic static factory method names are case-sensitive.\n\n\nGetting all instances\n^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: php\n\n   \u003c?php\n\n   var_dump(Color::all());\n\nOutput:\n\n::\n\n  array(3) {\n    [\"RED\"]=\u003e\n    object(Foo\\Color)#5 (2) {\n      [\"key\"]=\u003e\n      string(3) \"RED\"\n      [\"value\"]=\u003e\n      string(1) \"r\"\n    }\n    [\"GREEN\"]=\u003e\n    object(Foo\\Color)#4 (2) {\n      [\"key\"]=\u003e\n      string(5) \"GREEN\"\n      [\"value\"]=\u003e\n      string(1) \"g\"\n    }\n    [\"BLUE\"]=\u003e\n    object(Foo\\Color)#2 (2) {\n      [\"key\"]=\u003e\n      string(4) \"BLUE\"\n      [\"value\"]=\u003e\n      string(1) \"b\"\n    }\n  }\n\n\nMethod overview\n---------------\n\nGetting the key and value\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: php\n\n   \u003c?php\n\n   $color = Color::RED();\n\n   var_dump(\n       $color-\u003ekey(),\n       $color-\u003evalue()\n   );\n\nOutput:\n\n::\n\n  string(3) \"RED\"\n  string(1) \"r\"\n\n\nGetting the pair\n^^^^^^^^^^^^^^^^\n\n.. code:: php\n\n   \u003c?php\n\n   $color = Color::GREEN();\n\n   var_dump($color-\u003epair());\n\nOutput:\n\n::\n\n  array(1) {\n    [\"GREEN\"]=\u003e\n    string(1) \"g\"\n  }\n\n\nComparing the key and value\n^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: php\n\n  \u003c?php\n\n   $color = Color::RED();\n\n   var_dump(\n       $color-\u003eis('RED'),   // compare key\n       $color-\u003eis('GREEN'), // compare key\n       $color-\u003eequals('r'), // compare value\n       $color-\u003eequals('g')  // compare value\n   );\n\nOutput:\n\n::\n\n  bool(true)\n  bool(false)\n  bool(true)\n  bool(false)\n\n\nString conversion\n^^^^^^^^^^^^^^^^^\n\nConverting an instance to a string will yield its value (cast to a string):\n\n.. code:: php\n\n   \u003c?php\n\n   $color = Color::BLUE();\n\n   echo $color;\n\nOutput:\n\n::\n\n  b\n\n\nError handling\n==============\n\nMost error states are handled by throwing an exception.\n\nAll exceptions thrown by the enum classes implement ``Kuria\\Enum\\Exception\\ExceptionInterface``.\n\n- ``Kuria\\Enum\\Exception\\InvalidKeyException`` is thrown when a key doesn't exist\n- ``Kuria\\Enum\\Exception\\InvalidValueException`` is thrown when a value doesn't exist\n- ``Kuria\\Enum\\Exception\\InvalidMethodException`` is thrown when a magic factory method doesn't exist\n- ``Kuria\\Enum\\Exception\\DuplicateValueException`` is thrown when an enum class defines duplicate values\n\nValue type coercion\n===================\n\nValues are looked up and compared with the same type-coercion rules as PHP array\nkeys. See `PHP manual \u003chttp://php.net/manual/en/language.types.array.php\u003e`_ for\na detailed explanation.\n\nWith string, integer and null being the supported value types, this means that\nthe following values are equal:\n\n- ``null`` and ``\"\"`` (an empty string)\n- ``123`` and ``\"123\"`` (a numeric string)\n\n.. NOTE::\n\n   The public API, e.g. ``Enum::getValue()`` and ``EnumObject::value()``,\n   always returns the value as defined by the enum class.\n\n.. NOTE::\n\n   Array key type coercion is NOT the same as `loose comparison \u003chttp://php.net/manual/en/types.comparisons.php#types.comparisions-loose\u003e`_ (`==`).\n\n\nExamples\n--------\n\n.. code:: php\n\n   \u003c?php\n\n   use Kuria\\Enum\\EnumObject;\n\n   class IntAndNullEnum extends EnumObject\n   {\n       const INT_KEY = 123;\n       const NULL_KEY = null;\n   }\n\n   class StringEnum extends EnumObject\n   {\n       const NUMERIC_STRING_KEY = '123';\n       const EMPTY_STRING_KEY = '';\n   }\n\n   // value checks\n   var_dump(\n       IntAndNullEnum::hasValue('123'),\n       IntAndNullEnum::hasValue('0123'),\n       IntAndNullEnum::hasValue(''),\n       IntAndNullEnum::hasValue(' '),\n       StringEnum::hasValue(123),\n       StringEnum::hasValue('0123'),\n       StringEnum::hasValue(null),\n       StringEnum::hasValue(' ')\n   );\n\n   // value retrieval\n   var_dump(\n       (IntAndNullEnum::fromValue('123'))-\u003evalue(),\n       (IntAndNullEnum::fromValue(''))-\u003evalue(),\n       (StringEnum::fromValue(123))-\u003evalue(),\n       (StringEnum::fromValue(null))-\u003evalue()\n   );\n\nOutput for value checks:\n\n::\n\n  bool(true)    // '123' matches 123\n  bool(false)   // '0123' does not match 123\n  bool(true)    // '' matches NULL\n  bool(false)   // ' ' does not match NULL\n  bool(true)    // 123 matches '123'\n  bool(false)   // '0123' does not match '123'\n  bool(true)    // NULL matches ''\n  bool(false)   // ' ' does not match ''\n\nOutput for value retrieval:\n\n::\n\n  int(123)          // enum created with '123' but 123 is returned\n  NULL              // enum created with '' but NULL is returned\n  string(3) \"123\"   // enum created with 123 but '123' is returned\n  string(0) \"\"      // enum created with NULL but '' is returned\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuria%2Fenum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuria%2Fenum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuria%2Fenum/lists"}