sync with en rev

php · Nov 26, 2024 · 4606099 · 4606099
1 parent 6f1751a
commit 4606099
Show file tree

Hide file tree

Showing 8 changed files with 181 additions and 81 deletions.
diff --git a/install/composer.xml b/install/composer.xml
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: 23e2d505107219b10945c677c9b14ab0237d1886 Maintainer: leonardolara Status: ready -->
+
+<chapter xml:id="install.composer" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="chunk:false">
+ <title>Instalação do Composer e pacotes de terceiros</title>
+
+ <sect1 xml:id="install.composer.intro">
+  <title>Introdução ao Composer</title>
+  <simpara>
+   &link.composer; é um gerenciador de dependências para o PHP que torna possível
+   definir pacotes de códigos de terceiros usados por um projeto que pode
+   então ser facilmente instalado e atualizado. Ele aproveita os
+   <link linkend="language.oop5.autoload">recursos de carregamento automático de classe</link>
+   do PHP, repositórios de pacotes PHP como
+   <link xlink:href="&url.packagist;">Packagist</link> e convenções comuns
+   de layout e codificação de projetos.
+  </simpara>
+  <simpara>
+   Por exemplo, se uma aplicação ou página em PHP precisa
+   trabalhar com valores <abbrev>UUID</abbrev>,
+   <link xlink:href="&url.packagist.package;ramsey/uuid">o pacote
+   <literal>ramsey/uuid</literal> de Ben Ramsey</link>, que implementa os
+   tipos de UUID amplamente conhecidos que são definidos pela
+   <link xlink:href="&url.rfc;4122">RFC 4122</link>, poderia ser usado.
+  </simpara>
+  <simpara>
+   Resumidamente, isto é feito criando um arquivo <literal>composer.json</literal>
+   no projeto, usando o Composer para instalar a última versão do
+   pacote, e incluindo o script de autocarregamento do Composer para torná-lo disponível
+   ao código. A <link xlink:href="&url.composer;/doc/01-basic-usage.md">documentação de
+   "Uso Básico" do Composer</link> entra em mais detalhes sobre isso.
+  </simpara>
+  <example>
+   <title>
+    <literal>composer.json</literal> que requer um único pacote
+   </title>
+   <programlisting role="javascript">
+<![CDATA[
+{
+    "require": {
+        "ramsey/uuid": "^4.7"
+    }
+}
+]]>
+   </programlisting>
+  </example>
+
+ </sect1>
+</chapter>
diff --git a/language/oop5/autoload.xml b/language/oop5/autoload.xml
@@ -1,27 +1,27 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: ce3a2d381693ccbc10cc4a808c3eb853f3c85c9e Maintainer: lhsazevedo Status: ready --><!-- CREDITS: felipe, amandavale, machado, fabioluciano, lhsazevedo -->
+<!-- EN-Revision: 7befd9af043386158ef9080723eb18e03f0625c7 Maintainer: leonardolara Status: ready --><!-- CREDITS: felipe, amandavale, machado, fabioluciano, lhsazevedo, leonardolara -->
  <sect1 xml:id="language.oop5.autoload" xmlns="http://docbook.org/ns/docbook">
-  <title>Autoloading Classes</title>
+  <title>Autocarregamento de Classes</title>
   <para>
-   Muitos desenvolvedores ao desenvolver aplicações orientadas a objeto criam
+   Muitos programadores, ao desenvolver aplicações orientadas a objeto, criam
    um arquivo PHP para cada definição de classe. Um dos maiores contratempos é
