Enum backed values in PHP - Deep Dive

Overview - Enum backed values

What is it?

Enum backed values in PHP are a way to assign fixed scalar values like strings or integers to each case in an enum. This means each enum case not only has a name but also a specific value attached to it. It helps represent a set of related constants with meaningful values. This feature was introduced to make enums more powerful and useful in real applications.

Why it matters

Without enum backed values, developers would have to manage separate constants or arrays to link names to values, which can cause mistakes and make code harder to read. Enum backed values simplify this by bundling the name and value together, reducing bugs and improving clarity. This makes programs easier to maintain and understand, especially when dealing with fixed sets of options like statuses or categories.

Where it fits

Before learning enum backed values, you should understand basic PHP enums and scalar types like strings and integers. After mastering enum backed values, you can explore advanced enum features like methods inside enums and using enums with type safety in functions and classes.

Mental Model

Core Idea

Enum backed values are like labeled boxes where each label (case name) holds a fixed, meaningful value inside it.

Think of it like...

Imagine a set of mailboxes where each mailbox has a number on it. The mailbox name is the enum case, and the number on it is the backed value. You can refer to the mailbox by name or by its number, and both always match.

Enum Backed Values Structure
┌───────────────┐
│ Enum: Status │
├───────────────┤
│ Case: PENDING │───▶ Value: 1
│ Case: ACTIVE  │───▶ Value: 2
│ Case: CLOSED  │───▶ Value: 3
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Basic PHP Enums

Concept: Learn what enums are and how to define simple enums without values.

PHP enums let you define a set of named constants grouped together. For example: enum Status { case PENDING; case ACTIVE; case CLOSED; } Each case is just a name representing a fixed option.

Result

You can use Status::PENDING, Status::ACTIVE, or Status::CLOSED as fixed names in your code.

Understanding basic enums sets the stage for adding values, showing how enums group related options.

2

Foundation

Scalar Types in PHP

Concept: Review PHP scalar types like integers and strings that can be used as enum backed values.

PHP has simple data types like int (numbers) and string (text). For example: $number = 5; $text = 'hello'; These types are used to store single pieces of data.

Result

Knowing scalar types helps you understand what kinds of values enums can hold.

Recognizing scalar types is essential because enum backed values must be either int or string.

3

Intermediate

Defining Enum Backed Values

🤔Before reading on: do you think enum cases can have any type of value, like arrays or objects? Commit to your answer.

Concept: Introduce how to assign fixed int or string values to enum cases.

In PHP, you can define an enum with backed values by specifying the type and assigning values: enum Status: int { case PENDING = 1; case ACTIVE = 2; case CLOSED = 3; } Each case now has a fixed integer value.

Result

You can access the value with Status::PENDING->value which returns 1.

Knowing that enum cases can carry fixed scalar values makes enums more practical for real-world use.

4

Intermediate

Using String Backed Enums

🤔Before reading on: do you think string backed enums behave differently than int backed enums? Commit to your answer.

Concept: Learn how to use strings as backed values for enums.

You can also use strings as backed values: enum Direction: string { case NORTH = 'N'; case SOUTH = 'S'; case EAST = 'E'; case WEST = 'W'; } This helps when values need to be readable or match external data.

Result

Accessing Direction::NORTH->value returns 'N'.

Using strings as backed values allows enums to represent meaningful text codes, improving clarity.

5

Intermediate

Retrieving Enum Cases by Value

🤔Before reading on: do you think you can get an enum case from its value directly? Commit to your answer.

Concept: Learn how to find an enum case by its backed value using built-in methods.

PHP enums provide a static method from() to get a case by value: $status = Status::from(2); echo $status->name; // Outputs: ACTIVE If the value doesn't match any case, it throws an exception.

Result

You can convert values back to enum cases safely.

Being able to get enum cases from values allows smooth conversion between stored data and enum usage.

6

Advanced

Enum Backed Values with Methods

🤔Before reading on: do you think enum cases with backed values can have custom methods? Commit to your answer.

Concept: Explore adding methods to enums to work with backed values and add behavior.

Enums can have methods to add logic: enum Status: int { case PENDING = 1; case ACTIVE = 2; case CLOSED = 3; public function isActive(): bool { return $this === self::ACTIVE; } } $status = Status::ACTIVE; echo $status->isActive() ? 'Yes' : 'No'; // Outputs: Yes

Result

Enums become more powerful by combining data and behavior.

Adding methods to enums with backed values lets you encapsulate related logic cleanly.

7

Expert

Limitations and Performance of Backed Enums

🤔Before reading on: do you think backed enums have no performance cost compared to constants? Commit to your answer.

Concept: Understand internal behavior, limitations, and performance considerations of backed enums.

Backed enums are objects under the hood, so accessing them involves object creation and method calls. They cannot hold complex types like arrays or objects as values. Also, from() throws exceptions if values don't match, so error handling is needed. Compared to plain constants, backed enums add type safety but with slight overhead.

Result

