sync with en rev

2026-03-23 22:52:12 +01:00 · 2025-03-18 16:27:34 -03:00
parent f6a2803878
commit 6e3a481bf2
7 changed files with 78 additions and 72 deletions
--- a/appendices/migration70/incompatible/error-handling.xml
+++ b/appendices/migration70/incompatible/error-handling.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 22583751fbfdaa3eaa41aeb6470d1343f5cb2c78 Maintainer: leonardolara Status: ready --><!-- CREDITS: fabioluciano,leonardolara -->
+<!-- EN-Revision: 2485376b5b3d6b40e5c0d4e198ab5ff2a142425c Maintainer: leonardolara Status: ready --><!-- CREDITS: fabioluciano,leonardolara -->

 <sect2 xml:id="migration70.incompatible.error-handling">
  <title>Modificações na manipulação de erros e exceções</title>
--- a/language/attributes.xml
+++ b/language/attributes.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 9155d793178b5fcd5131b734cd174fecc34c1ae6 Maintainer: marcosmarcolin Status: ready --><!-- CREDITS: marcosmarcolin, adiel -->
+<!-- EN-Revision: 0f14761ba340c6e49797706ac3f0cf1147d97253 Maintainer: leonardolara Status: ready --><!-- CREDITS: marcosmarcolin, adiel, leonardolara -->
 <chapter xml:id="language.attributes" xmlns="http://docbook.org/ns/docbook">
 <title>Atributos</title>
 <sect1 xml:id="language.attributes.overview">
@@ -7,36 +7,25 @@
  <?phpdoc print-version-for="attributes"?>

  <para>
-   Os atributos oferecem a capacidade de adicionar informações de metadados estruturadas e legíveis por máquina
-   em declarações no código: classes, métodos, funções, parâmetros,
-   propriedades e constantes de classe podem ser o destino de um atributo. Os metadados
-   definidos pelos atributos podem ser inspecionados em tempo de execução usando as
-   <link linkend="book.reflection">APIs
-   Reflection</link>. Os atributos podem, portanto, ser pensados como uma linguagem de configuração
-   incorporada diretamente no código.
+   Os atributos PHP fornecem metadados estruturados e legíveis por máquina para classes, métodos,
+   funções, parâmetros, propriedades e constantes. Eles podem ser inspecionados no momento da execução
+   por meio da <link linkend="book.reflection">API Reflection</link>, permitindo comportamento
+   dinâmico sem modificar o código. Os atributos fornecem uma maneira declarativa de anotar
+   código com metadados.
  </para>
-
  <para>
-   Com atributos, a implementação genérica de um
-   recurso e seu uso concreto em uma aplicação podem ser desacoplados. De certa
-   forma, é comparável a interfaces e suas implementações. Mas onde as
-   interfaces e implementações são sobre código, os atributos são sobre a
-   anotação de informações extras e configuração. As interfaces podem ser
-   implementadas por classes, mas os atributos também podem ser declarados
-   em métodos, funções, parâmetros, propriedades e constantes de classe.
-   Como tal, eles são mais flexíveis do que as interfaces.
+   Atributos permitem o desacoplamento da implementação de um recurso de seu uso. Enquanto
+   interfaces definem estrutura ao impor métodos, atributos fornecem metadados em vários
+   elementos, incluindo métodos, funções, propriedades e constantes. Diferentemente de interfaces,
+   que impõem implementações de métodos, atributos anotam código sem alterar sua estrutura.
  </para>
-
  <para>
-   Um exemplo simples de uso de atributo é converter uma interface
-   que possui métodos opcionais para usar atributos. Vamos assumir uma interface
-   <literal>ActionHandler</literal>
-   que representa uma operação em uma aplicação, onde algumas
-   implementações de um manipulador de ações requerem configuração e outras não. Em vez de exigir que todas as classes
-   que implementam <literal>ActionHandler</literal> implementem
-   um método <literal>setUp()</literal>,
-   um atributo pode ser usado. Um benefício
-   dessa abordagem é que o atributo pode ser usado várias vezes.
+   Atributos podem complementar ou substituir métodos de interface opcionais fornecendo metadados em vez de
+   estrutura imposta. Considere uma interface <literal>ActionHandler</literal> que representa uma
+   operação em um aplicativo. Algumas implementações podem exigir uma etapa de configuração, enquanto outras não.
+   Em vez de forçar todas as classes que implementam <literal>ActionHandler</literal> a definir um
+   método <literal>setUp()</literal>, um atributo pode indicar requisitos de configuração. Essa abordagem
+   aumenta a flexibilidade, permitindo que os atributos sejam aplicados várias vezes quando necessário.
  </para>

  <example>