-   ter de escrever uma longa lista de includes no início de cada script(um
+   ter de escrever uma longa lista de "includes" no início de cada script (um
    para cada classe).
   </para>
   <para>
-   A função <function>spl_autoload_register</function>  registra qualquer número de
-   autoloaders, permitindo que classes e interfaces sejam automaticamente carregadas
-   se elas não ainda não foram definidas. Ao registrar autoloaders, o PHP têm uma última chance
+   A função <function>spl_autoload_register</function> registra qualquer número de
+   autocarregadores, permitindo que classes e interfaces sejam automaticamente carregadas
+   se elas não ainda não tiverem sido definidas. Ao registrar autocarregadores, o PHP tem uma última chance
    de carregar classes e interfaces antes que falhem com um erro.
   </para>
   <para>
-   Qualquer construto tipo classe pode ser automaticamente carregado do mesmo jeito. Isso inclui classes,
-   interfaces, traits, and enumerações.
+   Qualquer construção semelhante a uma classe pode ser carregada automaticamente da mesma maneira. Isso inclui classes,
+   interfaces, traits e enumerações.
   </para>
   <caution>
    <para>
-    Antes do PHP 8.0.0. era possível usar <function>__autoload</function>
-    para fazer autoload de classes and interfaces. No entanto, ela é uma alternativa menos
+    Antes do PHP 8.0.0, era possível usar <function>__autoload</function>
+    para fazer autocarregamento de classes and interfaces. No entanto, ela é uma alternativa menos
     flexível a <function>spl_autoload_register</function> e
     <function>__autoload</function> está descontinuada a partir do PHP 7.2.0, e removida
     a partir do PHP 8.0.0.
@@ -30,19 +30,19 @@
   <note>
    <para>
     <function>spl_autoload_register</function> pode ser chamada várias vezes para
-    registrar múltiplos autoloaders. No entando, lançar uma exceção em uma função de autoload
-    interromperá esse processo e não permitirá que outras funções de autoload sejam
-    executadas. Por esse motivo, o lançamento de exceções em funções de autoload é altamente
+    registrar múltiplos autocarregadores. No entando, lançar uma exceção em uma função de autocarregamento
+    interromperá esse processo e não permitirá que outras funções de autocarregamento sejam
+    executadas. Por esse motivo, o lançamento de exceções em funções de autocarregamento é altamente
     desencorajado.
    </para>
   </note>
   <para>
    <example>
-    <title>Exemplo de Autoload</title>
+    <title>Exemplo de autocarregamento</title>
     <para>
      Esse exemplo tenta carregar as classes <literal>MyClass1</literal>
      e <literal>MyClass2</literal> dos arquivos <filename>MyClass1.php</filename>
-     e <filename>MyClass2.php</filename> respectivamente.
+     e <filename>MyClass2.php</filename>, respectivamente.
     </para>
     <programlisting role="php">
 <![CDATA[
@@ -58,7 +58,7 @@ $obj2 = new MyClass2();
     </programlisting>
    </example>
    <example>
-    <title>Outro exemplo de Autoload</title>
+    <title>Outro exemplo de autocarregamento</title>
     <para>
      Este exemplo tenta carregar a interface <literal>ITest</literal>.
     </para>
@@ -79,6 +79,26 @@ string(5) "ITest"
 Fatal error: Interface 'ITest' not found in ...
 */
 ?>
+]]>
+    </programlisting>
+   </example>
+   <example>
+    <title>Usando o autocarregador do Composer</title>
+    <simpara>
+     &link.composer; gera um <literal>vendor/autoload.php</literal>
+     que é configurado para carregar automaticamente pacotes gerenciados
+     pelo Composer. Ao incluir este arquivo, esses pacotes podem ser usados sem
+     nenhum trabalho adicional.
+    </simpara>
+    <programlisting role="php">
+<![CDATA[
+<?php
+require __DIR__ . '/vendor/autoload.php';
+
+$uuid = new Ramsey\Uuid\Uuid::uuid7();
+
+echo "Gerado novo UUID -> ", $uuid->toString(), "\n";
+?>
 ]]>
     </programlisting>
    </example>

diff --git a/language/oop5/interfaces.xml b/language/oop5/interfaces.xml
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 2e7c00fd314a708ecbd495ef7cc9ae8c8462c33c Maintainer: ae Status: ready --><!-- CREDITS: felipe,narigone,fabioluciano,ae,leonardolara -->
+<!-- EN-Revision: 0c2a0d736df56dd0f3a1b88bd6ce7c975c38285a Maintainer: ae Status: ready --><!-- CREDITS: felipe,narigone,fabioluciano,ae,leonardolara -->
  <sect1 xml:id="language.oop5.interfaces" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
   <title>Interfaces de Objetos</title>
   <para>
    Interfaces de objetos permitem a criação de códigos que especificam quais métodos e propriedades
    uma classe deve implementar, sem definir como esses métodos ou propriedades serão
-   implementados. Interfaces compartilham o namespace com classes e traits, então eles
+   implementados. Interfaces compartilham um namespace com classes, traits e enumerações, por isso eles
    não podem usar os mesmos nomes.
   </para>
   <para>
@@ -154,15 +154,19 @@ class C2 implements I
     // Este exemplo cria uma propriedade virtual, o que é aceitável.
     public string $writeable {
         get => $this->written;
-        set => $value;
+        set {
+            $this->written = $value;
+        }
     }
 
     // Esta propriedade exige que tanto a leitura quanto a gravação
     // sejam possíveis, portanto, precisamos implementar ambas ou
     // permitir que ela tenha o comportamento padrão.
     public string $both {
         get => $this->all;
-        set => strtoupper($value);
+        set {
+            $this->all = strtoupper($value);
+        }
     }
 }
 ?>

