PHP 8.1 finalmente agregará soporte lingüístico para enumias. Enumeres, cortos para enumeraciones, son tipos que solo pueden instasizarse con valores específicos. Se encuentran comúnmente en otros idiomas orientados a objetos, pero anteriormente han requerido que las soluciones de soluciones de usuario de Userland implementen en PHP.

Sintaxis básica

Esto es lo que parece un enumme simple:

---

enum PostStatus {
    case Published;
    case InReview;
    case Draft;
}

---

La palabra clave del caso, parte previa de las declaraciones de interruptor, se usa para delinear los valores específicos que acepta el enum. Los valores se hacen referencia de la misma manera que las constantes de la clase:

---

$published = PostStatus::Published;

---

Los enumers se comportan de manera similar a las clases e interfaces. Son totalmente compatibles con el sistema tipo, por lo que puede contemplar que una función solo acepta un valor definido en un enumeración:

---

class BlogPost {
 
    public function __construct(
        public string $Headline,
        public string $Content,
        public PostStatus $Status=PostStatus::Draft) {}
 
}

---

Aquí hay un ejemplo de usar la clase BlogPost:

---

// OK
$post = new BlogPost(
    "Example Post",
    "An example",
    PostStatus::Draft
);
 
// TypeError: Argument #3 ($Status) must be of type PostStatus
$post = new BlogPost(
    "Broken Example",
    "A broken example",
    "Submitted"
);

---

La primera instancia funciona porque su estado $ es un valor válido del PostStatus Enum. En el segundo caso, se pasa una cadena simple como $ estado, que está prohibido ya que el valor debe definirse dentro de PostStatus.

Los casos enum son representados como constantes en el objeto enumio. Esto significa que puede usarlos como valores estáticos y como parte de expresiones constantes. El constructor BlogPost muestra un caso de enumeración que se está utilizando como un valor de parámetro predeterminado, donde el estado $ se establece automáticamente en el borrador cuando la persona que llama no proporciona ningún valor.

Puede acceder a todos los valores disponibles en un Enum usando sus casos.

---

PostStatus::cases();
// [PostStatus::Published, PostStatus::InReview, PostStatus::Draft]

---

PUERTOS VS BACKED ENUMES

El poststatus enumio de arriba es un enumio puro. Solo contiene afirmaciones de casos, sin datos adicionales. PHP también le permite adjuntar un valor a los casos de enumeración, creando un enumeración respaldado.

---

enum PostStatus : string {
    case Published = "S1";
    case InReview = "S2";
    case Draft = "S3";
}

---

Aquí se ha modificado el poststatus enum para crear un enumio respaldado. El Typehint en la definición de Enum se estipula que cada caso tiene un valor de cadena asignado a él. En este ejemplo, asumimos que cada estado de publicación con nombre tiene un identificador corto asociado. Puede ser este identificador que se guarde en la base de datos cuando se persiguen las publicaciones.

Puede acceder a los valores respaldados a través de la propiedad de valor en caso de instancia:

---

class BlogPostRepository {
 
    public function save(BlogPost $Post) : void {
        $this -> insert(
            "blog_posts",
            [
                "headline" => $Post -> Headline,
                "content" => $Post -> Content,
                "status" => $Post -> Status -> value
            ]
        );
    }
 
}
 
$post = new BlogPost("Example", "Demo", PostStatus::Published);
(new BlogPostRepository()) -> save($post);

---

Este ejemplo establecería el valor del campo de estado persistido en S1, en función de la versión respaldada del PostStatus enum que se muestra arriba.

Los enumeros respaldados solo aceptan cadenas y enteros como valores. No es posible utilizar la cadena de tipo de unión | INT tampoco. Además, cada caso necesita un valor único, el siguiente ejemplo no está permitido:

---

enum PostStatus : string {
 
    case Published = "S1";
    case Draft = "S1";
 
}

---

PHP proporciona un método de utilidad en los enumeros para crear una instancia de un valor respaldado:

---

// fetch the blog post from earlier from the database
// the "status" field = S1
$status = PostStatus::from($record["status"]);

---

El método de () hidratará las instancias de los casos de valor. En este ejemplo, S1 se remonta a la caja publicada, y su código recibe una instancia de PostStatus :: Publicado.

de () lanza un ValorError si el valor de entrada no es válido; En los escenarios, donde sabe que el valor podría no ser utilizable, en su lugar se puede usar el método de prueba alternativa (). Esto devuelve nulo cuando no hay ninguna coincidencia, en lugar de lanzar el error.

Añadiendo métodos a los enumeros

¡Como enumanos se basan en clases, también puede agregar métodos!

---

enum PostStatus {
 
    case Published;
    case Draft;
 
    public function isPubliclyAccessible() : bool {
        return ($this instanceof self::Published);
    }
 
}

---

Esto le permite mantener un comportamiento específico de los casos dentro de su enumeración, en lugar de duplicarlo en su base de código.

Enums también pueden implementar interfaces:

---