@@ -112,21 +101,21 @@ executeAction($copyAction);
  <title>Sintaxe de Atributo</title>

  <para>
-   Existem várias partes para a sintaxe de atributos. Primeiro, uma declaração
-   de atributo é sempre incluída com um
-   <literal>#[</literal> inicial e um <literal>]</literal>
-   final correspondente. Dentro, um ou vários atributos são listados,
-   separados por vírgula. O nome do atributo é um nome não qualificado, qualificado ou totalmente qualificado,
-   conforme descrito em <link linkend="language.namespaces.basics">Noções Básicas do Uso de Namespaces</link>.
-   Os argumentos para o atributo são opcionais, mas são colocados entre parênteses <literal>()</literal>.
-   Os argumentos para atributos só podem ser valores literais ou expressões constantes. Tanto a sintaxe de
-   argumentos posicionais quanto a dos argumentos nomeados podem ser usadas.
+   A sintaxe de atributo consiste em vários componentes-chave. Uma declaração de atributo
+   começa com <literal>#[</literal> e termina com
+   <literal>]</literal>. Dentro, um ou mais atributos podem ser listados,
+   separados por vírgulas. O nome do atributo pode ser não qualificado, qualificado,
+   ou totalmente qualificado, conforme descrito em <link linkend="language.namespaces.basics">Usando Namespaces Básicos</link>.
+   Argumentos para o atributo são opcionais e colocados entre parênteses
+   <literal>()</literal>. Argumentos podem ser apenas valores literais ou expressões
+   constantes. Tanto a sintaxe de argumento posicional quanto a de argumento nomeado são suportadas.
  </para>

  <para>
-   Os nomes dos atributos e seus argumentos são resolvidos para uma classe e os argumentos são passados para seu construtor,
-   quando uma instância do atributo é solicitada por meio da API Reflection. Como tal,
-   uma classe deve ser introduzida para cada atributo.
+   Nomes de atributos e seus argumentos são resolvidos para uma classe, e os argumentos
+   são passados para seu construtor quando uma instância do atributo é solicitada
+   por meio da API Reflection. Portanto, é recomendado introduzir uma classe
+   para cada atributo.
  </para>

  <example>
@@ -184,17 +173,19 @@ class AnotherThing
  <title>Lendo Atributos com a API Reflection</title>

  <para>
-   Para acessar atributos de classes, métodos, funções, parâmetros, propriedades e constantes de classe,
-   a API Reflection fornece o método <function>getAttributes</function> em cada um dos objetos
-   Reflection correspondentes. Este método retorna um array de instâncias de <classname>ReflectionAttribute</classname>
-   que podem ser consultadas para o nome do atributo, argumentos e para criar uma instância do atributo representado.
+   Para acessar atributos de classes, métodos, funções, parâmetros, propriedades
+   e constantes de classe, use o método <function>getAttributes</function> fornecido
+   pela API Reflection. Este método retorna um array de instâncias de <classname>ReflectionAttribute</classname>.
+   Essas instâncias podem ser consultadas para o nome do atributo, argumentos e
+   podem ser usadas para instanciar o atributo representado.
  </para>

  <para>
-   Essa separação da representação do atributo refletido da instância real aumenta o controle do programador
-   para lidar com erros relacionados a classes de atributos ausentes, erros de digitação ou argumentos ausentes. Somente após
-   chamar <function>ReflectionAttribute::newInstance</function>, os objetos da classe de atributo são instanciados e a correspondência correta dos argumentos
-   é validada, não antes.
+   Separar a representação do atributo refletido de sua instância real fornece mais
+   controle sobre o tratamento de erros, como classes de atributos ausentes, argumentos digitados incorretamente
+   ou valores ausentes. Objetos da classe de atributo são instanciados somente após chamar
+   <function>ReflectionAttribute::newInstance</function>, garantindo que a validação do argumento
+   ocorra naquele ponto.
  </para>

  <example>
