Updates to references (pgsql and session) (#419)

2026-03-23 22:52:12 +01:00 · 2023-12-12 11:16:55 -03:00
parent 4e93d90015
commit b456075ac6
10 changed files with 1215 additions and 702 deletions
--- a/reference/pgsql/book.xml
+++ b/reference/pgsql/book.xml
@@ -1,29 +1,32 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: af4410a7e15898c3dbe83d6ea38246745ed9c6fb Maintainer: felipe Status: ready --><!-- CREDITS: lucasr -->
- 
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: c2eca73ef79ebe78cebb34053e41b565af504c4f Maintainer: leonardolara Status: ready --><!-- CREDITS: lucasr,felipe,leonardolara -->
+
 <book xml:id="book.pgsql" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <?phpdoc extension-membership="bundledexternal" ?>
 <title>PostgreSQL</title>
- 
+
 <!-- {{{ preface -->
 <preface xml:id="intro.pgsql">
  &reftitle.intro;
  <para>
   O banco de dados PostgreSQL é um produto de código aberto e disponível
   gratuitamente. O Postgres, desenvolvido originalmente no Departamento de Ciência
-   de Computação da Universidade de Berkeley, foi pioneiro em muitos dos conceitos
-   objeto-relacionais que agora estão disponíveis em
-   alguns bancos de dados comerciais. Fornece suporte a linguagem
-   SQL92/SQL99, integridade de transações e extensibilidade de tipos.
-   O PostgreSQL é um descendente com código aberto do código original
-   desenvolvido em Berkeley.
+   da Computação da Universidade da Califórnia em Berkeley, foi pioneiro em muitos dos conceitos
+   objeto-relacionais que agora estão disponíveis em alguns bancos de dados comerciais. Fornece
+   suporte à linguagem SQL92/SQL99, transações, integridade referencial,
+   procedimentos armazenados e extensibilidade de tipos. O PostgreSQL é um descendente de código aberto
+   do original desenvolvido em Berkeley.
  </para>
 </preface>
 <!-- }}} -->
- 
+
 &reference.pgsql.setup;
 &reference.pgsql.constants;
 &reference.pgsql.examples;
 &reference.pgsql.reference;
+ &reference.pgsql.pgsql.connection;
+ &reference.pgsql.pgsql.result;
+ &reference.pgsql.pgsql.lob;

 </book>

--- a/reference/pgsql/constants.xml
+++ b/reference/pgsql/constants.xml
--- a/reference/pgsql/examples.xml
+++ b/reference/pgsql/examples.xml
@@ -1,26 +1,27 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: af4410a7e15898c3dbe83d6ea38246745ed9c6fb Maintainer: felipe Status: ready -->
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: cffb5f52894aa8a29109e3802e2257c56b51bcb6 Maintainer: leonardolara Status: ready --><!-- CREDITS: felipe,leonardolara -->

 <chapter xml:id="pgsql.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.examples;
 <section xml:id="pgsql.examples-basic">
+  <title>Uso básico</title>
  <para>
-   Este simples exemple mostra como conectar, executar uma query, mostrar
-   linhas de resultado e desconectar de um banco de dados PostgreSQL.
+   Este exemplo simples mostra como conectar, executar uma consulta, mostrar
+   linhas de resultados e desconectar de um banco de dados PostgreSQL.
   <example>
-    <title>Exemplo de visão geral da extensão PostgreSQL</title>
+    <title>Exemplo geral da extensão PostgreSQL</title>
    <programlisting role="php">
 <![CDATA[
 <?php
-// Connecting, selecting database
+// Connectando, selectionando o banco
 $dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
    or die('Could not connect: ' . pg_last_error());

-// Performing SQL query
+// Executando consulta SQL
 $query = 'SELECT * FROM authors';
 $result = pg_query($query) or die('Query failed: ' . pg_last_error());

-// Printing results in HTML
+// Mostrando resultados em HTML
 echo "<table>\n";
 while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
    echo "\t<tr>\n";
@@ -31,12 +32,86 @@ while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
 }
 echo "</table>\n";

-// Free resultset
+// Liberando o conjunto de resultados
 pg_free_result($result);

-// Closing connection
+// Fechando a conexão
 pg_close($dbconn);
 ?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </section>
+
+ <section xml:id="pgsql.examples-queries">
+  <title>Basic usage</title>
+  <para>
+   Estes exemplos contêm funções definidas pelo usuário similares às funções legadas
+   do MySQL.
+
+   <example>
+    <title>Exemplo de funções definidas pelo usuário no PostgreSQL</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Este função deve ser necessária, já que o a conexão PostgreSQL vincula o banco de dados.
+function pg_list_dbs($db)
+{
+    assert(is_resource($db));
+    $query = '
+SELECT
+ d.datname as "Name",
+ u.usename as "Owner",
+ pg_encoding_to_char(d.encoding) as "Encoding"
+FROM
+ pg_database d LEFT JOIN pg_user u ON d.datdba = u.usesysid
+ORDER BY 1;
+';
+    return pg_query($db, $query);
+}
+
+// Lista tabelas.
+function pg_list_tables($db)
+{
+    assert(is_resource($db));
+    $query = "
+SELECT
+ c.relname as \"Name\",
+ CASE c.relkind WHEN 'r' THEN 'table' WHEN 'v' THEN 'view' WHEN 'i' THEN 'index' WHEN 'S' THEN 'sequence' WHEN 's' THEN 'special' END as \"Type\",
+  u.usename as \"Owner\"
+FROM
+ pg_class c LEFT JOIN pg_user u ON c.relowner = u.usesysid
+WHERE
+ c.relkind IN ('r','v','S','')
+ AND c.relname !~ '^pg_'
+ORDER BY 1;
+";
+    return pg_query($db, $query);
+}
+
+// Veja também pg_meta_data(). Ela retorna definições de campo em um array.
+function pg_list_fields($db, $table)
+{
+    assert(is_resource($db));
+    $query = "
+SELECT
+ a.attname,
+ format_type(a.atttypid, a.atttypmod),
+ a.attnotnull,
+ a.atthasdef,
+ a.attnum
+FROM
+ pg_class c,
+ pg_attribute a
+WHERE
+ c.relname = '".$table."'
+ AND a.attnum > 0 AND a.attrelid = c.oid
+ORDER BY a.attnum;
+";
+    return pg_query($db, $query);
+}
+?>
 ]]>
    </programlisting>
   </example>
