Enums PHP: Guia completo para usar Enums em PHP 8.1+

Definindo Enums em PHP 8.1

Com a chegada do PHP 8.1, a linguagem passou a oferecer suporte nativo a enums, utilizando a palavra-chave enum. Para declarar uma enumeração, o desenvolvedor deve especificar um nome seguido por uma lista de casos. Cada caso representa uma instância única que não pode ser instanciada diretamente.

enum Status {
    case Draft;
    case Published;
    case Archived;
}

Para acessar os casos, utilize o operador de resolução de escopo: Status::Draft. As declarações de tipo aceitam o nome da enumeração, garantindo uma segurança de tipo rigorosa. Além disso, os enums integram-se perfeitamente com instruções switch e expressões de correspondência, permitindo uma verificação exaustiva.

Enums apoiados para valores escalares

As enumerações apoiadas associam cada caso a um valor, que pode ser um inteiro ou uma string. Para declarar o tipo de apoio, basta indicá-lo após o nome da enumeração e atribuir valores aos casos.

enum Status: string {
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

O valor de apoio pode ser recuperado através da propriedade value. Os métodos from() e tryFrom() permitem converter valores escalares de volta em instâncias de enum. O método from() lança um ValueError em caso de entrada inválida, enquanto tryFrom() retorna null se não houver correspondência.

$status = Status::from('published');
$status = Status::tryFrom('unknown'); // null

É importante destacar que as enumerações apoiadas impõem valores exclusivos por tipo, não permitindo a mistura de tipos int e string em um mesmo enum.

Métodos e propriedades dentro de enums

Os enums podem conter métodos, métodos estáticos e constantes. Dessa forma, é possível definir o comportamento diretamente nos casos, sem a necessidade de classes externas.

enum Status: string {
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';

    public function label(): string {
        return match($this) {
            self::Draft => 'Work in progress',
            self::Published => 'Live on site',
            self::Archived => 'Removed from view',
        };
    }

    public static function activeCases(): array {
        return [self::Draft, self::Published];
    }
}

Os métodos de instância podem ser chamados em casos específicos, como em Status::Draft->label(). Por outro lado, os métodos estáticos operam diretamente no enum. Os modificadores de visibilidade, como private e protected, funcionam como esperado.

Implementando Interfaces

Os enums têm a capacidade de implementar interfaces, permitindo um uso polimórfico junto com classes. Isso nos lembra muito o que discutimos sobre Guia de carreira e habilidades salariais do desenvolvedor Node.js 2024.

interface Describable {
    public function description(): string;
}

enum Status: string implements Describable {
    case Draft = 'draft';
    // ...
    public function description(): string {
        return $this->label() . ' status';
    }
}

Qualquer função que espera um objeto Describable pode aceitar casos de Status. Essa abordagem permite que as enumerações sejam utilizadas em modelos de domínio que exigem conformidade com contratos.

Serialização e manipulação de JSON

As enumerações são serializadas utilizando seu valor de apoio quando json_encode é aplicado. Em contrapartida, enums sem suporte são serializados com base no nome do caso. Para uma serialização personalizada, é necessário implementar a interface JsonSerializable.

enum Status: string implements JsonSerializable {
    // cases...
    public function jsonSerialize(): string {
        return $this->value;
    }
}

A desserialização pode ser realizada utilizando from() ou tryFrom() após a decodificação do JSON. Normalmente, a persistência em bancos de dados armazena o valor de apoio, reconstruindo o enum durante a recuperação.

Casos de uso prático

As máquinas de estado se beneficiam de uma cobertura exaustiva dos jogos. Além disso, os sinalizadores de configuração tornam-se mais legíveis quando substituídos por casos enum. Sistemas de permissão utilizam enums para representar funções, evitando o uso de sequências mágicas.

function transition(Status $current, Status $next): bool {
    return match([$current, $next]) {
        [Status::Draft, Status::Published] => true,
        // outras transições válidas
        default => false,
    };
}

Bibliotecas de validação de formulário podem mapear dados de solicitação para instâncias enum utilizando tryFrom(). Por fim, as respostas da API frequentemente retornam os valores de apoio dos enums, enquanto a lógica interna opera utilizando os casos tipados.

Características de desempenho e memória

Os casos de enum ocupam uma quantidade mínima de memória, pois são singletons criados uma única vez por solicitação. A comparação entre eles utiliza verificações de identidade (===), o que proporciona maior velocidade. A API Reflection expõe os casos através de ReflectionEnum, permitindo a inspeção dinâmica em estruturas.

Migração de abordagens legadas

É recomendável substituir constantes de classe e classes abstratas que eram utilizadas anteriormente por enumerações. Além disso, atualize as dicas de tipo de string ou int para o tipo enum. As consultas ao banco de dados continuarão a utilizar valores escalares, com o código do aplicativo responsável pela conversão no limite.

Limitações a considerar

Os enums não têm a capacidade de estender outros enums ou classes. Além disso, não suportam propriedades que variam por instância. Todos os casos devem ser conhecidos no momento da declaração. As referências circulares entre enums exigem uma ordenação cuidadosa ou a utilização de arquivos separados.

Melhores práticas para código de produção

Mantenha as definições de enum focadas em um único conceito de domínio. Além disso, forneça nomes de métodos que sejam descritivos e que comuniquem claramente a intenção. Utilize enums apoiados quando a persistência ou sistemas externos exigirem uma representação escalar. Documente as transições válidas em enumerações de estado através de nomes de métodos ou constantes. Finalmente, teste a correspondência exaustiva garantindo que todos os casos apareçam nos braços de correspondência durante a análise estática.

Perguntas Frequentes

O que são Enums em PHP?

Enums, ou enumerações, são um tipo de dado que permite definir um conjunto de constantes nomeadas, proporcionando uma maneira mais segura e legível de trabalhar com valores fixos em PHP.

Como eu defino um Enum em PHP 8.1?

Para definir um Enum em PHP 8.1, utilize a palavra-chave enum, seguida pelo nome do Enum e uma lista de casos. Cada caso representa uma instância única.

Quais são as vantagens de usar Enums?

As vantagens incluem maior segurança de tipo, legibilidade do código e a possibilidade de utilizar enums em instruções switch e expressões de correspondência, facilitando a verificação exaustiva.

Enums podem implementar interfaces?

Sim, os Enums podem implementar interfaces, permitindo o uso polimórfico e integrando-se facilmente com outras classes e estruturas de código.