[Sync EN] unserialization: allowed_classes option with enums (#776)

* [Sync EN] unserialization: allowed_classes option with enums

Refs: php/doc-en@8af3521

* Update unserialize.xml to reflect deprecation notice

Author: lacatoire

language/enumerations.xml

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8"?> <!-- EN-Revision: 1eb67bea30f61f7d9cdfd371146911a0ba07bbd2 Maintainer: leonardolara Status: ready --><!-- CREDITS: lhsazevedo,ae,ABDALAZARD,leonardolara -->
+<?xml version="1.0" encoding="utf-8"?> <!-- EN-Revision: 8af3521cb43f54c652baaf8dbbcb786b79a5d04e Maintainer: leonardolara Status: ready --><!-- CREDITS: lhsazevedo,ae,ABDALAZARD,leonardolara -->
  <chapter xml:id="language.enumerations" xmlns="http://docbook.org/ns/docbook" annotations="interactive">
   <title>Enumerações</title>
   <sect1 xml:id="language.enumerations.overview">
@@ -37,6 +37,7 @@
    <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
+
 enum Naipe
 {
     case Copas;
@@ -59,6 +60,7 @@ enum Naipe
     <programlisting role="php">
 <![CDATA[
 <?php
+
 enum Naipe
 {
     case Copas;
@@ -105,6 +107,7 @@ pegar_uma_carta('Espadas');
     <programlisting role="php">
 <![CDATA[
 <?php
+
 enum Naipe
 {
     case Copas;
@@ -155,6 +158,7 @@ if ($a !== 'Spades') {
     <programlisting role="php">
 <![CDATA[
 <?php
+
 enum Naipe
 {
     case Copas;
@@ -193,6 +197,7 @@ print Naipe::Espadas->name;
   <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
+
 enum Naipe: string
 {
     case Copas = 'C';
@@ -235,6 +240,7 @@ enum Naipe: string
    <programlisting role="php">
 <![CDATA[
 <?php
+
 enum Naipe: string
 {
     case Copas = 'C';
@@ -258,6 +264,7 @@ print Naipe::Paus->value;
    <programlisting role="php">
 <![CDATA[
 <?php
+
 enum Naipe: string
 {
     case Copas = 'C';
@@ -307,6 +314,7 @@ $ref = &$naipe->value;
    <programlisting role="php">
 <![CDATA[
 <?php
+
 enum Naipe: string
 {
     case Copas = 'C';
@@ -352,6 +360,7 @@ print $naipe->value . "\n";
    <programlisting role="php">
 <![CDATA[
 <?php
+
 interface Colorido
 {
     public function cor(): string;
@@ -367,7 +376,7 @@ enum Naipe implements Colorido
     // Cumpre o contrato da interface.
     public function cor(): string
     {
-        return match($this) {
+        return match ($this) {
             Naipe::Copas, Naipe::Ouros => 'Vermelho',
             Naipe::Paus, Naipe::Espadas => 'Preto',
         };
@@ -405,6 +414,7 @@ print Naipe::Ouros->forma(); // imprime "Retângulo"
   <programlisting role="php" annotations="non-interactive">
    <![CDATA[
 <?php
+
 interface Colorido
 {
     public function cor(): string;
@@ -420,7 +430,7 @@ enum Naipe: string implements Colorido
     // Cumpre o contrato da interface.
     public function cor(): string
     {
-        return match($this) {
+        return match ($this) {
             Naipe::Copas, Naipe::Ouros => 'Vermelho',
             Naipe::Paus, Naipe::Espadas => 'Preto',
         };
@@ -453,6 +463,7 @@ enum Naipe: string implements Colorido
   <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
+
 interface Colorido
 {
     public function cor(): string;
@@ -469,7 +480,7 @@ final class Naipe implements UnitEnum, Colorido
 
     public function cor(): string
     {
-        return match($this) {
+        return match ($this) {
             Naipe::Copas, Naipe::Ouros => 'Vermelho',
             Naipe::Paus, Naipe::Espadas => 'Preto',
         };
@@ -508,6 +519,7 @@ final class Naipe implements UnitEnum, Colorido
    <programlisting role="php">
 <![CDATA[
 <?php
+
 enum Tamanho
 {
     case Pequeno;
@@ -516,7 +528,7 @@ enum Tamanho
 
     public static function deComprimento(int $cm): self
     {
-        return match(true) {
+        return match (true) {
             $cm < 50 => self::Pequeno,
             $cm < 100 => self::Medio,
             default => self::Grande,
@@ -550,6 +562,7 @@ var_dump(Tamanho::fromLength(50));
    <programlisting role="php">
 <![CDATA[
 <?php
+
 enum Tamanho
 {
     case Pequeno;
@@ -578,14 +591,16 @@ var_dump(Tamanho::Enorme);
    <programlisting role="php">
 <![CDATA[
 <?php
+
 interface Colorido
 {
     public function cor(): string;
 }
 
 trait Retangulo
 {
-    public function forma(): string {
+    public function forma(): string
+    {
         return "Retângulo";
     }
 }
@@ -601,7 +616,7 @@ enum Naipe implements Colorido
 
     public function cor(): string
     {
-        return match($this) {
+        return match ($this) {
             Naipe::Copas, Naipe::Ouros => 'Vermelho',
             Naipe::Paus, Naipe::Espadas => 'Preto',
         };
@@ -636,6 +651,7 @@ var_dump($naipe->forma());
   <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
+
 // Esta é uma definição de enumeração perfeitamente legal.
 enum Direcao implements ArrayAccess
 {
@@ -734,6 +750,7 @@ $foo = new Foo();
   <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
+
 $trevos = new Naipe();
 // Erro: Não é possível instanciar a enumeração Naipe
 
@@ -757,6 +774,7 @@ $ferraduras = (new ReflectionClass(Naipe::class))->newInstanceWithoutConstructor
    <programlisting role="php">
 <![CDATA[
 <?php
+
 enum Naipe
 {
     case Copas;
@@ -796,6 +814,7 @@ var_dump(NaipeApoiado::cases());
    <programlisting role="php">
 <![CDATA[
 <?php
+
 enum Naipe: string
 {
     case Copas = 'C';
@@ -816,6 +835,12 @@ print serialize(Naipe::Copas);
    Na desserialização, se uma enumeração de um caso não pode ser encontrada para combinar com um valor
    serializado, um aviso será emitido e &false; retornado.</para>
 
+  <simpara>
+   A opção <literal>allowed_classes</literal> de
+   <function>unserialize</function> não afeta
+   <link linkend="language.enumerations">Enumerações</link>.
+  </simpara>
+
   <para>
    Se uma Enumeração Pura for serializada para JSON, um erro será lançado. Se uma Enumeração Apoiada
    for serializada para JSON, ela será representada apenas por seu valor escalar, no
@@ -831,11 +856,14 @@ print serialize(Naipe::Copas);
    <programlisting role="php">
 <![CDATA[
 <?php
-enum Foo {
+
+enum Foo
+{
     case Bar;
 }
 
-enum Baz: int {
+enum Baz: int
+{
     case Beep = 5;
 }
 
@@ -868,12 +896,14 @@ Baz Enum:int {
   <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
+
 class A {}
 class B extends A {}
 
 function foo(A $a) {}
 
-function bar(B $b) {
+function bar(B $b)
+{
     foo($b);
 }
 ]]>
@@ -892,7 +922,9 @@ function bar(B $b) {
   <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
-enum ErrorCode {
+
+enum ErrorCode
+{
     case SOMETHING_BROKE;
 }
 
@@ -919,13 +951,16 @@ function quux(ErrorCode $errorCode)
   <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
+
 // Apenas para o exemplo onde enumerações não são finais.
 // Isto *não* funciona no PHP.
-enum MoreErrorCode extends ErrorCode {
+enum MoreErrorCode extends ErrorCode
+{
     case PEBKAC;
 }
 
-function fot(MoreErrorCode $errorCode) {
+function fot(MoreErrorCode $errorCode)
+{
     quux($errorCode);
 }
 
@@ -957,6 +992,7 @@ fot(MoreErrorCode::PEBKAC);
     <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
+
 enum Ordem
 {
     case Asc;
@@ -986,6 +1022,7 @@ function consulta($campos, $filtros, Ordem $ordem = Ordem::Asc)
     <programlisting role="php">
 <![CDATA[
 <?php
+
 enum EstadoDeUsuario: string
 {
     case Pendente = 'P';
@@ -995,7 +1032,7 @@ enum EstadoDeUsuario: string
 
     public function rotulo(): string
     {
-        return match($this) {
+        return match ($this) {
             self::Pendente => 'Pendente',
             self::Ativo => 'Ativo',
             self::Suspenso => 'Suspenso',
@@ -1025,6 +1062,7 @@ var_dump($status->rotulo());
     <programlisting role="php">
 <![CDATA[
 <?php
+
 enum EstadoDeUsuario: string
 {
     case Pendente = 'P';

reference/var/functions/unserialize.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: a9e47cecca7d5834de43b7641baf5d86828bb153 Maintainer: leonardolara Status: ready -->
+<!-- EN-Revision: 8af3521cb43f54c652baaf8dbbcb786b79a5d04e Maintainer: leonardolara Status: ready -->
 <refentry xml:id="function.unserialize" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>unserialize</refname>
@@ -103,6 +103,9 @@
             Omitir esta opção é o mesmo que defini-la como &true;: o PHP
             tentará instanciar objetos de qualquer classe.
            </simpara>
+           <simpara>
+            Esta opção não afeta <link linkend="language.enumerations">Enumerações</link>.
+           </simpara>
           </entry>
          </row>
          <row>
@@ -172,6 +175,13 @@
         de <parameter>options</parameter> não for um <type>array</type> de nomes de classes.
        </entry>
       </row>
+      <row>
+       <entry>8.4.0</entry>
+       <entry>
+        Desserializar strings usando a tag maiúscula <literal>"S"</literal>
+        foi descontinuado; use a tag minúscula <literal>"s"</literal> em vez disso.
+       </entry>
+      </row>
       <row>
        <entry>8.3.0</entry>
        <entry>