php enum

Implementação de PHP Enum inspirada em SplEnum

A manutenção deste projeto é suportada via Tidelift.

Por que?

Primeiro, e principalmente, SplEnum não está integrado ao PHP, é necessário instalar a extensão separadamente.

Usar um enum em vez de constantes de classe oferece as seguintes vantagens:

• Você pode usar um enum como tipo de parâmetro: function setAction(Action $action) {

• Você pode usar um enum como tipo de retorno: function getAction() : Action {

• Você pode enriquecer o enum com métodos (por exemplo, format , parse ,…)

• Você pode estender o enum para adicionar novos valores (tornar seu enum final para evitar isso)

• Você pode obter uma lista de todos os valores possíveis (veja abaixo)

Esta classe Enum não se destina a substituir constantes de classe, mas apenas para ser usada quando fizer sentido.

Instalação

composer require myclabs/php-enum

Declaração

 use MyCLabsEnumEnum;/** * Action enum * * @extends Enum<Action::*> */final class Action estende Enum
{privado const VIEW = 'visualizar'; privado const EDIT = 'editar';
}

Uso

 $action = Action::VIEW();// ou com uma chave dinâmica:$action = Action::$key();// ou com um valor dinâmico:$action = Action::from($value);/ /ou$action = new Action($value);

Como você pode ver, os métodos estáticos são implementados automaticamente para fornecer acesso rápido a um valor enum.

Uma vantagem sobre o uso de constantes de classe é poder usar um enum como tipo de parâmetro:

 function setAction(Ação $ação) {// ...}

Documentação

• __construct() O construtor verifica se o valor existe no enum

• __toString() Você pode echo $myValue , ele exibirá o valor enum (valor da constante)

• getValue() Retorna o valor atual do enum

• getKey() Retorna a chave do valor atual em Enum

• equals() Testa se as instâncias de enum são iguais (retorna true se os valores de enum forem iguais, false caso contrário)

Métodos estáticos:

• from() Cria uma instância Enum, verificando se o valor existe no enum

• Método toArray() Retorna todos os valores possíveis como um array (nome constante na chave, valor constante no valor)

• keys() Retorna os nomes (chaves) de todas as constantes da classe Enum

• values() Retorna instâncias da classe Enum de todas as constantes Enum (nome da constante na chave, instância Enum no valor)

• isValid() Verifica se o valor testado é válido no conjunto enum

• isValidKey() Verifica se a chave testada é válida no conjunto enum

• assertValidValue() Afirma que o valor é válido no conjunto enum, lançando exceção caso contrário

• search() Chave de retorno para o valor pesquisado

Métodos estáticos

 A ação de classe final estende Enum
{privado const VIEW = 'visualizar'; privado const EDIT = 'editar';
}// Método estático:$action = Action::VIEW();$action = Action::EDIT();

Auxiliares de métodos estáticos são implementados usando __callStatic() .

Se você se preocupa com o preenchimento automático do IDE, você mesmo pode implementar os métodos estáticos:

 A ação de classe final estende Enum
{private const VIEW = 'view';/** * @return Action */public static function VIEW() {return new Action(self::VIEW);
    }
}

ou você pode usar o phpdoc (isso é suportado no PhpStorm, por exemplo):

 /** * @method static Action VIEW() * @method static Action EDIT() */final class Action extends Enum
{privado const VIEW = 'visualizar'; privado const EDIT = 'editar';
}

Enums nativos e migração

O enum nativo chegou ao PHP na versão 8.1: https://www.php.net/enumerations
Se o seu projeto estiver rodando PHP 8.1+ ou sua biblioteca tiver como requisito mínimo você deve usá-lo em vez desta biblioteca.

Ao migrar de myclabs/php-enum , o esforço deverá ser pequeno se o uso for da forma recomendada:

• constantes privadas

• aulas finais

• nenhum método substituído

Mudanças para migração:

• A definição de classe deve ser alterada de

 /** * @method static Action VIEW() * @method static Action EDIT() */final class Action extends Enum
{privado const VIEW = 'visualizar'; privado const EDIT = 'editar';
}

para

 enum Ação: string{case VIEW = 'view';case EDIT = 'edit';
}

Todos os locais onde a classe foi usada como tipo continuarão funcionando.

Usos e mudanças necessárias:

Operação	myclabs/php-enum	enumeração nativa
Obter uma instância mudará de	$enumCase = Action::VIEW()	$enumCase = Action::VIEW
Crie uma enumeração a partir de um valor apoiado	$enumCase = new Action('view')	$enumCase = Action::from('view')
Obtenha o valor apoiado da instância enum	$enumCase->getValue()	$enumCase->value
Compare duas instâncias de enum	$enumCase1 == $enumCase2 ou $enumCase1->equals($enumCase2)	$enumCase1 === $enumCase2
Obtenha a chave/nome da instância enum	$enumCase->getKey()	$enumCase->name
Obtenha uma lista de todas as instâncias possíveis do enum	Action::values()	Action::cases()
Obtenha um mapa de possíveis instâncias do enum mapeado por nome	Action::values()	array_combine(array_map(fn($case) => $case->name, Action::cases()), Action::cases()) ou (new ReflectionEnum(Action::class))->getConstants()
Obtenha uma lista de todos os nomes possíveis do enum	Action::keys()	array_map(fn($case) => $case->name, Action::cases())
Obtenha uma lista de todos os valores possíveis do enum	Action::toArray()	array_map(fn($case) => $case->value, Action::cases())
Obtenha um mapa de possíveis valores apoiados do enum mapeado por nome	Action::toArray()	array_combine(array_map(fn($case) => $case->name, Action::cases()), array_map(fn($case) => $case->value, Action::cases())) ou array_map(fn($case) => $case->value, (new ReflectionEnum(Action::class))->getConstants()))

Projetos relacionados

• Enumeração nativa do PHP 8.1+

• Mapeamento de enum de doutrina

• Integração Symfony ParamConverter

• Integração PHPStan