@@ -248,9 +239,9 @@ object(MyAttribute)#3 (1) {
  </example>

  <para>
-   Em vez de iterar todos os atributos na instância de reflexão, apenas aqueles
-   de uma determinada classe de atributo podem ser
-   recuperados passando o nome da classe de atributo pesquisado como argumento.
+   Em vez de iterar sobre todos os atributos na instância de reflexão,
+   você pode recuperar apenas aqueles de uma classe de atributo específica passando
+   o nome da classe de atributo como um argumento.
  </para>

  <example>
@@ -280,9 +271,10 @@ dumpMyAttributeData(new ReflectionClass(Thing::class));
  <title>Declarando Classes de Atributos</title>

  <para>
-   Embora não seja estritamente necessário, é recomendável criar uma classe real para cada atributo.
-   No caso mais simples, apenas uma classe vazia é necessária com o atributo <literal>#[Attribute]</literal> declarado
-   que pode ser importado do namespace global com uma declaração use.
+   É recomendado definir uma classe separada para cada atributo.
+   No caso mais simples, uma classe vazia com a declaração <literal>#[Attribute]</literal>
+   é suficiente. O atributo pode ser importado do namespace global usando uma
+   declaração <literal>use</literal>.
  </para>

  <example>
@@ -305,8 +297,9 @@ class MyAttribute
  </example>

  <para>
-   Para restringir o tipo de declaração ao qual um atributo pode ser atribuído, uma máscara de bits pode ser passada
-   como o primeiro argumento para a declaração <literal>#[Attribute]</literal>.
+   Para restringir os tipos de declarações às quais um atributo pode ser aplicado,
+   passe uma máscara de bits como o primeiro argumento para a declaração
+   <literal>#[Attribute]</literal>.
  </para>

  <example>
@@ -346,8 +339,10 @@ class MyAttribute
  </simplelist>

  <para>
-   Por padrão, um atributo só pode ser usado uma vez por declaração. Se o atributo deve ser repetível nas declarações,
-   ele deve ser especificado como parte da máscara de bits para a declaração <literal>#[Attribute]</literal>.
+    Por padrão, um atributo só pode ser usado uma vez por declaração. Para permitir
+    que um atributo seja repetível, especifique-o na máscara de bits da
+    declaração <literal>#[Attribute]</literal> usando o sinalizador
+    <constant>Attribute::IS_REPEATABLE</constant>.
  </para>

  <example>
--- a/reference/filesystem/functions/is-link.xml
+++ b/reference/filesystem/functions/is-link.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 7c9f1adb4b7d55a7a37b0503ec895412a6ecc656 Maintainer: leonardolara Status: ready --><!-- CREDITS: ae, rarruda, felipe, leonardolara -->
+<!-- EN-Revision: d5f735c7bcbf2ae62a875171b2ec3b9f98c28ee5 Maintainer: leonardolara Status: ready --><!-- CREDITS: ae, rarruda, felipe, leonardolara -->
 <refentry xml:id="function.is-link" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>is_link</refname>
