iteks/laravel-enum

A comprehensive Laravel package providing enhanced enum functionalities, including attribute handling, select array conversions, and fluent facade interactions for robust enum management in Laravel applications.

v1.0.3 2024-04-17 11:36 UTC

Requires

• php: ^8.1
• laravel/framework: ^9.46|^10.10|^11.0

Requires (Dev)

• laravel/pint: ^1.14
• pestphp/pest: ^2.34
• pestphp/pest-plugin-arch: ^2.7
• phpstan/phpstan: ^1.10
• symfony/var-dumper: ^6.4

MIT

• Jeramy Hing

• php
• serialize
• data
• array
• attribute
• enum
• trait
• string
• helper
• laravel
• collection

README

The Laravel Enum package enriches Laravel's enum support, integrating advanced features like attribute handling, select array transformation, and facade access for streamlined enum operations. Designed for Laravel applications, it offers a suite of utilities for both backed enums and attribute-enhanced enums, including descriptive annotations, ID management, label generation, and metadata association. This package streamlines working with enums in Laravel by providing intuitive, fluent interfaces for common tasks, enhancing enum usability in forms, API responses, and more. Whether you're defining select options, querying enum attributes, or integrating enums tightly with Laravel features, Laravel Enum simplifies these processes, making enum management in Laravel applications both powerful and efficient. Offered by iteks, Developed by jeramyhing.

Get Started

Requires PHP 8.1+

Install Laravel Enum via the Composer package manager:

composer require iteks/laravel-enum

Usage

• EnumExample class
• Enum Helpers (BackedEnum)
  • Enum::asSelectArray()
  • Enum::toLabel()
  • Enum::toLabels()
• Enum Helpers (HasAttributes)
  • Enum::attributes()
  • Enum::description()
  • Enum::descriptions()
  • Enum::id()
  • Enum::ids()
  • Enum::label()
  • Enum::labels()
  • Enum::metadata()
  • Enum::metadatum()
• Enum Traits (BackedEnum)
  • asSelectArray()
  • fromName()
  • name()
  • names()
  • toLabel()
  • toLabels()
  • tryFromName()
  • value()
  • values()
• Enum Traits (HasAttributes)
  • attributes()
  • description()
  • descriptions()
  • id()
  • ids()
  • label()
  • labels()
  • metadata()
  • metadatum()
• String Helper Macros
  • Str::splitConstantCase()
  • Str::splitEnumCase()

EnumExample class

The Laravel Enum methods are designed for PHP 8 Backed Enumeration classes.

Laravel Enum helper and trait methods extend an existing backed enum class for more versatile enum handling. Additionally, Laravel Enum offers a fluent way to add and manage PHP 8 Attributes on backed enum cases. This package comes with four available attributes to readily assign to your enum cases: Description, Id, Label, and Metadata. The ExampleEnum class below demonstrates how you can apply these attributes to you enums. You may pick and choose which attributes you wish to take advantage of.

use Iteks\Attributes\Description;
use Iteks\Attributes\Id;
use Iteks\Attributes\Label;
use Iteks\Attributes\Metadata;
use Iteks\Traits\BackedEnum;
use Iteks\Traits\HasAttributes;

enum ExampleEnum: int
{
    use BackedEnum;
    use HasAttributes;

    #[Description('Lorem ipsum dolor sit amet, consectetur adipiscing elit.')]
    #[Id(0)]
    #[Label('First-Example')]
    #[Metadata(['key' => 'value'])]
    case FirstExample = 1;

    #[Description('Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.')]
    #[Id(1)]
    #[Label('SecondExample (Example)')]
    #[Metadata('{"key": "value"}')]
    case SecondExample = 2;

    #[Description('Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.')]
    #[Id(2)]
    #[Label('3rd Eg.')]
    #[Metadata([])]
    case ThirdExample = 3;
}

top

Enum Helpers (BackedEnum)

First, import the helper class:

use Iteks\Support\Facades\Enum;

Note: This group of helpers does NOT require any trait to be applied to the target enum class. You may immediately use the the following methods:

top

Enum::asSelectArray()

Get a backed enum class as an array to populate a select element. The array will consist of a text key column containing values of the case name in display format, and a value keys column containing values using the original simpler values.

Note: This method will first check for Label and Id attributes applied to the target enum class. If they are present, the method will prioritize those values. If not present, the method will return a mutated Headline value from the case name.

Enum::asSelectArray(ExampleEnum::class);

array:3 [▼ 
  0 => array:2 [▼
    "text" => "First-Example"
    "value" => 1
  ]
  1 => array:2 [▼
    "text" => "SecondExample (Example)"
    "value" => 2
  ]
  2 => array:2 [▼
    "text" => "3rd Eg."
    "value" => 3
  ]
]

