|
| 1 | +# Enumerated type for PHP |
| 2 | + |
| 3 | +* [What is Enum?](#what-is-enum) |
| 4 | +* [Why use Enums instead of Constants?](#why-use-enums-instead-of-constants) |
| 5 | +* [Usage of php-enum](#usage-of-php-enum) |
| 6 | + * [Enum declaration](#enum-declaration) |
| 7 | + * [Enum usage](#enum-usage) |
| 8 | + * [Tips & Tricks](#tips--tricks) |
| 9 | +* [How to install](#how-to-install) |
| 10 | + |
| 11 | + |
| 12 | +## What is Enum? |
| 13 | + |
| 14 | +> In computer programming, an **enumerated type** (also called **enumeration** or **enum**, or **factor** in the R programming language, and a **categorical variable** in statistics) is a data type consisting of a set of named values called **elements**, **members**, **enumeral**, or **enumerators** of the type. The enumerator names are usually identifiers that behave as constants in the language. A variable that has been declared as having an enumerated type can be assigned any of the enumerators as a value. In other words, an *enumerated type has values that are different from each other*, and that can be compared and assigned, but which are not specified by the programmer as having any particular concrete representation in the computer's memory; compilers and interpreters can represent them arbitrarily. |
| 15 | +-- [Enumerated type - Wikipedia, The Free Encyclopedia] |
| 16 | + |
| 17 | + |
| 18 | +## Why use Enums instead of Constants? |
| 19 | + |
| 20 | +Because **it is safer and less scary** than using constants. Don't trust me? Let see at this code: |
| 21 | + |
| 22 | +```php |
| 23 | +<?php |
| 24 | + |
| 25 | +class MyBoolean |
| 26 | +{ |
| 27 | + const MY_TRUE = 1; |
| 28 | + const MY_FALSE = 2; |
| 29 | +} |
| 30 | + |
| 31 | +function isTrue($myBoolean) |
| 32 | +{ |
| 33 | + switch($myBoolean) { |
| 34 | + case MyBoolean::MY_TRUE: |
| 35 | + return true; |
| 36 | + case MyBoolean::MY_FALSE: |
| 37 | + return false; |
| 38 | + } |
| 39 | +} |
| 40 | + |
| 41 | +isTrue(MyBoolean::MY_TRUE); // returns true - OK |
| 42 | +isTrue(MyBoolean::MY_FALSE); // returns false - OK |
| 43 | +isTrue(1); // returns true - OK |
| 44 | +isTrue(2); // returns false - scary, but OK |
| 45 | +isTrue(true); // returns true - OK |
| 46 | +isTrue(false); // returns null - WTF? |
| 47 | +``` |
| 48 | + |
| 49 | +And now the **same code with Enum** instead of Constants: |
| 50 | + |
| 51 | +```php |
| 52 | +<?php |
| 53 | + |
| 54 | +class MyBoolean extends \PetrKnap\Php\Enum\Enum |
| 55 | +{ |
| 56 | + protected function members() |
| 57 | + { |
| 58 | + return [ |
| 59 | + "MY_TRUE" => 1, |
| 60 | + "MY_FALSE" => 2 |
| 61 | + ]; |
| 62 | + } |
| 63 | +} |
| 64 | + |
| 65 | +function isTrue(MyBoolean $myBoolean) |
| 66 | +{ |
| 67 | + switch($myBoolean) { |
| 68 | + case MyBoolean::MY_TRUE(): |
| 69 | + return true; |
| 70 | + case MyBoolean::MY_FALSE(): |
| 71 | + return false; |
| 72 | + } |
| 73 | +} |
| 74 | + |
| 75 | +isTrue(MyBoolean::MY_TRUE()); // returns true - OK |
| 76 | +isTrue(MyBoolean::MY_FALSE()); // returns false - OK |
| 77 | +isTrue(1); // uncaught type error - OK |
| 78 | +isTrue(2); // uncaught type error - OK |
| 79 | +isTrue(true); // uncaught type error - OK |
| 80 | +isTrue(false); // uncaught type error - OK |
| 81 | +``` |
| 82 | + |
| 83 | + |
| 84 | +## Usage of php-enum |
| 85 | + |
| 86 | +### Enum declaration |
| 87 | +```php |
| 88 | +<?php |
| 89 | + |
| 90 | +class DayOfWeek extends \PetrKnap\Php\Enum\Enum |
| 91 | +{ |
| 92 | + protected function members() |
| 93 | + { |
| 94 | + return [ |
| 95 | + "SUNDAY" => 0, |
| 96 | + "MONDAY" => 1, |
| 97 | + "TUESDAY" => 2, |
| 98 | + "WEDNESDAY" => 3, |
| 99 | + "THURSDAY" => 4, |
| 100 | + "FRIDAY" => 5, |
| 101 | + "SATURDAY" => 6 |
| 102 | + ]; |
| 103 | + } |
| 104 | +} |
| 105 | +``` |
| 106 | + |
| 107 | +### Enum usage |
| 108 | +```php |
| 109 | +<?php |
| 110 | + |
| 111 | +if (DayOfWeek::FRIDAY() == DayOfWeek::FRIDAY()) { |
| 112 | + echo "This is OK."; |
| 113 | +} |
| 114 | + |
| 115 | +if (DayOfWeek::FRIDAY() == DayOfWeek::MONDAY()) { |
| 116 | + echo "We are going to Hell!"; |
| 117 | +} |
| 118 | + |
| 119 | +function isWeekend(DayOfWeek $dayOfWeek) |
| 120 | +{ |
| 121 | + switch ($dayOfWeek) { |
| 122 | + case DayOfWeek::SATURDAY(): |
| 123 | + case DayOfWeek::SUNDAY(): |
| 124 | + return true; |
| 125 | + default: |
| 126 | + return false; |
| 127 | + } |
| 128 | +} |
| 129 | + |
| 130 | +if (date('w') == DayOfWeek::FRIDAY()->getValue()) { |
| 131 | + echo "Finally it is Friday!"; |
| 132 | +} |
| 133 | +// or |
| 134 | +if (DayOfWeek::getEnumByValue(date('w')) == DayOfWeek::FRIDAY()) { |
| 135 | + echo "Finally it is Friday!"; |
| 136 | +} |
| 137 | +``` |
| 138 | + |
| 139 | +### Tips & Tricks |
| 140 | + |
| 141 | +Enum is capable to carry any data type as values, including another enum instance. |
| 142 | + |
| 143 | +```php |
| 144 | +<?php |
| 145 | + |
| 146 | +class MixedValues extends \PetrKnap\Php\Enum\Enum |
| 147 | +{ |
| 148 | + protected function members() |
| 149 | + { |
| 150 | + return [ |
| 151 | + "null" => null, |
| 152 | + "boolean" => true, |
| 153 | + "integer" => 1, |
| 154 | + "float" => 1.0, |
| 155 | + "string" => "s", |
| 156 | + "array" => [], |
| 157 | + "object" => new \stdClass(), |
| 158 | + "callable" => function() {} |
| 159 | + ]; |
| 160 | + } |
| 161 | +} |
| 162 | +``` |
| 163 | + |
| 164 | +You can simply convert value to Enum instance and vice versa. |
| 165 | + |
| 166 | +```php |
| 167 | +<?php |
| 168 | + |
| 169 | +/** |
| 170 | + * @ORM\Entity |
| 171 | + */ |
| 172 | +class MyEntity |
| 173 | +{ |
| 174 | + /** |
| 175 | + * @ORM\Column(type="integer") |
| 176 | + * @var int |
| 177 | + */ |
| 178 | + private $dayOfWeek; |
| 179 | + |
| 180 | + /** |
| 181 | + * @return DayOfWeek |
| 182 | + */ |
| 183 | + public function getDayOfWeek() |
| 184 | + { |
| 185 | + return DayOfWeek::getEnumByValue($this->dayOfWeek); |
| 186 | + } |
| 187 | + |
| 188 | + /** |
| 189 | + * @param DayOfWeek $dayOfWeek |
| 190 | + */ |
| 191 | + public function setDayOfWeek(DayOfWeek $dayOfWeek) |
| 192 | + { |
| 193 | + $this->dayOfWeek = $dayOfWeek->getValue(); |
| 194 | + } |
| 195 | +} |
| 196 | +``` |
| 197 | + |
| 198 | + |
| 199 | +## How to install |
| 200 | + |
| 201 | +Run `composer require petrknap/php-enum` or merge this JSON code with your project `composer.json` file manually and run `composer install`. Instead of `dev-master` you can use [one of released versions]. |
| 202 | + |
| 203 | +```json |
| 204 | +{ |
| 205 | + "require": { |
| 206 | + "petrknap/php-enum": "dev-master" |
| 207 | + } |
| 208 | +} |
| 209 | +``` |
| 210 | + |
| 211 | +Or manually clone this repository via `git clone https://github.com/petrknap/php-enum.git` or download [this repository as ZIP] and extract files into your project. |
| 212 | + |
| 213 | + |
| 214 | + |
| 215 | +[one of released versions]:https://github.com/petrknap/php-enum/releases |
| 216 | +[this repository as ZIP]:https://github.com/petrknap/php-enum/archive/master.zip |
| 217 | + |
| 218 | + |
| 219 | + |
| 220 | + |
| 221 | +[Enumerated type - Wikipedia, The Free Encyclopedia]:https://en.wikipedia.org/w/index.php?title=Enumerated_type&oldid=701057934 |
0 commit comments