Download the PHP package bakame/aide-enums without Composer

Aide for Enums

A collection of traits and classes to improve handling PHP's Enum.

[!CAUTION]
Sub-split of Aide for Enum helpers.
⚠️ this is a sub-split, for pull requests and issues, visit: https://github.com/bakame-php/aide

Installation

Composer

composer require bakame-php/aide-enums

System Requirements

You need:

• PHP >= 8.1 but the latest stable version of PHP is recommended

Usage

Traits

Factory

Enable creating Pure or Backed Enum based on their name. The trait adds two (2) new static methods, tryFromName and fromName and re-introduce the tryFrom and from method on pure Enums. Once added to your Enum you can do the following:

You need the Bakame\Aide\Enum\Factory trait to expose the new API.

Info

Gather information regarding the current Enum via public static methods. This trait enables getting:

• the number of cases via the size method;
• the type of enum via the isBacked and isPure method;
• the names of each cases with the names method;
• the possible values for the Enum with the values method;
• the nameOf which returns the name associated with a specific value

You need the Bakame\Aide\Enum\Info trait to expose the new API.

Hasser/Isser methods

Enables asking whether some data are present in the Enum

hasValue and hasCase will always return false for a Pure enumeration.

You need the Bakame\Aide\Enum\Hasser trait to expose the new API.

Comparison

The Compare trait which adds four (4) methods to compare Enums instances. The equals and notEquals methods do strict comparison whereas isOneOf and isNotOneOf do loose comparison taking into account the value or the name of the Enum.

You need the Bakame\Aide\Enum\Compare trait to expose the new API.

Convert

The Convert trait adds three (3) methods to convert Enums instances. The toAssociative converts the Enum instance into an associative array whereas the toJavaScriptObject and toJavaScriptClass methods convert the Enum into a JavaScript equivalent structure.

You need the Bakame\Aide\Enum\Convert trait to expose the new API.

All in one

If you want to apply all the traits together just use the single one which encompass all the traits already mentioned Bakame\Aide\Enum\Helper. Once added to your enum all the methods described here will be made available to your codebase.

You need the Bakame\Aide\Enum\Helper to expose the new API.

Converting the Enum into a JavaScript structure

While the Convert::toJavaScriptObject and Convert::toJavaScriptClass methods are enough to convert your Enum to JavaScript code, behind the scene the method makes use of the JavaScriptConverter class. The class enables returning a more fine-tuned representation that suite your constraints better.

Because there are two (2) ways to create an Enum like structure in JavaScript, the class provides two (2) methods to allow the conversion.

In both cases, the conversion is configurable via wither methods to control the formatting and the JavaScript structure properties.

Backed Enum

For instance, given I have the following enum:

It can be converted into an object using the convertToObject method:

will produce the following JavaScript code snippet:

conversely using convertToClass as follows:

will produce the following JavaScript code snippet:

Of course there are ways to improve the output depending on your use case you can

• ignore or use object immutability;
• ignore or use JavaScript export or export default;
• change the class name or add and/or change the object variable name;
• use Symbol when declaring the object property value;
• define indentation spaces and thus end of line;
• define the presence or absence of a trailing comma in the object representation;

Here's a more advance usage of the converter to highlight how you can configure it.

will return the following JavaScript code:

Pure Enum

For Pure PHP Enum, the converter will assign a unique Symbol value for each case, starting wih the Symbol(0) and following the PHP order of case declaration. you can optionally configure the start value using the startAt method.

Let's take the following PHP Pure Enum:

It can be converted into an object using the convertToObject method:

will produce the following JavaScript code snippet:

If you set up the starting value to increment you will get a different value:

Then the start at value will be taken into account as shown below:

[!CAUTION]
For Pure Enum the ignoreSymbol and useSymbol methods have no effect on the output.

Storing the output

The converter will not store the resulting string into a Javascriot file as this part is left to the discretion of the implementor. There are several ways to do so:

• using vanilla PHP with file_put_contents or SplFileObject
• using more robust and battle tested packages you can find on packagist for instance.

Credits

• ignace nyamagana butera
• All Contributors