https://github.com/kuria/enum
Emulated enumeration objects in PHP
https://github.com/kuria/enum
enum enumeration php
Last synced: about 1 year ago
JSON representation
Emulated enumeration objects in PHP
- Host: GitHub
- URL: https://github.com/kuria/enum
- Owner: kuria
- License: mit
- Created: 2017-07-01T00:07:42.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2023-04-22T14:38:49.000Z (about 3 years ago)
- Last Synced: 2025-03-06T06:04:39.232Z (over 1 year ago)
- Topics: enum, enumeration, php
- Language: PHP
- Homepage:
- Size: 30.3 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.rst
- License: LICENSE
Awesome Lists containing this project
README
Enum
####
Emulated enumeration objects in PHP.
The interface is similar to `SplEnum `_
but doesn't require any PHP extensions and provides more functionality.
.. image:: https://travis-ci.com/kuria/enum.svg?branch=master
:target: https://travis-ci.com/kuria/enum
.. contents::
Features
********
- immutability
- ensured unique keys and values
- simple to use (just extend a class and define some class constants)
- many methods related to keys
- values and their enumeration, maps and checking
- enum instances
- detailed exception messages
Requirements
************
- PHP 7.1+
Usage
*****
.. _Enum:
``Enum``
========
The static ``Enum`` class provides access to the defined key-value pairs.
Defining an enum class
----------------------
.. code:: php
'bar',
'BAZ' => 'qux',
'QUUX' => 'quuz',
];
}
}
Supported value types
---------------------
Only string, integer and null values are supported.
Values must be unique when used as an array key. See `Value type coercion`_.
Values are looked up and compared with the same type-coercion rules as
PHP array keys. See `Value type coercion`_.
Method overview
---------------
Checking keys and values
^^^^^^^^^^^^^^^^^^^^^^^^
Verify the existence of a key or a value:
.. code:: php
MONDAY
[1] => TUESDAY
[2] => WEDNESDAY
[3] => THURSDAY
[4] => FRIDAY
[5] => SATURDAY
[6] => SUNDAY
)
DayOfTheWeek::getValues(): Array
(
[0] => 0
[1] => 1
[2] => 2
[3] => 3
[4] => 4
[5] => 5
[6] => 6
)
DayOfTheWeek::getMap(): Array
(
[MONDAY] => 0
[TUESDAY] => 1
[WEDNESDAY] => 2
[THURSDAY] => 3
[FRIDAY] => 4
[SATURDAY] => 5
[SUNDAY] => 6
)
DayOfTheWeek::getKeyMap(): Array
(
[MONDAY] => 1
[TUESDAY] => 1
[WEDNESDAY] => 1
[THURSDAY] => 1
[FRIDAY] => 1
[SATURDAY] => 1
[SUNDAY] => 1
)
DayOfTheWeek::getValueMap(): Array
(
[0] => MONDAY
[1] => TUESDAY
[2] => WEDNESDAY
[3] => THURSDAY
[4] => FRIDAY
[5] => SATURDAY
[6] => SUNDAY
)
Getting pairs
^^^^^^^^^^^^^
A pair is an array with a single key and the corresponding value. They can be retrieved using either
the key or the value:
.. code:: php
int(0)
}
array(1) {
["FRIDAY"]=>
int(4)
}
Counting members
^^^^^^^^^^^^^^^^
.. code:: php
`_.
Creating instances
------------------
Instances can be created by one of the factory methods. Those instances are cached internally
and reused, so that multiple calls to the factory methods with the same key or value will yield
the same instance.
Enum instances cannot be cloned.
Using a value
^^^^^^^^^^^^^
.. code:: php
string(3) "RED"
["value"]=>
string(1) "r"
}
Using a key
^^^^^^^^^^^
.. code:: php
string(5) "GREEN"
["value"]=>
string(1) "g"
}
Using the magic static factory method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For every key there is a static method with the same name, which returns an instance
for that key-value pair.
.. code:: php
string(4) "BLUE"
["value"]=>
string(1) "b"
}
.. WARNING::
Magic static factory method names are case-sensitive.
Getting all instances
^^^^^^^^^^^^^^^^^^^^^
.. code:: php
object(Foo\Color)#5 (2) {
["key"]=>
string(3) "RED"
["value"]=>
string(1) "r"
}
["GREEN"]=>
object(Foo\Color)#4 (2) {
["key"]=>
string(5) "GREEN"
["value"]=>
string(1) "g"
}
["BLUE"]=>
object(Foo\Color)#2 (2) {
["key"]=>
string(4) "BLUE"
["value"]=>
string(1) "b"
}
}
Method overview
---------------
Getting the key and value
^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: php
key(),
$color->value()
);
Output:
::
string(3) "RED"
string(1) "r"
Getting the pair
^^^^^^^^^^^^^^^^
.. code:: php
pair());
Output:
::
array(1) {
["GREEN"]=>
string(1) "g"
}
Comparing the key and value
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: php
is('RED'), // compare key
$color->is('GREEN'), // compare key
$color->equals('r'), // compare value
$color->equals('g') // compare value
);
Output:
::
bool(true)
bool(false)
bool(true)
bool(false)
String conversion
^^^^^^^^^^^^^^^^^
Converting an instance to a string will yield its value (cast to a string):
.. code:: php
`_ for
a detailed explanation.
With string, integer and null being the supported value types, this means that
the following values are equal:
- ``null`` and ``""`` (an empty string)
- ``123`` and ``"123"`` (a numeric string)
.. NOTE::
The public API, e.g. ``Enum::getValue()`` and ``EnumObject::value()``,
always returns the value as defined by the enum class.
.. NOTE::
Array key type coercion is NOT the same as `loose comparison `_ (`==`).
Examples
--------
.. code:: php
value(),
(IntAndNullEnum::fromValue(''))->value(),
(StringEnum::fromValue(123))->value(),
(StringEnum::fromValue(null))->value()
);
Output for value checks:
::
bool(true) // '123' matches 123
bool(false) // '0123' does not match 123
bool(true) // '' matches NULL
bool(false) // ' ' does not match NULL
bool(true) // 123 matches '123'
bool(false) // '0123' does not match '123'
bool(true) // NULL matches ''
bool(false) // ' ' does not match ''
Output for value retrieval:
::
int(123) // enum created with '123' but 123 is returned
NULL // enum created with '' but NULL is returned
string(3) "123" // enum created with 123 but '123' is returned
string(0) "" // enum created with NULL but '' is returned