top

Enum::toLabel()

Create a label from the case name.

Enum::toLabel(ExampleEnum::FirstExample);

"First Example"

top

Enum::toLabels()

Create and compile an array of labels from the case names.

Enum::toLabels(ExampleEnum::class);

array:3 [▼
  0 => "First Example"
  1 => "Second Example"
  2 => "Third Example"
]

top

Enum Helpers (HasAttributes)

First, ensure that the target enum class has the HasAttributes trait applied, as shown in the ExampleEnum class above.

Then, import the helper class:

use Iteks\Support\Facades\Enum;

You may then use the following methods:

top

Enum::attributes()

Retrieve all of the attributes for all cases.

Enum::attributes(ExampleEnum::FirstExample);

array:5 [▼
  "simpleValue" => 1
  "description" => "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
  "id" => 0
  "label" => "First-Example"
  "metadata" => array:1 [▼
    "key" => "value"
  ]
]

Enum::attributes(ExampleEnum::FirstExample, ['id', 'label']);

array:2 [▼
  "id" => 0
  "label" => "First-Example"
]

Enum::attributes(ExampleEnum::class);

array:3 [▼
  "FirstExample" => array:5 [▼
    "simpleValue" => 1
    "description" => "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    "id" => 0
    "label" => "First-Example"
    "metadata" => array:1 [▼
      "key" => "value"
    ]
  ]
  "SecondExample" => array:5 [▼
    "simpleValue" => 2
    "description" => "Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
    "id" => 1
    "label" => "SecondExample (Example)"
    "metadata" => "{"key": "value"}"
  ]
  "ThirdExample" => array:5 [▼
    "simpleValue" => 3
    "description" => "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
    "id" => 2
    "label" => "3rd Eg."
    "metadata" => []
  ]
]

Enum::attributes(ExampleEnum::class, ['description', 'metadata']);

array:3 [▼
  "FirstExample" => array:2 [▼
    "description" => "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    "metadata" => array:1 [▼
      "key" => "value"
    ]
  ]
  "SecondExample" => array:2 [▼
    "description" => "Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
    "metadata" => "{"key": "value"}"
  ]
  "ThirdExample" => array:2 [▼
    "description" => "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
    "metadata" => []
  ]
]

top

Enum::description()

Retrieve the description attribute.

Enum::description(ExampleEnum::FirstExample);

"Lorem ipsum dolor sit amet, consectetur adipiscing elit."

top

Enum::descriptions()

Retrieve the description attribute for all cases.

Enum::descriptions(ExampleEnum::class);

array:3 [▼
  0 => "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
  1 => "Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
  2 => "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
]

top

Enum::id()

Retrieve the id attribute.

Enum::id(ExampleEnum::FirstExample);

0

top

Enum::ids()

Retrieve the id attribute for all cases.

Enum::ids(ExampleEnum::class);

array:3 [▼
  0 => 0
  1 => 1
  2 => 2
]

top

Enum::label()

Retrieve the label attribute.

Enum::label(ExampleEnum::FirstExample);

"First-Example"

top

Enum::labels()

Retrieve the label attribute for all cases.

Enum::labels(ExampleEnum::class);

array:3 [▼
  0 => "First-Example"
  1 => "SecondExample (Example)"
  2 => "3rd Eg."
]

top

Enum::metadata()

Retrieve the metadata attribute.

Enum::metadata(ExampleEnum::FirstExample);

array:1 [▼
  "key" => "value"
]

top

Enum::metadatum()

Retrieve the metadata attribute for all cases.

Enum::metadatum(ExampleEnum::class);

array:3 [▼
  0 => array:1 [▼
    "key" => "value"
  ]
  1 => "{"key": "value"}"
  2 => []
]

top

Enum Traits (BackedEnum)

First, ensure that the target enum class has the BackedEnum trait applied, as shown in the ExampleEnum class above.

Then, you may then use the following methods:

top

asSelectArray()

Get a backed enum class as an array to populate a select element. The array will consist of a text key column containing values of the case name in display format, and a value keys column containing values using the original simpler values.

Note: This method will first check for Label and Id attributes applied to the target enum class. If they are present, the method will prioritize those values. If not present, the method will return a mutated Headline value from the case name.

ExampleEnum::asSelectArray();

array:3 [▼
  0 => array:2 [▼
    "text" => "First-Example"
    "value" => 0
  ]
  1 => array:2 [▼
    "text" => "SecondExample (Example)"
    "value" => 1
  ]
  2 => array:2 [▼
    "text" => "3rd Eg."
    "value" => 2
  ]
]

top

fromName()

Maps a scalar to an enum instance.

ExampleEnum::fromName('FirstExample');

App\Enums\ExampleEnum {#297 ▼
  +name: "FirstExample"
  +value: 1
}

top

name()

Retrieve the case name for the given simpler value.

ExampleEnum::name(1);

"FirstExample"

top

names()

Retrieve an array containing all of the case names.

ExampleEnum::names();

array:3 [▼
  0 => "FirstExample"
  1 => "SecondExample"
  2 => "ThirdExample"
]

top

toLabel()

Create a label from the case name.

ExampleEnum::toLabel(1);

"First Example"

top

toLabels()

Create and compile an array of labels from the case names.

ExampleEnum::toLabels();

array:3 [▼
  0 => "First Example"
  1 => "Second Example"
  2 => "Third Example"
]

top

tryFromName()

Maps a scalar to an enum instance or null.

ExampleEnum::tryFromName('FirstExample');

App\Enums\ExampleEnum {#297 ▼
  +name: "FirstExample"
  +value: 1
}

top

value()

Retrieve the simpler value for the given case name.

ExampleEnum::value('FirstExample');

1

top

values()

Retrieve an array containing all of the simpler values.

ExampleEnum::values();

array:3 [▼
  0 => 1
  1 => 2
  2 => 3
]

top

Enum Traits (HasAttributes)

First, ensure that the target enum class has the HasAttributes trait applied, as shown in the ExampleEnum class above.

Then, you may then use the following methods:

top

attributes()

Retrieve all of the attributes for all cases.

ExampleEnum::attributes('FirstExample');

array:5 [▼
  "simpleValue" => 1
  "description" => "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
  "id" => 0
  "label" => "First-Example"
  "metadata" => array:1 [▼
    "key" => "value"
  ]
]

ExampleEnum::attributes('FirstExample', ['id', 'label']);

array:2 [▼
  "id" => 0
  "label" => "First-Example"
]

ExampleEnum::attributes();

array:3 [▼
  "FirstExample" => array:5 [▼
    "simpleValue" => 1
    "description" => "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    "id" => 0
    "label" => "First-Example"
    "metadata" => array:1 [▼
      "key" => "value"
    ]
  ]
  "SecondExample" => array:5 [▼
    "simpleValue" => 2
    "description" => "Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
    "id" => 1
    "label" => "SecondExample (Example)"
    "metadata" => "{"key": "value"}"
  ]
  "ThirdExample" => array:5 [▼
    "simpleValue" => 3
    "description" => "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
    "id" => 2
    "label" => "3rd Eg."
    "metadata" => []
  ]
]

ExampleEnum::attributes(null, ['description', 'metadata']);

array:3 [▼
  "FirstExample" => array:2 [▼
    "description" => "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    "metadata" => array:1 [▼
      "key" => "value"
    ]
  ]
  "SecondExample" => array:2 [▼
    "description" => "Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
    "metadata" => "{"key": "value"}"
  ]
  "ThirdExample" => array:2 [▼
    "description" => "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
    "metadata" => []
  ]
]

top

description()

Retrieve the description attribute.

ExampleEnum::description('FirstExample');

"Lorem ipsum dolor sit amet, consectetur adipiscing elit."

top

descriptions()

Retrieve the description attribute for all cases.

ExampleEnum::descriptions();

array:3 [▼
  0 => "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
  1 => "Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
  2 => "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
]

top

id()

Retrieve the id attribute.

ExampleEnum::id('FirstExample');

0

top

ids()

Retrieve the id attribute for all cases.

ExampleEnum::ids();

array:3 [▼
  0 => 0
  1 => 1
  2 => 2
]

top

label()

Retrieve the label attribute.

ExampleEnum::label('FirstExample');

"First-Example"

top

labels()

Retrieve the label attribute for all cases.

ExampleEnum::labels();

array:3 [▼
  0 => "First-Example"
  1 => "SecondExample (Example)"
  2 => "3rd Eg."
]

top

metadata()

Retrieve the metadata attribute.

ExampleEnum::metadata('FirstExample');

array:1 [▼
  "key" => "value"
]

top

metadatum()

Retrieve the metadata attribute for all cases.

ExampleEnum::metadatum();

array:3 [▼
  0 => array:1 [▼
    "key" => "value"
  ]
  1 => "{"key": "value"}"
  2 => []
]

top

String Helper Macros

These helperas are booted when installing the package and are immediately available for use.

top

Str::splitConstantCase()

Splits a "CONSTANT_CASE" string into words separated by whitespace.

Str::splitConstantCase('FIRST_EXAMPLE');

"FIRST EXAMPLE"

top

Str::splitEnumCase()

Splits a "EnumCase" string into words separated by whitespace.

Str::splitEnumCase('FirstExample');

"First Example"

top