@@ -45,7 +120,7 @@ pg_close($dbconn);
 </chapter>

 <!-- Keep this comment at the end of the file
-Local variables: 
+Local variables:
 mode: sgml
 sgml-omittag:t
 sgml-shorttag:t
--- a/reference/pgsql/reference.xml
+++ b/reference/pgsql/reference.xml
@@ -1,12 +1,12 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: felipe Status: ready --><!-- CREDITS: lucasr -->
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: 3ba581880a9e5635109c65cef01a7ca192999ad1 Maintainer: leonardolara Status: ready --><!-- CREDITS: lucasr,felipe,leonardolara -->

 <reference xml:id="ref.pgsql" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
- <title>PostgreSQL &Functions;</title>
+ <title>&Functions; PostgreSQL</title>

 <partintro>
  <section xml:id="pgsql.notes">
-  &reftitle.notes;
+   &reftitle.notes;
   <note>
    <para>
     Nem todas as funções são suportadas por todas as compilações. Isso vai
@@ -14,10 +14,10 @@
     como esta foi compilada. Se há alguma função ausente, é porque a libpq não
     suporta a característica exigida por esta função.
    </para>
-   </note>  
+   </note>
   <note>
    <para>
-     Muitas funções do PostgreSQL aceitam <parameter>connection</parameter> como
+     A maioria das funções do PostgreSQL aceita <parameter>connection</parameter> como
     o primeiro parâmetro opcional. Se ele não é fornecido, a última conexão
     aberta é usada. Se não existir, a função retorna &false;.
    </para>