enum PostStatus implements PublicAccessGatable {
 
    case Published;
    case Draft;
 
    public function isPubliclyAccessible() : bool {
        return ($this instanceof self::Published);
    }
 
}

---

Ahora puede pasar una instancia de PostStatus a cualquier cosa que acepte un PublicCessccessgatable:

---

class UserAuthenticator {
 
    function shouldAllowAccess(PublicAccessGatable $Resource) : bool {
        return ($this -> User -> isAdmin() || $Resource -> isPubliclyAccessible());
    }
 
}
 
$auth = new UserAuthenticator();
 
// get a blog post from the database
if (!$auth -> shouldAllowAccess($post -> Status)) {
    http_response_code(403);
}

---

No hay restricciones sobre lo que puede hacer con los métodos de Enumio: son métodos regulares de PHP, después de todo, pero en general esperaría que realicen algún tipo de comparación contra el caso de la instancia, luego devuelva un valor estático. Los enumeres pueden usar rasgos, por lo que puede tirar de los métodos existentes que también ha abstraído de esta manera.

Puede utilizar métodos públicos, protegidos y privados en enumias, aunque protegidos y privados tienen el mismo efecto. Los enumnos no pueden extenderse, por lo que la privada es efectivamente redundante. No puedes agregar un constructor o destructor tampoco. Los métodos estáticos son compatibles y se pueden llamar a la clase de enumeración o en sus casos.

Constantes

Enums también puede tener sus propias constantes, ya sea como valores literales regulares o una referencia a un caso enumio:

---

enum PostStatus {
 
    case Published;
    case Draft;
 
    public const Live = self::Published;
    public const PlainConstant = "foobar";
 
}

---

Esto posee el potencial de crear confusión a medida que se utiliza la misma sintaxis para acceder a los casos (instancias de enumeración) y las constantes:

---

$published = PostStatus::Published;
$plain = PostStatus::PlainConstant;

---

Solo $ Publicado satisfaría un poststatus typhint, ya que $ se refiere a un valor escalar simple.

¿Cuándo usar Enums?

Los enumnos son para ocasiones en las que necesita flexibilidad en el valor que puede tomar una variable, pero solo entre un conjunto predeterminado de casos posibles.

La clase de publicación del blog que se ejecuta a través de esta publicación es un ejemplo clásico. Las publicaciones solo pueden estar en uno de un conjunto conocido de estados, pero PHP anteriormente no tuvo una forma directa de lograr esto.

En versiones anteriores, es posible que haya utilizado este enfoque:

---

class PostStatus {
    const Published = 0;
    const Draft = 1;
}
 
class BlogPost {
    public function __construct(
        public string $Headline,
        public int $Status
    ) {}
}
 
$post = new BlogPost("My Headline", PostStatus::Published);

---

El problema aquí es que $ $ estado realmente acepta cualquier entero, por lo que la siguiente llamada sería perfectamente válida:

---

$post = new BlogPost("My Headline", 9000);

---

Además, BlogPost y Poststtatus están completamente separados, no hay forma de que alguien que lea BlogPost pueda aprender la gama de valores que se acepta $ en realidad. Si bien estos problemas se pueden mitigar utilizando los tíos de Docblock apropiados, o los paquetes de terceros “falsos”, todos agregan capas adicionales alrededor de un concepto que otros idiomas de programación hacen simples.

Agregar enumias nativas a PHP es un paso que ayuda a redondear el sistema de tipo del idioma. Finalmente, puede limitar los valores permisibles de una manera que mantiene a todos en la misma página. Si pasa un valor no válido, obtendrá un error de tiempo de ejecución. Su IDE puede ayudarlo mejor a suministrar valores correctos, ya que sabrá que $ $ sólo acepta tres opciones, en lugar de “cualquier entero”.

Conclusión

Los enumers abordan algunos puntos de dolor de desarrolladores comunes cuando se trabaja en PHP. Hacen posible conjustar los parámetros, los valores de retorno y las propiedades deben ser uno de un conjunto de opciones predeterminadas.

Los enumeres son entidades de base de código flexibles que puede mantenerse simple en forma pura, o extenderse con valores respaldados, implementaciones de interfaz y métodos personalizados. Los enumers se comportan de manera similar a los objetos regulares en la mayoría de los casos y soportan características de la clase, como __call (), __InVoke y :: Class.

Puedes enumeraciones introspectas con la nueva función enum_exists () y la clase de reflexión de reflejo. Además, los enumeran implementan dos nuevas interfaces, Unindenum (en el caso de enumias puras) y BackedEnum (para enumias con valores respaldados). Estos se pueden utilizar en un código de marco genérico que funciona con cualquier enumeración. Las interfaces no pueden ser implementadas manualmente por el código de Userland.

Enums aterrizará en PHP como parte de la versión 8.1 en noviembre de 2021. Ya están disponibles en las últimas BETA BUMS. PHP 8.1 también enviará varias características de conveniencia, incluidas las propiedades inmediatas y los tipos de intersección.