diff --git a/language/oop5/visibility.xml b/language/oop5/visibility.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 7d7b378abd302430b8ce7cedb4b78c7033f5e88c Maintainer: ae Status: ready --><!-- CREDITS: narigone,felipe,ae,fabioluciano,leonardolara -->
+<!-- EN-Revision: bda37a3a4dd7934642918455408d36b664e43a27 Maintainer: ae Status: ready --><!-- CREDITS: narigone,felipe,ae,fabioluciano,leonardolara -->
  <sect1 xml:id="language.oop5.visibility" xmlns="http://docbook.org/ns/docbook">
   <title>Visibilidade</title>
   <para>
@@ -164,6 +164,13 @@ $b->pubYear = 2023; // Erro fatal
       </simpara>
      </listitem>
     </itemizedlist>
+    <note>
+     <simpara>
+      Espaços não são permitidos na declaração de visibilidade "set".
+      <literal>private(set)</literal> está correto.
+      <literal>private( set )</literal> não está correto e resultará em erro de análise.
+     </simpara>
+    </note>
     <simpara>
      Quando uma classe estende outra, a classe filha pode redefinir
      qualquer propriedade que não seja <literal>final</literal>. Ao fazer isso,

diff --git a/reference/bc/functions/bcdiv.xml b/reference/bc/functions/bcdiv.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 1fafa3d9998bf7359b4edf39fcf49056b2006c1c Maintainer: ae Status: ready --><!-- CREDITS: rarruda,ae,leonardolara -->
+<!-- EN-Revision: 87f32875a189be7ee2a8487c0db3958579e4ce72 Maintainer: ae Status: ready --><!-- CREDITS: rarruda,ae,leonardolara -->
 <refentry xml:id="function.bcdiv" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>bcdiv</refname>
@@ -115,6 +115,8 @@ echo bcdiv('105', '6.55957', 3);  // 16.007
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>bcdivmod</function></member>
+    <member><function>bcmod</function></member>
     <member><function>bcmul</function></member>
    </simplelist>
   </para>

diff --git a/reference/bc/functions/bcmod.xml b/reference/bc/functions/bcmod.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 1fafa3d9998bf7359b4edf39fcf49056b2006c1c Maintainer: ae Status: ready --><!-- CREDITS: rarruda, leonardolara -->
+<!-- EN-Revision: 87f32875a189be7ee2a8487c0db3958579e4ce72 Maintainer: ae Status: ready --><!-- CREDITS: rarruda, leonardolara -->
 <refentry xml:id="function.bcmod" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>bcmod</refname>