@@ -25,7 +25,7 @@
   <note>
    <para>
     PostgreSQL automaticamente converte todos identificadores (e.g. nomes de tabela/coluna)
-     para minúsculo na criação do objeto e na query. 
+     para minúsculo na criação do objeto e na query.
     Para força o uso misto de maiúsculo ou minúsculo, você precisa usar escape
     no identificador usando aspas dupla ("").
    </para>
@@ -36,7 +36,7 @@
     banco de dados (dicionário de dados) (eg. todas as tabelas do banco de dados
     atual). Ao invés, há um schema padrão chamado <literal>information_schema</literal> no
     PostgreSQL 7.4 e superior contendo views do sistema com todas as informações
-     necessárias, em um form fácil de acessá-las. Veja a <link 
+     necessárias, em um form fácil de acessá-las. Veja a <link
     xlink:href="&url.pgsql.manual;">Documentação do PostgreSQL</link>
     para maiores detalhes.
    </para>
@@ -44,12 +44,12 @@
  </section>
 </partintro>

-&reference.pgsql.entities.functions;
+ &reference.pgsql.entities.functions;

 </reference>

 <!-- Keep this comment at the end of the file
-Local variables: 
+Local variables:
 mode: sgml
 sgml-omittag:t
 sgml-shorttag:t
--- a/reference/pgsql/setup.xml
+++ b/reference/pgsql/setup.xml
@@ -1,5 +1,5 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- EN-Revision: af4410a7e15898c3dbe83d6ea38246745ed9c6fb Maintainer: felipe Status: ready --><!-- CREDITS: lucasr -->
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: c2eca73ef79ebe78cebb34053e41b565af504c4f Maintainer: leonardolara Status: ready --><!-- CREDITS: lucasr,felipe,leonardolara -->

 <chapter xml:id="pgsql.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.setup;
@@ -31,9 +31,9 @@
 <section xml:id="pgsql.resources">
  &reftitle.resources;
  <para>
-   Há dois tipos de resource usados no módulo PostgreSQL. O primeiro
-   é o identificador do link para a conexão com o banco de dados, o segundo um
-   resource que guarda o resultado de uma query.
+   Antes do PHP 8.1.0, havia dois tipos de recurso usados no módulo PostgreSQL. O primeiro
+   é o identificador de conexão com o banco de dados, o segundo um
+   recurso que guarda o resultado de uma consulta.
  </para>
 </section>
 <!-- }}} -->
--- a/reference/session/book.xml
+++ b/reference/session/book.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 60fc9f497ab530fa78abe1f12aa664d8cd5bbe95 Maintainer: felipe Status: ready --><!-- CREDITS: fernandoc, marcosmarcolin -->
+<!-- EN-Revision: ba6a83ca3558574695be5ef0a0e008e4e5f78ddb Maintainer: leonardolara Status: ready --><!-- CREDITS: fernandoc, marcosmarcolin, felipe, leonardolara -->

 <book xml:id="book.session" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <?phpdoc extension-membership="bundled" ?>
@@ -53,22 +53,21 @@
    ser armazenadas em sessão.
   </para>
   <para>
-     Manipuladores de serialização (<literal>php</literal>
-     e <literal>php_binary</literal>) herdam as limitações de
-     register_globals. Portanto, índices numéricos ou strings contendo
-     caracteres especiais (<literal>|</literal>
-     e <literal>!</literal>) não podem ser usados. Se usados, resultará em
-     erros na finalização do script. <literal>php_serialize</literal>
-     não possui tais limitações.
+    Manipuladores de serialização (<literal>php</literal>
+    e <literal>php_binary</literal>) herdam as limitações de
+    register_globals. Portanto, índices numéricos ou strings contendo
+    caracteres especiais (<literal>|</literal>
+    e <literal>!</literal>) não podem ser usados. Se usados, resultará em
+    erros na finalização do script. <literal>php_serialize</literal>
+    não possui tais limitações.
   </para>
  </warning>
  <note>
   <para>
