The php_enum model is used to define an enumeration object. These objects were introduced in PHP 8.1.0 and allow you to define a list of valid values for a property or variable. If a property is defined as type string, it can generally be assigned any valid string value, without restriction. By using enumerations, you can have the PHP runtime engine enforce rules around the values that can be assigned to a property or a function argument or return value.

Consider the following enum definition named suit:

This will generate the following simple PHP enum object:

enum suit {
  case Hearts;
  case Diamonds;
  case Clubs;
  case Spades;
}

The actual name of the definition, in this example suit, is determined by the name under which you stow the enum object. Only lower case enum definitions are allowed by GenHelm.

Let's review the parameters supported by the php_enum model.

Before Enum

The Before Enum control is used to define code that will be placed at the top of the generated definition. This is usually used to specify a namespace and/or require code, such as trait definitions, to be incorporated into the enum.

Implements

If your enum object implements a certain interface, enter it here. You can implement multiple interfaces by listing them separated by a comma.

Enumerator Cases (Values)

This is the main enumerator definition.

Enum Case

This column is required and contains the unique enumeration values. These can be defined in mixed case. Embedded spaces are not permitted.

Backed Value

PHP supports a concept of backed enumerations whereby each enum value can be associated with a string or an integer. This feature is often used to translate enumerations into values that can be stored in a database or other permanent data storage location.

Comment

Comments are not generated into the enum definition. These can be used to provide information about each enum value.

Optional Methods

Enumerations can include functions as well as use blocks to incorporate other traits. The php_emun model makes use of the generic custom code handler utilized by other models. As such, not all custom code features are available within the context of the php_enum model.

Section Type

The section type must be one of use, function or example. 

Section Id

Enumerations to not make use of this column.

Location

The location must be After Last Sibling.

Method Example

Enumeration objects can define methods. Let's look at an example of how these can be used. Here we have a Backed Enumeration definition:

This definition includes a method that will be used to determine whether a day value is a weekend day.

Let's assume that we stowed this enum under the name dayofweek. Next we will look at how we can use this enum definition from a PHP Class generated using the custom model.

First, we need to pull in the enum definition. Notice that generated enumerations are stored within the enum subfolder of the classes folder.

Next we add a property to our class of type dayofweek:

In the generate method we add the following code (this will be under Section Type function, Section Id generate and Location Replace Body):

We call the dollar date function to get today's date in the form of a 3-character day name (since the backed values are 3-characters).

Then we used the built-in from method of value-backed enum objects to assign the day property based on the 3-character day name that matches the enum object's backed value.

Finally, we call the enum's is_weekend method to determine whether today is a weekend day and return a suitable message.