Enums (PHP 8.1)

Parte da seção Programação Orientada a Objetos do Journey de PHP da Coddy — lição 59 de 91.

Antes do PHP 8.1, representar um conjunto fixo de valores, como status ou tipos, significava usar constantes de classe ou strings mágicas — ambas abordagens propensas a erros. Enums (enumerações) fornecem uma maneira adequada de definir um tipo que pode conter apenas valores específicos e predefinidos.

Defina um enum usando a palavra-chave enum:

<?php
enum Status {
    case Pending;
    case Active;
    case Completed;
}

$status = Status::Active;
echo $status->name;

Saída:

Active

Enums também podem ter valores de suporte (backed values) - valores de string ou inteiros associados a cada caso. Isso é útil ao armazenar enums em bancos de dados ou APIs:

<?php
enum Status: string {
    case Pending = 'pending';
    case Active = 'active';
    case Completed = 'completed';
}

$status = Status::Active;
echo $status->value;

Saída:

active

Backed enums fornecem um método from() para criar um enum a partir de seu valor, e tryFrom() que retorna null em vez de lançar um erro para valores inválidos:

<?php
$status = Status::from('active');      // Retorna Status::Active
$invalid = Status::tryFrom('unknown'); // Retorna null

Enums também podem conter métodos, tornando-os poderosos para encapsular lógica relacionada. Eles funcionam perfeitamente com type hints, garantindo que suas funções aceitem apenas valores válidos - sem a necessidade de verificar se uma string corresponde às opções esperadas.

Desafio

Fácil

Vamos construir um sistema de gerenciamento de pedidos que utiliza enums para representar os status dos pedidos de forma segura em termos de tipo. Em vez de depender de strings que podem ser digitadas incorretamente ou ser inválidas, você criará um backed enum que mapeia cada status para um valor amigável ao banco de dados.

Você organizará seu código em três arquivos:

OrderStatus.php — Crie um string-backed enum chamado OrderStatus com quatro casos:
- Pending associado a 'pending'
- Processing associado a 'processing'
- Shipped associado a 'shipped'
- Delivered associado a 'delivered'
Adicione um método label() que retorna uma descrição legível para cada status:
- Pending retorna "Awaiting confirmation"
- Processing retorna "Being prepared"
- Shipped retorna "On the way"
- Delivered retorna "Order complete"
Order.php — Crie uma classe Order que utiliza o enum. Inclua o arquivo OrderStatus. A classe deve:
- Aceitar um ID de pedido (string) e um OrderStatus em seu construtor usando promoção de construtor (constructor promotion)
- Ter um método getInfo() que retorna "Order [id]: [status label]"
- Ter um método getStatusValue() que retorna o valor associado (backed value) do status (útil para armazenamento em banco de dados)
main.php — Inclua o arquivo Order. Você receberá duas entradas: um ID de pedido e uma string de status (como "shipped"). Use tryFrom() para converter com segurança a string de entrada em um enum OrderStatus. Se o status for válido, crie um Order e imprima duas linhas:
- O resultado de getInfo()
- O resultado de getStatusValue()
Se a string de status for inválida, imprima "Invalid status".

Este desafio demonstra como os enums fornecem segurança de tipo — sua classe Order só pode aceitar status válidos, e o método tryFrom() permite que você manipule a entrada do usuário com segurança, sem arriscar valores inválidos.

Folha de consulta

Enums fornecem uma maneira segura em termos de tipo (type-safe) para definir um conjunto fixo de valores. Defina um enum usando a palavra-chave enum:

<?php
enum Status {
    case Pending;
    case Active;
    case Completed;
}

$status = Status::Active;
echo $status->name; // Saída: Active

Backed enums associam valores de string ou inteiros a cada caso:

<?php
enum Status: string {
    case Pending = 'pending';
    case Active = 'active';
    case Completed = 'completed';
}

$status = Status::Active;
echo $status->value; // Saída: active

Use from() para criar um enum a partir de seu valor, ou tryFrom() que retorna null para valores inválidos:

<?php
$status = Status::from('active');      // Retorna Status::Active
$invalid = Status::tryFrom('unknown'); // Retorna null

Enums podem conter métodos para encapsular a lógica relacionada:

<?php
enum Status: string {
    case Pending = 'pending';
    case Active = 'active';
    
    public function label(): string {
        return match($this) {
            self::Pending => 'Awaiting',
            self::Active => 'In Progress',
        };
    }
}

Experimente você mesmo

<?php

require_once 'Order.php';

// Ler a entrada
$orderId = trim(fgets(STDIN));
$statusString = trim(fgets(STDIN));

// TODO: Use OrderStatus::tryFrom() para converter com segurança a string de status para um enum
// tryFrom() retorna null se o valor for inválido

// TODO: Se o status for válido, crie um Order e imprima:
// - O resultado de getInfo()
// - O resultado de getStatusValue()

// TODO: Se o status for inválido, imprima "Invalid status"

?>