You gain safety and clarity but must handle exceptions and minor performance tradeoffs.

Knowing the tradeoffs helps decide when to use backed enums versus simpler constants.

Under the Hood

PHP backed enums are implemented as special classes where each case is a singleton object with a fixed scalar property called 'value'. When you access a case, PHP returns the same object instance. The 'value' property holds the scalar value assigned. The from() method searches cases by value and returns the matching object or throws an exception if none matches.

Why designed this way?

Backed enums were designed to combine the clarity of enums with the practicality of fixed scalar values, improving type safety and reducing errors. The choice to limit values to int or string keeps the implementation simple and efficient. Using objects allows adding methods and behavior to enums, making them more versatile than plain constants.

Backed Enum Internal Structure
┌─────────────────────────────┐
│ Enum Class: Status          │
│ ┌───────────────┐          │
│ │ Case Object   │          │
│ │ Name: PENDING │          │
│ │ Value: 1      │          │
│ └───────────────┘          │
│ ┌───────────────┐          │
│ │ Case Object   │          │
│ │ Name: ACTIVE  │          │
│ │ Value: 2      │          │
│ └───────────────┘          │
│ ┌───────────────┐          │
│ │ Case Object   │          │
│ │ Name: CLOSED  │          │
│ │ Value: 3      │          │
│ └───────────────┘          │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Can enum backed values be any PHP type like arrays or objects? Commit to yes or no.

Common Belief: Enum backed values can be any PHP type, including arrays or objects.

Reality: Backed values are limited to scalar types: only int or string are allowed.

Why it matters: Trying to use unsupported types causes syntax errors and confusion, blocking correct enum usage.

Quick: Does from() method return null if no matching value is found? Commit to yes or no.

Common Belief: The from() method returns null when no enum case matches the given value.

Reality: from() throws a ValueError exception if the value does not match any case.

Why it matters: Not handling this exception can cause unexpected crashes in applications.

Quick: Are enum backed values mutable after definition? Commit to yes or no.

Common Belief: You can change the backed value of an enum case at runtime.

Reality: Enum backed values are immutable and fixed at compile time.

Why it matters: Expecting mutability leads to bugs when trying to modify enum values dynamically.

Quick: Do backed enums perform exactly like constants with zero overhead? Commit to yes or no.

Common Belief: Backed enums have no performance cost compared to using plain constants.

Reality: Backed enums involve object creation and method calls, so they have slight performance overhead.

Why it matters: Ignoring this can cause performance issues in very high-load scenarios.

Expert Zone

1

Backed enums are singletons per case, so comparing cases with === works reliably and efficiently.

2

The from() method throws exceptions, but tryFrom() returns null on failure, offering safer alternatives.

3

Backed enums cannot be extended or inherited, preserving their fixed set of cases and values.

When NOT to use

Avoid backed enums when you need complex or mutable values, or when performance is critical and you prefer simple constants. Use plain constants or value objects instead.

Production Patterns

Backed enums are widely used for status codes, configuration options, and API response types. They improve code readability and reduce bugs by enforcing valid values and enabling switch-case statements with type safety.

Connections

Type-safe constants

Backed enums build on and improve type-safe constants by grouping related values with names and types.

Understanding backed enums clarifies how to replace scattered constants with safer, grouped alternatives.

Database enum columns

Backed enums correspond to enum columns in databases, mapping fixed values between code and storage.

Knowing backed enums helps synchronize application logic with database constraints, reducing data errors.

Finite state machines (FSM)

Backed enums represent states in FSMs, where each state has a fixed identity and behavior.

Recognizing enums as states aids in designing clear, maintainable state-driven systems.

Common Pitfalls

#1 Using unsupported types as backed values.

Wrong approach:

enum Colors: array {
case RED = ['#FF0000'];
}

Correct approach:

enum Colors: string {
case RED = '#FF0000';
}

Root cause:

Misunderstanding that backed values must be scalar types (int or string) only.

#2 Not handling exceptions from from() method.

Wrong approach:

try {
$status = Status::from(99);
} catch (Exception $e) {
// no handling
}

Correct approach:

if ($status = Status::tryFrom(99)) {
// use $status
} else {
// handle invalid value
}

Root cause:

Assuming from() returns null instead of throwing exceptions on invalid values.

#3 Trying to change enum backed values at runtime.

Wrong approach:

$status = Status::ACTIVE;
$status->value = 5; // attempt to change value

Correct approach:

// Enum backed values are immutable; define correct values at declaration.

Root cause:

Not realizing enum cases are immutable objects with fixed values.

Key Takeaways

Enum backed values in PHP let you assign fixed int or string values to enum cases, combining names and meaningful data.

They improve code clarity, reduce errors, and enable safe conversions between values and enum cases.

Backed enums are immutable and limited to scalar types, with built-in methods to retrieve cases by value.

Understanding their internal object-based design helps grasp their behavior and performance tradeoffs.

Using backed enums effectively requires handling exceptions and knowing when simpler constants might be better.