@@ -146,6 +146,7 @@ echo bcmod('5.7', '1.3'); // 0.5 no PHP 7.2.0; anteriormente 0
   <para>
    <simplelist>
     <member><function>bcdiv</function></member>
+    <member><function>bcdivmod</function></member>
    </simplelist>
   </para>
  </refsect1>

diff --git a/reference/filter/ini.xml b/reference/filter/ini.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: aa471e2d84786f7d82cfb8969b2b924f17319e61 Maintainer: ae Status: ready --><!-- CREDITS: felipe, ae -->
+<!-- EN-Revision: 55e2079a87f9ec40eff85deb666fbab44d525386 Maintainer: ae Status: ready --><!-- CREDITS: felipe, ae, leonardolara -->
 <section xml:id="filter.configuration" xmlns="http://docbook.org/ns/docbook">
  &reftitle.runtime;
  &extension.runtime;
@@ -32,11 +32,10 @@
    </tgroup>
   </table>
   &ini.php.constants;
-</para>
+ </para>
 
-&ini.descriptions.title;
+ &ini.descriptions.title;
 
-<para>
  <variablelist>
   <varlistentry xml:id="ini.filter.default">
    <term>
@@ -51,29 +50,32 @@
      A informação original pode ser acessada através da <function>filter_input</function>.
     </para>
     <para>
-     Aceita o nome do filtro que você quer usar por padrão. Veja a
-     <link linkend="filter.filters">filter list</link> existentes na
-     lista de nomes de filtros.
+     Deve ser o nome de um filtro que pode ser determinado através de
+     <function>filter_list</function> e <function>filter_id</function>.
     </para>
     <note>
-      <para>
-        Cuidado com os valores padrão dos filtros. Você deve explicitamente
-        informar quais deseja. Por exemplo, para configurar o filtro padrão para
-        para se comportar exatamente como <function>htmlspecialchars</function> você deve configurar
-        o falgs para 0 como mostrado abaixo.
-      </para>
-      <para>
-        <example>
-          <title>Configurando o filtro padrão para agir como htmlspecialchars</title>
-          <programlisting role="php">
+     <simpara>
+      Cuidado com as opções padrão para os filtros padrão.
+      Eles devem ser definidos explicitamente.
+      Por exemplo, para configurar o filtro padrão para se comportar exatamente como
+      <function>htmlspecialchars</function>, as opções padrão devem ser definidas para
+      <literal>0</literal> como mostrado no exemplo abaixo.
+     </simpara>
+     <example>
+      <title>Configurando o filtro padrão para agir como htmlspecialchars</title>
+      <programlisting role="php">
 <![CDATA[
 filter.default = full_special_chars
 filter.default_flags = 0
 ]]>
-          </programlisting>
-        </example>
-      </para>
-   </note>
+      </programlisting>
+     </example>
+    </note>
+    <warning>
+     <simpara>
+      Esta configuração INI está descontinuada a partir do PHP 8.1.0.
+     </simpara>
+    </warning>
    </listitem>
   </varlistentry>
 
@@ -83,19 +85,17 @@ filter.default_flags = 0
     <type>int</type>
    </term>
    <listitem>
-    <para>
-     Flags padrão a serem aplicados ao filtro padrão. Inicialmente configurado para
-     <constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant> por padrão para compatibilidade reversa.
-     Veja a <link linkend="filter.filters.flags">lista de flags</link>
-     para uma listagem dos nomes das flags.
-    </para>
+    <simpara>
+     Opções padrão a serem aplicados quando o filtro padrão está definido.
+     É definido como <constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant>
+     por padrão para compatibilidade com versões anteriores.
+     Consulte as constantes <constant>FILTER_FLAG_<replaceable>*</replaceable></constant>
+     para conhecer as opções disponíveis.
+    </simpara>
    </listitem>
   </varlistentry>
-
  </variablelist>
- </para>
 </section>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml