Download the PHP package cerbero/enum without Composer

🎲 Enum

Zero-dependencies package to supercharge enum functionalities.

[!TIP] Need to supercharge enums in a Laravel application?

Consider using 🎲 Laravel Enum instead.

📦 Install

Via Composer:

🔮 Usage

• ⚖️ Comparison
• 🏷️ Meta
• 🚰 Hydration
• 🎲 Enum operations
• 🧺 Cases collection
• 🪄 Magic
• 🤳 Self-awareness
• 🦾 Console commands
  • 🗒️ annotate
  • 🏗️ make
  • 💙 ts

To supercharge our enums with all the features provided by this package, we can let our enums use the Enumerates trait:

⚖️ Comparison

We can check whether an enum includes some names or values. Pure enums check for names and backed enums check for values:

Otherwise we can check whether cases match a given name or value:

Comparisons can also be performed against arrays:

🏷️ Meta

Meta add extra information to a case. Meta can be added by implementing a public non-static method and/or by attaching #[Meta] attributes to cases:

The above enum defines 3 meta for each case: color, shape and isOdd. The #[Meta] attributes are ideal to declare static information, whilst public non-static methods are ideal to declare dynamic information.

To access a case meta, we can simply call the method having the same name of the wanted meta:

[!TIP] Our IDE can autocomplete meta methods thanks to the annotate command.

#[Meta] attributes can also be attached to the enum itself to provide default values when a case does not declare its own meta values:

In the above example all cases have a red color and a triangle shape, except the case Two that overrides the default meta values.

Meta can also be leveraged for the collection of cases.

🚰 Hydration

An enum case can be instantiated from its own name, value (if backed) or meta:

Hydrating from meta can return multiple cases. To facilitate further processing, such cases are collected into a CasesCollection.

🎲 Enum operations

A number of operations can be performed against an enum to affect all its cases:

🧺 Cases collection

When an enum operation can return multiple cases, they are collected into a CasesCollection which provides a fluent API to perform further operations on the set of cases:

Cases can be collected by calling collect() or any other enum operation returning a CasesCollection:

We can iterate a cases collection within any loop:

All the enum operations listed above are also available when dealing with a collection of cases.

🪄 Magic

Enums can implement magic methods to be invoked or to handle calls to inaccessible methods. By default when calling an inaccessible static method, the name or value of the case matching the missing method is returned:

[!TIP] Our IDE can autocomplete cases static methods thanks to the annotate command.

We can also obtain the name or value of a case by simply invoking it:

When calling an inaccessible method of a case, by default the value of the meta matching the missing method is returned:

[!TIP] Our IDE can autocomplete meta methods thanks to the annotate command.

Depending on our needs, we can customize the default behavior of all enums in our application when invoking a case or calling inaccessible methods:

🤳 Self-awareness

Some internal methods are also available and can be useful for inspecting enums or auto-generating code:

🦾 Console commands

This package provides a handy binary, built to automate different tasks. To learn how to use it, we can simply run it:

For the console commands to work properly, the application base path is automatically guessed. However, in case of issues, we can manually set it by creating an enums.php file in the root of our app:

Some commands support the option --all to reference all the enums of our application. We can set the paths where enums live in our app in the enums.php configuration file as well:

In the above example, enums are discovered in the app/Enums directory and in all Enums sub-folders belonging to domain, e.g. domain/Posts/Enums, domain/Users/Enums, etc.

🗒️ annotate

The annotate command automatically adds method annotations to enums, making IDEs autocompletion possible:

We can provide more than one enum to annotate, if needed:

Otherwise we can annotate all our enums at once by enabling the option --all:

If we want to overwrite method annotations already annotated on enums, we can add the option --force:

🏗️ make

The make command creates a new - automatically annotated - enum with the cases that we provide:

If we need to create backed enums, we can specify a custom value for each case:

Otherwise we can automatically assign values to cases by setting the --backed option:

The option --backed supports the following values:

• int0: assign an incremental integer starting from 0 (0, 1, 2...)
• int1: assign an incremental integer starting from 1 (1, 2, 3...)
• bitwise: assign an incremental bitwise value (1, 2, 4...)
• snake: assign the case name in snake case (case_one, case_two...)
• kebab: assign the case name in kebab case (case-one, case-two...)
• camel: assign the case name in camel case (caseOne, caseTwo...)
• lower: assign the case name in lower case (caseone, casetwo...)
• upper: assign the case name in upper case (CASEONE, CASETWO...)

If we want to overwrite an existing enum, we can add the option --force:

We can generate the TypeScript counterpart of the newly created enum by adding the --typescript option:

💙 ts

The ts command turns enums into their TypeScript counterpart, synchronizing backend with frontend:

We can provide more than one enum to synchronize in TypeScript, if needed:

Otherwise we can synchronize all our enums at once by enabling the option --all:

By default enums are synchronized in resources/js/enums/index.ts, however we can customize it in our enums.php configuration file:

As seen above, we can either set a static path for our TypeScript enums or dynamically set the TypeScript path of an enum depending on its namespace.

If we want to update previously synchronized enums, we can add the option --force:

📆 Change log

Please see CHANGELOG for more information on what has changed recently.

🧪 Testing

💞 Contributing

Please see CODE_OF_CONDUCT for details.

🧯 Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

🏅 Credits

• Andrea Marco Sartori
• All Contributors

⚖️ License

The MIT License (MIT). Please see License File for more information.