-    Por favor, note que ao trabalhar com sessões, um registro na sessão
-    não é criado até que a variável seja registrada usando a função
-    <function>session_register</function> ou pela adição de uma nova
+    Por favor, note que ao trabalhar com sessões, um registro de uma sessão
+    não é criado até que uma variável tenha sindo registrada pela adição de uma nova
    chave ao array super global <varname>$_SESSION</varname>. Isto
-    continua valendo mesmo se uma sessão foi iniciada usando a função
+    continua valendo mesmo se uma sessão tenha sido iniciada usando a função
    <function>session_start</function>.
   </para>
  </note>
--- a/reference/session/configure.xml
+++ b/reference/session/configure.xml
@@ -1,13 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: fernandoc Status: ready --><!-- CREDITS: surfmax -->
+<!-- EN-Revision: a7d56396b4b04d83871e084371cd6c6fecdafaa8 Maintainer: leonardolara Status: ready --><!-- CREDITS: surfmax,fernandoc,leonardolara -->
 <section xml:id="session.installation" xmlns="http://docbook.org/ns/docbook">
 &reftitle.install;
 <para>
-  Suporte à sessão está habilitado no PHP por padrão. Se você preferir
-  compilar o PHP sem suporte à sessão, você deve
-  especificar a opção <option role="configure">--disable-session</option>
-  para o script configure. Para usar alocação de memória compartilhada (mm) para armazenamento
-  de sessão especifique a opção <option role="configure">--with-mm[=DIR] </option>.
+  &installation.enabled.disable;
+  <option role="configure">--disable-session</option>
+ </para>
+ <para>
+  Para usar alocação de memória compartilhada (mm) para armazenamento de sessão, configure o PHP com
+  <option role="configure">--with-mm[=DIR]</option>.
 </para>
 &windows.builtin;
 <note>
@@ -16,13 +17,13 @@
   um arquivo no diretório especificado pela configuração INI session.save_path.
   Um arquivo para cada sessão (independente se alguma informação está associada com
   esta sessão) será criado. Isto é devido ao fato de que uma sessão
-   é aberta (um arquivo é criado) mas até então nenhum dado é escrito neste arquivo.
-   Note que este comportamento é um efeito colateral das limitações de trabalhar
-   com o sistema de arquivo e é possível que um manipulador de sessão personalizado
-   (como um que utilize banco de dados) não mantenha registros das sessões
-   que não contém dados.
+   é aberta (um arquivo é criado) mas nenhum dado é escrito neste arquivo.
+   Note que este comportamento é um efeito colateral das limitações de se trabalhar
+   com o sistema de arquivos e é possível que um manipulador de sessão personalizado
+   (como um que utilize banco de dados) não mantenha registros de sessões
+   que não armazenem dados.
  </para>
- </note> 
+ </note>
 </section>

 <!-- Keep this comment at the end of the file
--- a/reference/session/security.xml
+++ b/reference/session/security.xml
--- a/reference/session/sessionhandler.xml
+++ b/reference/session/sessionhandler.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 601f6f4ce5827d441a7e110184708f0abe9fd447 Maintainer: none Status: ready --><!-- CREDITS: marcosmarcolin -->
+<!-- EN-Revision: 14767af0f05dffa6fdb9b49e1a1f4e9ca7022a60 Maintainer: leonardolara Status: ready --><!-- CREDITS: marcosmarcolin,leonardolara -->
 <phpdoc:classref xml:id="class.sessionhandler" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">

 <title>A classe SessionHandler</title>
@@ -61,24 +61,19 @@
   &reftitle.classsynopsis;

 <!-- {{{ Synopsis -->
-   <classsynopsis>
+   <classsynopsis class="class">
    <ooclass>
     <classname>SessionHandler</classname>
    </ooclass>

-    <classsynopsisinfo>
-     <ooclass>
-      <classname>SessionHandler</classname>
-     </ooclass>
+    <oointerface>
+     <modifier>implements</modifier>
+     <interfacename>SessionHandlerInterface</interfacename>
+    </oointerface>

-     <oointerface>
-      <interfacename>SessionHandlerInterface</interfacename>
-     </oointerface>
-
-     <oointerface>
-      <interfacename>SessionIdInterface</interfacename>
-     </oointerface>
-    </classsynopsisinfo>
+    <oointerface>
+     <interfacename>SessionIdInterface</interfacename>
+    </oointerface>

    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.sessionhandler')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='SessionHandler'])">
@@ -120,7 +115,7 @@ function decrypt($edata, $password) {
    $salt = substr($data, 0, 16);
    $ct = substr($data, 16);

-    $rounds = 3; // depends on key length
+    $rounds = 3; // depende do comprimento da chave
    $data00 = $password.$salt;
    $hash = array();
    $hash[0] = hash('sha256', $data00, true);
@@ -143,15 +138,15 @@ function decrypt($edata, $password) {
 * @return base64 encrypted data
 */
 function encrypt($data, $password) {
-    // Generate a cryptographically secure random salt using random_bytes()
+    // Gera um salt aleatório criptograficamente seguro usando random_bytes()
    $salt = random_bytes(16);

    $salted = '';
    $dx = '';
-    // Salt the key(32) and iv(16) = 48
+    // Salt em key(32) e iv(16) = 48
    while (strlen($salted) < 48) {
-      $dx = hash('sha256', $dx.$password.$salt, true);
-      $salted .= $dx;
+        $dx = hash('sha256', $dx.$password.$salt, true);
+        $salted .= $dx;
    }

    $key = substr($salted, 0, 32);
--- a/reference/session/sessionhandlerinterface.xml
+++ b/reference/session/sessionhandlerinterface.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 6e69d9342ef5b124a62c8a255cb0d9a091d07b5e Maintainer: none Status: ready --><!-- CREDITS: marcosmarcolin -->
+<!-- EN-Revision: 9eb4a46bba05da229be4c8f7a3cb64702e1a2f95 Maintainer: leonardolara Status: ready --><!-- CREDITS: marcosmarcolin, leonardolara -->
 <phpdoc:classref xml:id="class.sessionhandlerinterface" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">

 <title>A classe SessionHandlerInterface</title>
@@ -11,10 +11,10 @@
  <section xml:id="sessionhandlerinterface.intro">
   &reftitle.intro;
   <para>
-    <classname>SessionHandlerInterface</classname> é uma interface que define o mínimo
-    protótipo para criar um manipulador de sessão personalizado. Para passar um
+    <classname>SessionHandlerInterface</classname> é uma interface que define o protótipo
+    mínimo para criar um manipulador de sessão personalizado. Para passar um
    manipulador de sessão personalizado para <function>session_set_save_handler</function> usando
-    invocação <literal>Orientada à Objetos</literal>, a classe deve implementar esta interface.
+    invocação <abbrev>OOP</abbrev> (Orientada à Objetos), a classe deve implementar esta interface.
   </para>
   <para>
    Note que os métodos de callbacks desta classe são projetos para serem chamados internamente pelo
@@ -27,16 +27,10 @@
   &reftitle.interfacesynopsis;

 <!-- {{{ Synopsis -->
-   <classsynopsis>
-    <ooclass>
-     <classname>SessionHandlerInterface</classname>
-    </ooclass>
-
-    <classsynopsisinfo>
-     <oointerface>
-      <interfacename>SessionHandlerInterface</interfacename>
-     </oointerface>
-    </classsynopsisinfo>
+   <classsynopsis class="interface">
+    <oointerface>
+     <interfacename>SessionHandlerInterface</interfacename>
+    </oointerface>

    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.sessionhandlerinterface')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='SessionHandlerInterface'])">