add enum docs (#379)

* add enum docs

* add more examples in docs

* Apply suggestions from code review

Co-authored-by: Cristian Tăbăcitu <[email protected]>

Author: pxpm

5.x/crud-columns.md

@@ -245,6 +245,63 @@ The email column will output the email address in the database (truncated to 254
 
 <hr>
 
+<a name="enum"></a>
+### enum
+
+The enum column will output the value of your database ENUM column or your PHP enum attribute.
+```php
+[
+   'name'  => 'status', 
+   'label' => 'Status', 
+   'type'  => 'enum',
+],
+```
+
+By default, in case it's a `BackedEnum` it will show the `value` of the enum (when casted), in `database` or `UnitEnum` it will show the the enum value without parsing the value. 
+
+If you want to output something different than what your enum stores you have two options:
+- For `database enums` you need to provide the `options` that translates the enums you store in database.
+- For PHP enums you can provide the same `options` or provide a `enum_function` from the enum to gather the final result.
+
+```php
+// for database enums
+[
+   'name'  => 'status', 
+   'label' => 'Status', 
+   'type'  => 'enum',
+   'options' => [
+       'DRAFT' => 'Is draft',
+       'PUBLISHED' => 'Is published'
+   ]
+],
+
+// for PHP enums, given the following enum example
+
+enum StatusEnum
+{
+    case DRAFT;
+    case PUBLISHED;
+
+    public function readableText(): string
+    {
+        return match ($this) {
+            StatusEnum::DRAFT => 'Is draft',
+            StatusEnum::PUBLISHED => 'Is published',
+        };
+    }
+}
+
+[
+   'name'  => 'status', 
+   'label' => 'Status', 
+   'type'  => 'enum',
+   'enum_function' => 'readableText',
+   'enum_class' => 'App\Enums\StatusEnum'
+],
+```
+
+<hr>
+
 <a name="image"></a>
 ### image
 

5.x/crud-fields.md

@@ -448,17 +448,56 @@ Input preview:
 <a name="enum"></a>
 ### enum
 
-Show a select with the values in the database for that ENUM field. Requires that the db column type is "enum". If the db column allows null, the " - " value will also show up in the select.
+Show a select with the values for an ENUM database column, or an PHP enum (introduced in PHP 8.1).
+
+##### Database ENUM
+When used with a database enum it requires that the database column type is `enum`. In case it's nullable it will also show `-` (empty) option.
+
+PLEASE NOTE the `enum` field using database enums only works for MySQL.
+
+```php
+[
+    'name'  => 'status',
+    'label' => 'Status',
+    'type'  => 'enum',
+    // optional, specify the enum options with custom display values
+    'options' => [
+        'DRAFT' => 'Is Draft',
+        'PUBLISHED' => 'Is Published'
+    ]
+],
+```
+
+##### PHP enum
+
+If you are using a `BackedEnum` your best option is to cast it in your model, and Backpack know how to handle it without aditional configuration. 
 
 ```php
-[   // Enum
+// in your model (eg. Article)
+
+protected $casts = ['status' => \App\Enums\StatusEnum::class]; //assumes you have this enum created
+
+// and in your controller
+[
     'name'  => 'status',
     'label' => 'Status',
     'type'  => 'enum'
+    // optional
+    //'enum_class' => 'App\Enums\StatusEnum',
+    //'enum_function' => 'readableStatus',
 ],
 ```
 
-PLEASE NOTE the enum field only works for MySQL databases.
+In case it's not a `BackedEnum` or you don't want to cast it in your Model, you should provide the enum class to the field:
+
+```php
+[
+    'name'  => 'status',
+    'label' => 'Status',
+    'type'  => 'enum',
+    'enum_class' => \App\Enums\StatusEnum::class
+],
+```
 
 Input preview: