Por omisión, los Casos Enumerados no tienen equivalente escalar. Son simplemente objetos singleton. Sin embargo, hay amplios casos en los que un Caso Enumerado necesita poder hacer un viaje de ida y vuelta a una base de datos o un almacén de datos similar, por lo que tener un equivalente escalar integrado (y por lo tanto trivialmente serializable) definido intrínsecamente es útil.
Para definir un equivalente escalar para una Enumeración, la sintaxis es la siguiente:
<?php
enum Suit: string
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}
?>Un caso que tiene un equivalente escalar se denomina Caso Respaldado, ya que está "respaldado" por un valor más simple. Una enumeración que contiene todos los Casos Respaldados se denomina "Enumeración Respaldada". Una Enumeración Respaldada solo puede contener Casos Respaldados. Una Enumeración Pura solo puede contener Casos Puros.
Una Enumeración Respaldada puede estar respaldada por tipos de int o string,
y una enumeración dada admite solo un tipo a la vez (es decir, no hay unión de int|string).
Si una enumeración está marcada como que tiene un equivalente escalar, entonces todos los casos deben tener un equivalente
escalar único definido explícitamente. No hay equivalentes escalares generados automáticamente
(por ejemplo, enteros secuenciales). Los casos respaldados deben ser únicos; dos casos de enumeración respaldados no pueden
tener el mismo equivalente escalar. Sin embargo, una constante puede referirse a un caso, creando efectivamente
un alias. Ver Constantes de enumeración.
Los valores equivalentes pueden ser una expresión escalar constante.
Antes de PHP 8.2.0, los valores equivalentes debían ser literales o expresiones literales.
Esto significa que las constantes y expresiones constantes no estaban admitidas.
Es decir, 1 + 1 estaba permitido, pero 1 + SOME_CONST no.
Los Casos Respaldados tienen una propiedad adicional de solo lectura, value, que es el valor
especificado en la definición.
<?php
print Suit::Clubs->value;
// Imprime "C"
?>
Para hacer cumplir la propiedad value como de solo lectura, una variable no puede
ser asignada como referencia a ella. Es decir, lo siguiente genera un error:
<?php
$suit = Suit::Clubs;
$ref = &$suit->value;
// Error: No se puede obtener una referencia a la propiedad Suit::$value
?>Las enumeraciones respaldadas implementan una interfaz interna BackedEnum, que expone dos métodos adicionales:
from(int|string): self tomará un escalar y devolverá el Caso de Enumeración correspondiente.
Si no se encuentra ninguno, lanzará un ValueError. Esto es principalmente
útil en casos donde el escalar de entrada es confiable y un valor de enumeración faltante debería ser
considerado un error que detiene la aplicación.
tryFrom(int|string): ?self tomará un escalar y devolverá el
Caso de Enumeración correspondiente. Si no se encuentra ninguno, devolverá null.
Esto es principalmente útil en casos donde el escalar de entrada no es confiable y el llamador quiere
implementar su propia lógica de manejo de errores o valores por omisión.
Los métodos from() y tryFrom() siguen las reglas estándar
de tipado débil/fuerte. En modo de tipado débil, pasar un entero o string es admisible
y el sistema coercionará el valor en consecuencia. Pasar un float también funcionará y será
coercionado. En modo de tipado estricto, pasar un entero a from() en una
enumeración respaldada por string (o viceversa) resultará en un TypeError,
al igual que un float en todas las circunstancias. Todos los demás tipos de parámetros lanzarán un TypeError
en ambos modos.
<?php
$record = get_stuff_from_database($id);
print $record['suit'];
$suit = Suit::from($record['suit']);
// Datos no válidos lanzan un ValueError: "X" no es un valor escalar válido para la enumeración "Suit"
print $suit->value;
$suit = Suit::tryFrom('A') ?? Suit::Spades;
// Datos no válidos devuelven null, por lo que se usa Suit::Spades en su lugar.
print $suit->value;
?>Definir manualmente un método from() o tryFrom() en una Enumeración Respaldada resultará en un error fatal.