@@ -81,6 +81,7 @@ if (is_link($link)) {
    <member><function>is_dir</function></member>
    <member><function>is_file</function></member>
    <member><function>readlink</function></member>
+    <member><function>symlink</function></member>
   </simplelist>
  </para>
 </refsect1>
--- a/reference/filesystem/functions/symlink.xml
+++ b/reference/filesystem/functions/symlink.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 46a0d3708e3c428ad8fa2e1dd38e4755863dc5c2 Maintainer: leonardolara Status: ready --><!-- CREDITS: rarruda,felipe,leonardolara -->
+<!-- EN-Revision: d5f735c7bcbf2ae62a875171b2ec3b9f98c28ee5 Maintainer: leonardolara Status: ready --><!-- CREDITS: rarruda,felipe,leonardolara -->
 <refentry xml:id="function.symlink" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>symlink</refname>
@@ -85,6 +85,7 @@ echo readlink($link);
  &reftitle.seealso;
  <para>
   <simplelist>
+    <member><function>is_link</function></member>
    <member><function>link</function></member>
    <member><function>readlink</function></member>
    <member><function>linkinfo</function></member>
--- a/reference/gnupg/functions/gnupg-gettrustlist.xml
+++ b/reference/gnupg/functions/gnupg-gettrustlist.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: dc54babb688f72ee5b40cd6240a8d506623f5e10 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
+<!-- EN-Revision: 766fa972bca0f6ea8711f6e27d68278be41db17a Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.gnupg-gettrustlist">
 <refnamediv>
  <refname>gnupg_gettrustlist</refname>
--- a/reference/gnupg/functions/gnupg-import.xml
+++ b/reference/gnupg/functions/gnupg-import.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: dc54babb688f72ee5b40cd6240a8d506623f5e10 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
+<!-- EN-Revision: 766fa972bca0f6ea8711f6e27d68278be41db17a Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.gnupg-import">
 <refnamediv>
  <refname>gnupg_import</refname>
--- a/reference/strings/functions/parse-str.xml
+++ b/reference/strings/functions/parse-str.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: e35fbbaa52702ebf45c5e7284351e136ed67f3bb Maintainer: ae Status: ready --><!-- CREDITS: fernandoc,ae -->
+<!-- EN-Revision: 5d7f95f58f99eb121d25348370ee6146c0442b0c Maintainer: leonardolara Status: ready --><!-- CREDITS: fernandoc,ae,leonardolara -->
 <refentry xml:id="function.parse-str" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>parse_str</refname>
@@ -14,7 +14,7 @@
   <methodparam><type>array</type><parameter role="reference">result</parameter></methodparam>
  </methodsynopsis>
  <para>
-   Interpreta <parameter>string</parameter> como se ela fosse uma query string
+   Interpreta <parameter>string</parameter> como se ela fosse uma string de consulta
   passada via URL e cria variáveis no escopo atual ou no array se
   informado em <parameter>result</parameter>.
  </para>
@@ -28,7 +28,7 @@
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
-       The input string.
+       A string de entrada.
      </para>
     </listitem>
    </varlistentry>
@@ -95,19 +95,19 @@
  &reftitle.examples;
  <para>
   <example>
-    <title>Using <function>parse_str</function></title>
+    <title>Usando <function>parse_str</function></title>
    <programlisting role="php">
 <![CDATA[
 <?php
 $str = "first=value&arr[]=foo+bar&arr[]=baz";

-// Recommended
+// Recomendado
 parse_str($str, $output);
 echo $output['first'];  // value
 echo $output['arr'][0]; // foo bar
 echo $output['arr'][1]; // baz

-// DISCOURAGED
+// DESENCORAJADO
 parse_str($str);
 echo $first;  // value
 echo $arr[0]; // foo bar
@@ -119,11 +119,11 @@ echo $arr[1]; // baz
  </para>
  <para>
   Como variáveis no PHP não podem conter pontos ou espaços em seus nomes,
-   estes são convertidos em underlines. O mesmo se aplica aos nomes de
+   estes são convertidos em sublinhados. O mesmo se aplica aos nomes de
   chaves de array no caso de utilizar esta função com o parâmetro
   <parameter>result</parameter>.
   <example>
-    <title>Name mangling em <function>parse_str</function></title>
+    <title>Confusão de nomes em <function>parse_str</function></title>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -144,13 +144,22 @@ echo $output['My_Value']; // Something

  <note>
   <para>
-    Todas as variáveis criadas, ou os valores informados no array do segundo parâmetro,
+    <function>parse_str()</function> é afetado pela diretiva <link linkend="ini.max-input-vars">max_input_vars</link>.
+    Exceder esse limite emite um <constant>E_WARNING</constant>,
+    e quaisquer variáveis além do limite não são adicionadas ao array de resultados.
+    O padrão é 1000; ajuste <link linkend="ini.max-input-vars">max_input_vars</link> conforme necessário.
+   </para>
+  </note>
+
+  <note>
+   <para>
+    Todas as variáveis criadas ou os valores informados no array do segundo parâmetro,
    já estarão automaticamente convertidos por<function>urldecode</function>.
   </para>
  </note>
  <note>
   <para>
-    Para obter a <literal>QUERY_STRING</literal> em si, vocẽ pode utilizar a variável
+    Para obter a string de consulta (<literal>QUERY_STRING</literal>) em si, vocẽ pode utilizar a variável
    <varname>$_SERVER['QUERY_STRING']</varname>.
    Além disso, leia a seção sobre
    <link linkend="language.variables.external">variáveis de fontes