Docs.

docs/Entity/Enum.md

@@ -1,7 +1,33 @@
-# EnumTrait
+# Static Enums
 
 Enum support via trait and `enum()` method.
 
+## Intro
+
+There are many cases where an additional model + table + relation would be total overhead. Like those little "status", "level", "type", "color", "category" attributes.
+Often those attributes are implemented as "enums" in SQL - but cake doesn't support them natively. And it should not IMO. You might also want to read [this](http://komlenic.com/244/8-reasons-why-mysqls-enum-data-type-is-evil/) ;)
+
+If there are only a few values to choose from and if they don't change very often, you might want to consider the following approach.
+It is very efficient and easily expandable on code level.
+
+Further advantages
+- can be used from anywhere (model, controller, view, behavior, component, ...)
+- reorder them dynamically per form by just changing the order of the array keys when you call the method.
+- auto-translated right away (i18n without any translation tables - very fast)
+- create multiple static functions for different views ("optionsForAdmins", "optionsForUsers" etc). the overhead is minimal.
+
+
+## Setup
+
+Add tinyint(2) unsigned field called for example "status" (singular).
+"tinyint(2) unsigned" covers 0...127 / 0...255 - which should always be enough for enums. 
+if you need more, you SHOULD make an extra relation as real table. 
+
+Do not use tinyint(1) as CakePHP interprets this as a (boolean) toggle field, which we don't want!
+
+
+## Usage
+
 Add the trait to your entity:
 ```php
 use Tools\Model\Entity\EnumTrait;
@@ -56,6 +82,25 @@ echo $entity->status !== null ? $entity::statuses($entity->status) : $default;
 echo $entity::statuses($entity->getStatusOrFail());
 ```
 
+You can also use it anywhere else for filtering, or comparison:
+```php
+use App\Model\Entity\Notification;
+
+$unreadNotifications = $this->Notifications->find()
+    ->where(['user_id' => $uid, 'status' => Notification::STATUS_UNREAD)])
+    ->all();
+```
+
+### Subset or custom order
+You can reorder the choices per form by passing a list of keys in the order you want.
+With this, you can also filter the options you want to allow:
+```php
+<?= $this->Form->control('status', [
+    'options' => $entity::statuses([$entity::STATUS_FAILURE, $entity::STATUS_SUCCESS]),
+]) ?>
+```
+
+
 
 ## Bake template support
 
@@ -67,3 +112,7 @@ The above form controls would be auto-added by this.
 ## Background
 
 See [Static Enums](http://www.dereuromark.de/2010/06/24/static-enums-or-semihardcoded-attributes/).
+
+## Bitmasks
+
+If you are looking for combining several booleans into a single database field check out my [Bitmasked Behavior](http://www.dereuromark.de/2012/02/26/bitmasked-using-bitmasks-in-cakephp/).