archived-doc-pt-br/reference/pdo/constants.fetch-modes.xml

<?xml version="1.0" encoding="utf-8"?><!-- EN-Revision: 86d3fb841e0206e2588896ad3c21432333535848 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
<section xmlns="http://docbook.org/ns/docbook" xml:id="pdo.constants.fetch-modes">
 <title>Modos de Busca</title>

 <simpara>
  Consulte as <link linkend="pdo.constants.cursors">constantes de cursores</link> para as
  constantes <literal>PDO::FETCH_ORI_*</literal>.
 </simpara>

 <section xml:id="pdo.fetch-modes.basic" annotations="chunk:false">
  <title>Modos de Busca Básicos</title>
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Modo de Busca</entry>
      <entry>Resumo</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>
       <constant>PDO::FETCH_DEFAULT</constant>
      </entry>
      <entry>
       Especifica que o modo de busca padrão deve ser usado.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_ASSOC</constant>
      </entry>
      <entry>
       Array indexado somente pelo nome da coluna.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_BOTH</constant> (Padrão)
      </entry>
      <entry>
       Array indexado tanto pelo nome quanto pelo número da coluna.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_NAMED</constant>
      </entry>
      <entry>
       Variante de <constant>PDO::FETCH_ASSOC</constant> que retém colunas
       duplicadas.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_NUM</constant>
      </entry>
      <entry>
       Array indexado somente pelo número da coluna.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_COLUMN</constant>
      </entry>
      <entry>
       Uma única coluna.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_KEY_PAIR</constant>
      </entry>
      <entry>
       Pares de chave-valor, indexados pela primeira coluna.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_FUNC</constant>
      </entry>
      <entry>
       Usa uma função para criar o valor de retorno.
       (<methodname>PDOStatement::fetchAll</methodname> somente)
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_OBJ</constant>
      </entry>
      <entry>
       Objeto anônimo (<classname>stdClass</classname>).
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_CLASS</constant>
      </entry>
      <entry>
       Um objeto de uma classe especificada.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </section>

 <section xml:id="pdo.fetch-modes.class-flags" annotations="chunk:false">
  <title>Opções de PDO::FETCH_CLASS</title>

  <simpara>
   Estes modos são usados para implementar opções ao usar
   <constant>PDO::FETCH_CLASS</constant>.
  </simpara>

  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Modo de busca</entry>
      <entry>Resumo</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>
       <constant>PDO::FETCH_CLASSTYPE</constant>
      </entry>
      <entry>
       Usa a primeira coluna como o nome da classe.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_PROPS_LATE</constant>
      </entry>
      <entry>
       Chama o construtor antes de definir as propriedades.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_SERIALIZE</constant>
      </entry>
      <entry>
       Usa dados serializados do PHP. Descontinuado a partir do PHP 8.1.0.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </section>

 <section xml:id="pdo.fetch-modes.single" annotations="chunk:false">
  <title>Modos de resultado único</title>

  <simpara>
   Os modos a seguir não podem ser usados com
   <methodname>PDOStatement::fetchAll</methodname>.
  </simpara>

  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Modo de busca</entry>
      <entry>Resumo</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>
       <constant>PDO::FETCH_BOUND</constant>
      </entry>
      <entry>
       Vincula valores a variáveis especificadas.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_INTO</constant>
      </entry>
      <entry>
       Atualiza um objeto existente.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_LAZY</constant>
      </entry>
      <entry>
       Busca lenta via <classname>PDORow</classname> para acessos como array
       e objetos.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </section>

 <section xml:id="pdo.fetch-modes.grouped" annotations="chunk:false">
  <title>
   Sinalizadores de comportamento especiais para <methodname>PDOStatement::fetchAll</methodname>
  </title>

  <simpara>
   Os seguintes modos especiais para múltiplos resultados funcionam apenas com
   <methodname>PDOStatement::fetchAll</methodname> e não funcionam com alguns outros
   modos de busca. Consulte a documentação completa para obter detalhes.
  </simpara>

  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Modo de busca</entry>
      <entry>Resumo</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>
       <constant>PDO::FETCH_GROUP</constant>
      </entry>
      <entry>
       Os resultados estão agrupados pela primeira coluna.
      </entry>
     </row>
     <row>
      <entry>
       <constant>PDO::FETCH_UNIQUE</constant>
      </entry>
      <entry>
       Os resultados são indexados (exclusivamente) pela primeira coluna.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </section>

 <section xml:id="pdo.fetch-modes.duplicate-names" annotations="chunk:false">
  <title>Tratamento de nomes de colunas duplicados</title>
  <simpara>
   É possível que os resultados contenham várias colunas com o mesmo nome.
   Por exemplo, ao unir duas tabelas que contêm uma coluna com o mesmo
   nome.
  </simpara>
  <simpara>
   Como as estruturas do PHP, como arrays e objetos, não suportam múltiplas chaves
   ou propriedades com o mesmo nome, o array ou objeto retornado
   conterá apenas 1 dos valores com o mesmo nome.
  </simpara>
  <simpara>
   O valor retornado para um determinado nome duplicado deve ser considerado
   indefinido.
  </simpara>
  <simpara>
   Para evitar esse problema, nomeie as colunas explicitamente usando um sinônimo. Por exemplo:
  </simpara>
  <informalexample>
   <programlisting role="sql">
<![CDATA[
SELECT table1.created_at AS t1_created_at,
       table2.created_at AS t2_created_at
FROM table1
JOIN table2 ON table1.table2id = table2.id
]]>
   </programlisting>
  </informalexample>
  <simpara>
   Consulte também <constant>PDO::FETCH_NAMED</constant>,
   <constant>PDO::ATTR_FETCH_TABLE_NAMES</constant> e
   <constant>PDO::ATTR_FETCH_CATALOG_NAMES</constant>.
  </simpara>
 </section>

 <section xml:id="pdo.fetch-modes.default" annotations="chunk:false">
  <title>Definindo o modo de busca padrão </title>
  <simpara>
   É possível definir o modo de busca padrão para todas as consultas usando
   <constant>PDO::ATTR_DEFAULT_FETCH_MODE</constant> com
   <methodname>PDO::__construct</methodname> ou
   <methodname>PDO::setAttribute</methodname>.
  </simpara>
  <simpara>
   É possível definir o modo de busca padrão para uma instrução específica usando
   <methodname>PDOStatement::setFetchMode</methodname>.
   Isso afeta a reutilização como uma instrução preparada e a iteração (usando
   &foreach;).
  </simpara>
  <caution>
   <simpara>
    <methodname>PDOStatement::setAttribute</methodname> não pode ser usado para definir o
    modo de busca padrão. Ele aceita apenas atributos específicos do driver e ignora silenciosamente
    os atributos que não são reconhecidos.
   </simpara>
  </caution>
 </section>

 <section xml:id="pdo.constants.fetch-default" annotations="chunk:false">
  <title>PDO::FETCH_DEFAULT (<type>int</type>)</title>
  <simpara>
   Disponível a partir do PHP 8.0.7.
  </simpara>
  <simpara>
   Este é um valor especial que usa o modo de busca padrão atual para um
   <classname>PDOStatement</classname>. É particularmente útil como o valor padrão
   para parâmetros de método ao estender
   <classname>PDOStatement</classname> para uso com
   <constant>PDO::ATTR_STATEMENT_CLASS</constant>.
  </simpara>
  <para>
   Este valor não pode ser usado com
   <constant>PDO::ATTR_DEFAULT_FETCH_MODE</constant>.
  </para>
 </section>

 <section xml:id="pdo.constants.fetch-assoc" annotations="chunk:false">
  <title>PDO::FETCH_ASSOC (<type>int</type>)</title>
  <simpara>
   <constant>PDO::FETCH_ASSOC</constant> retorna um array indexado apenas pelo nome da
   coluna.
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query("SELECT userid, name, country FROM users");
$row = $stmt->fetch(\PDO::FETCH_ASSOC);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [userid] => 104
    [name] => Chris
    [country] => Ukraine
)
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-both" annotations="chunk:false">
  <title>PDO::FETCH_BOTH (<type>int</type>)</title>
  <simpara>
   Este é o modo de busca padrão.
  </simpara>
  <simpara>
   <constant>PDO::FETCH_BOTH</constant> retorna uma matriz indexada tanto pelo número da coluna quanto pelo nome.
   Isso significa que cada valor retornado é duplicado para cada
   linha de resultado.
  </simpara>
  <simpara>
   O número da coluna começa em 0 e é determinado pela ordem da coluna de resultado na
   consulta, não (por exemplo) pela ordem em que as colunas são definidas na tabela.
  </simpara>
  <note>
   <simpara>
    Não é recomendável usar o índice numérico de coluna, pois ele pode mudar quando
    a consulta for alterada ou quando o esquema da tabela for alterado ao usar
    <literal>SELECT *</literal>.
   </simpara>
  </note>
  <note>
   <simpara>
    O número de entradas indexadas por nome pode não corresponder ao número de entradas
    indexadas por número nos casos em que várias colunas retornadas usam o mesmo
    nome.
   </simpara>
  </note>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query("SELECT userid, name, country FROM users");
$row = $stmt->fetch(\PDO::FETCH_BOTH);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [id] => 104,
    [0] => 104,
    [name] => Chris,
    [1] => Chris,
    [country] => Ukraine,
    [2] => Ukraine
)
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-named" annotations="chunk:false">
  <title>PDO::FETCH_NAMED (<type>int</type>)</title>
  <simpara>
   <constant>PDO::FETCH_NAMED</constant> retorna resultados no mesmo formato que
   <constant>PDO::FETCH_ASSOC</constant> exceto que, quando várias colunas usam
   o mesmo nome, todos os valores são retornados como uma lista.
  </simpara>
  <simpara>
   Para obter mais informações sobre o tratamento de nomes de colunas duplicados e alternativas,
   consulte a seção <link linkend="pdo.fetch-modes.duplicate-names">tratamento de
   nomes duplicados</link> acima.
  </simpara>
  <simpara>
   A ordem em que os valores duplicados são retornados deve ser considerada
   indefinida. Não há como saber de onde cada valor veio.
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query(
    "SELECT users.*, referrer.name
     FROM users
     LEFT JOIN users AS referrer ON users.referred_by = referrer.userid
     WHERE userid = 109"
);
$row = $stmt->fetch(\PDO::FETCH_NUM);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [userid] => 109
    [name] => Array
        (
            [0] => Toni
            [1] => Chris
        )
    [country] => Germany
    [referred_by] = 104
)
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-num" annotations="chunk:false">
  <title>PDO::FETCH_NUM (<type>int</type>)</title>
  <simpara>
   <constant>PDO::FETCH_NUM</constant> retorna um array indexado apenas pelo número da coluna.
   O número da coluna começa em 0 e é determinado pela ordem da coluna de resultado na
   consulta, não (por exemplo) pela ordem em que as colunas são definidas na tabela.
  </simpara>
  <note>
   <simpara>
    Não é recomendável usar o índice de coluna numérica, pois ele pode mudar quando
    a consulta for alterada ou quando o esquema da tabela for alterado ao usar
    <literal>SELECT *</literal>.
   </simpara>
  </note>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query("SELECT userid, name, country FROM users");
$row = $stmt->fetch(\PDO::FETCH_NUM);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [0] => 104
    [1] => Chris
    [2] => Ukraine
)
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-column" annotations="chunk:false">
  <title>PDO::FETCH_COLUMN (<type>int</type>)</title>
  <simpara>
   <constant>PDO::FETCH_COLUMN</constant> retorna valores de uma única coluna.
   Use o segundo argumento de <methodname>PDOStatement::setFetchMode</methodname>
   ou <methodname>PDOStatement::fetchAll</methodname> para especificar qual coluna será
   retornada.
  </simpara>
  <simpara>
   Se a coluna especificada não existir, será lançado um
   <classname>ValueError</classname>.
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_COLUMN);
print_r($row);

$stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_COLUMN, 1);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [0] => Chris
    [1] => Jamie
    [2] => Robin
)

Array
(
    [0] => Ukraine
    [1] => England
    [2] => Germany
)
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-key-pair" annotations="chunk:false">
  <title>PDO::FETCH_KEY_PAIR (<type>int</type>)</title>
  <simpara>
   <constant>PDO::FETCH_KEY_PAIR</constant> retorna pares de valores, indexados pela
   primeira coluna. Os resultados devem conter apenas 2 colunas. Este modo de busca
   só faz sentido com <methodname>PDOStatement::fetchAll</methodname>.
  </simpara>
  <note>
   <simpara>
    Se a primeira coluna não for única, valores serão perdidos.
    Quais valores serão perdidos devem ser considerados indefinidos.
   </simpara>
  </note>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_KEY_PAIR);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [Chris] => Ukraine
    [Jamie] => England
    [Robin] => Germany
)
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-func" annotations="chunk:false">
  <title>PDO::FETCH_FUNC (<type>int</type>)</title>
  <simpara>
   Especifique uma função para criar o valor retornado. Este modo só pode ser usado
   com <methodname>PDOStatement::fetchAll</methodname>.
  </simpara>
  <simpara>
   A função recebe os valores como parâmetros.
   Não há como recuperar o nome da coluna à qual um determinado valor estava associado.
   É crucial garantir que a ordem das colunas na consulta corresponda à
   esperada pela função.
  </simpara>
  <note>
   <simpara>
    Os efeitos de <constant>PDO::FETCH_GROUP</constant> e
    <constant>PDO::FETCH_UNIQUE</constant> são aplicados aos resultados antes da
    função ser chamada.
   </simpara>
  </note>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
function valueCreator($col1, $col2, $col3)
{
    return [
        'col1' => $col1,
        'col2' => strtoupper($col2),
        'col3' => $col3,
        'customKey' => 'customValue',
    ];
}

$stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_FUNC, valueCreator(...));
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [0] => Array
        (
            [col1] => 104
            [col2] => SAM
            [col3] => Ukraine
            [customKey] => customValue
        )

    [1] => Array
        (
            [col1] => 105
            [col2] => JAMIE
            [col3] => England
            [customKey] => customValue
        )

    [2] => Array
        (
            [col1] => 107
            [col2] => ROBIN
            [col3] => Germany
            [customKey] => customValue
        )

)
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-obj" annotations="chunk:false">
  <title>PDO::FETCH_OBJ (<type>int</type>)</title>
  <simpara>
   <constant>PDO::FETCH_OBJ</constant> retorna um objeto
   <classname>stdClass</classname>.
  </simpara>
  <simpara>
   Consulte também <methodname>PDOStatement::fetchObject</methodname> e
   <constant>PDO::FETCH_CLASS</constant>.
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query("SELECT userid, name, country FROM users");
$row = $stmt->fetch(\PDO::FETCH_OBJ);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
stdClass Object
(
    [userid] => 104
    [name] => Chris
    [country] => Ukraine
)
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-class" annotations="chunk:false">
  <title>PDO::FETCH_CLASS (<type>int</type>)</title>
  <simpara>
   Retorna um objeto de uma classe especificada. Para comportamentos adicionais, consulte os sinalizadores de opções:
   <link linkend="pdo.fetch-modes.class-flags">sinalizadores de opções</link>.
  </simpara>
  <simpara>
   Se uma propriedade com o nome de uma coluna retornada não existir, ela será
   declarada dinamicamente. Esse comportamento foi descontinuado e causará um erro
   a partir do PHP 9.0.
  </simpara>
  <simpara>
   Consulte também <methodname>PDOStatement::fetchObject</methodname>.
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
class TestEntity
{
    public $userid;

    public $name;

    public $country;

    public $referred_by_userid;

    public function __construct()
    {
        print "Construtor chamado com ". count(func_get_args()) ." argumentos\n";
        print "Propriedades definidas quando o construtor foi chamado? "
            . (isset($this->name) ? 'Sim' : 'Não') . "\n";
    }
}

$stmt = $db->query(
    "SELECT userid, name, country, referred_by_userid FROM users"
);
$stmt->setFetchMode(PDO::FETCH_CLASS, TestEntity::class);
$result = $stmt->fetch();
var_dump($result);
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
Construtor chamado com 0 argumentoss
Propriedades definidas quando o construtor foi chamado? Sim
object(TestEntity)#3 (4) {
  ["userid"]=>
  int(104)
  ["name"]=>
  string(5) "Chris"
  ["country"]=>
  string(7) "Ukraine"
  ["referred_by_userid"]=>
  NULL
}
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-classtype" annotations="chunk:false">
  <title>PDO::FETCH_CLASSTYPE (<type>int</type>)</title>
  <simpara>
   Este modo de busca só pode ser usado em combinação com
   <constant>PDO::FETCH_CLASS</constant> (e
   <link linkend="pdo.fetch-modes.class-flags">suas outras opções</link>).
  </simpara>
  <simpara>
   Quando este modo de busca é usado, o PDO usará a primeira coluna retornada como o
   nome da classe a ser retornada.
  </simpara>
  <simpara>
   Se a classe especificada não for encontrada, um objeto <classname>stdClass</classname>
   será retornado, sem aviso ou erro.
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
class TestEntity
{
    public $userid;

    public $name;

    public $country;

    public $referred_by_userid;

    public function __construct()
    {
        print "Construtor chamado com ". count(func_get_args()) ." argumentos\n";
        print "Propriedades definidas quando o construtor foi chamado? "
            . (isset($this->name) ? 'Sim' : 'Não') . "\n";
    }
}

$stmt = $db->query(
    "SELECT 'TestEntity', userid, name, country, referred_by_userid FROM users"
);
$stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE);
$result = $stmt->fetch();
var_dump($result);
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
Construtor chamado com 0 argumentos
Propriedades definidas quando o construtor foi chamado? Sim
object(TestEntity)#3 (4) {
  ["userid"]=>
  int(104)
  ["name"]=>
  string(5) "Chris"
  ["country"]=>
  string(7) "Ukraine"
  ["referred_by_userid"]=>
  NULL
}
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-props-late" annotations="chunk:false">
  <title>PDO::FETCH_PROPS_LATE (<type>int</type>)</title>
  <simpara>
   Este modo de busca só pode ser usado em combinação com
   <constant>PDO::FETCH_CLASS</constant> (e
   <link linkend="pdo.fetch-modes.class-flags">suas outras opções</link>).
  </simpara>
  <simpara>
   Quando este modo de busca é usado, o construtor será chamado antes que as
   propriedades sejam definidas.
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
class TestEntity
{
    public $userid;

    public $name;

    public $country;

    public $referred_by_userid;

    public function __construct()
    {
        print "Construtor chamado com ". count(func_get_args()) ." argumentos\n";
        print "Propriedades definidas quando o construtor foi chamado? "
            . (isset($this->name) ? 'Sim' : 'Não') . "\n";
    }
}

$stmt = $db->query(
    "SELECT userid, name, country, referred_by_userid FROM users"
);
$stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, TestEntity::class);
$result = $stmt->fetch();
var_dump($result);
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
Construtor chamado com 0 argumentos
Propriedades definidas quando o construtor foi chamado? Não
object(TestEntity)#3 (4) {
  ["userid"]=>
  int(104)
  ["name"]=>
  string(5) "Chris"
  ["country"]=>
  string(7) "Ukraine"
  ["referred_by_userid"]=>
  NULL
}
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-serialize" annotations="chunk:false">
  <title>PDO::FETCH_SERIALIZE (<type>int</type>)</title>
  &warn.deprecated.feature-8-1-0;
  <simpara>
   Este modo de busca só pode ser usado em combinação com
   <constant>PDO::FETCH_CLASS</constant> (e
   <link linkend="pdo.fetch-modes.class-flags">suas outras opções</link>).
  </simpara>
  <simpara>
   Quando este modo de busca é utilizado, a classe especificada deve ser
   <interfacename>Serializable</interfacename>.
  </simpara>
  <caution>
   <simpara>
    Este recurso não suporta uma string que contenha um objeto serializado completo
    (com <function>serialize</function>).
   </simpara>
  </caution>
  <caution>
   <simpara>
    Este modo de busca não chama o construtor.
   </simpara>
  </caution>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
class TestEntity implements Serializable
{
    public $userid;

    public $name;

    public $country;

    public $referred_by_userid;

    public function __construct()
    {
        print "Construtor chamado com " . count(func_get_args()) . " argumentos\n";
        print "Propriedades definidas quando o construtor é chamado? "
            . (isset($this->name) ? 'Sim' : 'Não') . "\n";
    }

    public function serialize()
    {
        return join(
            "|",
            [$this->userid, $this->name, $this->country, $this->referred_by_userid]
        );
    }

    public function unserialize(string $data)
    {
        $parts = explode("|", $data);
        $this->userid = (int) $parts[0];
        $this->name = $parts[1];
        $this->country = $parts[2];

        $refId = $parts[3];
        $this->referred_by_userid = ($refId === "" ? null : (int) $refId);
    }
}

print "Definindo o registro (construtor chamado manualmente):\n";
$db->exec(
    "CREATE TABLE serialize (
        sdata TEXT
    )"
);

$origObj = new TestEntity();
$origObj->userid = 200;
$origObj->name = 'Seri';
$origObj->country = 'Syria';
$origObj->referred_by_userid = null;

$insert = $db->prepare("INSERT INTO serialize (sdata) VALUES (:sdata)");
$insert->execute(['sdata' => $origObj->serialize()]);

print "\nRecuperando o resultado:\n";
$query = "SELECT sdata FROM serialize";
$stmt = $db->query($query);
// NOTA: O construtor nunca é chamado!
$stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_SERIALIZE, TestEntity::class);
$result = $stmt->fetch();
var_dump($result);
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
Deprecated: TestEntity implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in Standard input code on line 2
Definindo o registro (construtor chamado manualmente):
Construtor chamado com 0 argumentos
Propriedades definidas quando o construtor é chamado? Não

Recuperando o resultado:
Deprecated: PDOStatement::setFetchMode(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 58

Deprecated: PDOStatement::fetch(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 59
object(TestEntity)#5 (4) {
  ["userid"]=>
  int(200)
  ["name"]=>
  string(4) "Seri"
  ["country"]=>
  string(5) "Syria"
  ["referred_by_userid"]=>
  NULL
}
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-bound" annotations="chunk:false">
  <title>PDO::FETCH_BOUND (<type>int</type>)</title>
  <simpara>
   Este modo de busca não pode ser usado com
   <methodname>PDOStatement::fetchAll</methodname>.
  </simpara>
  <simpara>
   Este modo de busca não retorna um resultado diretamente, mas associa valores a
   variáveis ​​especificadas com <methodname>PDOStatement::bindColumn</methodname>. O
   método de busca chamado retorna &true;.
  </simpara>
  <note>
   <simpara>
    Ao usar instruções preparadas, para funcionar corretamente, as variáveis ​​devem ser vinculadas
    após a execução da consulta.
   </simpara>
  </note>
  <programlisting role="php">
<![CDATA[
<?php
$query = "SELECT users.userid, users.name, users.country, referrer.name
    FROM users
    LEFT JOIN users AS referrer ON users.referred_by_userid = referrer.userid";
$stmt = $db->prepare($query);
$stmt->execute();

$stmt->bindColumn('userid', $userId);
$stmt->bindColumn('name', $name);
$stmt->bindColumn('country', $country);
// Vincule pela posição da coluna para resolver nomes de coluna duplicados
// Para evitar que isso cause problemas se a consulta for alterada, use um sinônimo SQL.
// Por exemplo: referrer.name AS referrer_name
$stmt->bindColumn(4, $referrerName);

while ($stmt->fetch(\PDO::FETCH_BOUND)) {
    print join("\t", [$userId, $name, $country, ($referrerName ?? 'NULL')]) . "\n";
}
]]>
  </programlisting>
  &example.outputs;
  <screen>
<![CDATA[
104	Chris	Ukraine	NULL
105	Jamie	England	NULL
107	Robin	Germany	Chris
108	Sean	Ukraine	NULL
109	Toni	Germany	NULL
110	Toni	Germany	NULL
]]>
  </screen>
 </section>

 <section xml:id="pdo.constants.fetch-into" annotations="chunk:false">
  <title>PDO::FETCH_INTO (<type>int</type>)</title>
  <simpara>
   Este modo de busca não pode ser usado com
   <methodname>PDOStatement::fetchAll</methodname>.
  </simpara>
  <simpara>
   Este modo de busca atualiza as propriedades do objeto especificado. O objeto é
   retornado em caso de sucesso.
  </simpara>
  <simpara>
   Se uma propriedade com o nome de uma coluna retornada não existir, ela será
   declarada dinamicamente. Esse comportamento está obsoleto e causará um erro
   a partir do PHP 9.0.
  </simpara>
  <simpara>
   Propriedades precisam ser <literal>public</literal> e não podem ser
   <literal>readonly</literal>.
  </simpara>
  <caution>
   <simpara>
    Não há como alterar o objeto a ser atualizado sem usar
    <methodname>PDOStatement::setFetchMode</methodname> entre a recuperação de cada
    registro.
   </simpara>
  </caution>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
class TestEntity
{
    public $userid;

    public $name;

    public $country;

    public $referred_by_userid;
}

$obj = new TestEntity();
$stmt->setFetchMode(\PDO::FETCH_INTO, $obj);

$stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
$result = $stmt->fetch();
var_dump($result);
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
object(TestEntity)#3 (4) {
  ["userid"]=>
  int(104)
  ["name"]=>
  string(5) "Chris"
  ["country"]=>
  string(7) "Ukraine"
  ["referred_by_userid"]=>
  NULL
}
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-lazy" annotations="chunk:false">
  <title>PDO::FETCH_LAZY (<type>int</type>)</title>
  <simpara>
   Este modo de busca não pode ser usado com
   <methodname>PDOStatement::fetchAll</methodname>.
  </simpara>
  <simpara>
   Este modo de busca retorna um objeto <classname>PDORow</classname> que fornece
   acesso a valores tanto no formato de array quanto no formato de objeto (ou seja, combina o comportamento de
   <constant>PDO::FETCH_BOTH</constant> e
   <constant>PDO::FETCH_OBJ</constant>), recuperados de forma lenta.
  </simpara>
  <simpara>
   Isso pode fornecer acesso eficiente em termos de memória (no lado do PHP) a resultados não armazenados em buffer
   no servidor de banco de dados. Se o PDO usa buffer no lado do cliente para resultados
   depende do driver específico do banco de dados usado (e de sua configuração).
  </simpara>
  <caution>
   <simpara>
    <classname>PDORow</classname> retornará <literal>NULL</literal> sem
    qualquer erro ou aviso ao acessar propriedades ou chaves que não estejam definidas.
    Isso pode dificultar a detecção e depuração de erros como erros de digitação ou consultas
    que não retornam os dados esperados.
   </simpara>
  </caution>
  <caution>
   <simpara>
    O objeto <classname>PDORow</classname> retornado é atualizado cada vez que um
    resultado é recuperado.
   </simpara>
  </caution>
  <programlisting role="php">
<![CDATA[
<?php
$stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
$result = $stmt->fetch(\PDO::FETCH_LAZY);

print "ID: ". $result[0] ."\n";
print "Nome: {$result->name}\n";
print "País: " . $result['country'] ."\n";
// Retorna NULL. Nenhum aviso ou erro é emitido.
print "Não existe: " . var_export($result->does_not_exist, true) . "\n";

$differentResult = $stmt->fetch(\PDO::FETCH_LAZY);
// O PDORow recuperado anteriormente agora aponta para o resultado recém-recuperado.
print "ID: ". $result[0] ."\n";

]]>
  </programlisting>
  &example.outputs;
  <screen>
<![CDATA[
ID: 104
Nome: Chris
País: Ukraine
Não existe: NULL
ID: 105
]]>
  </screen>
 </section>

 <section xml:id="pdo.constants.fetch-group" annotations="chunk:false">
  <title>PDO::FETCH_GROUP (<type>int</type>)</title>
  <simpara>
   <constant>PDO::FETCH_GROUP</constant> retorna listas de arrays associativos,
   indexados por uma coluna (não única). Este modo de busca funciona apenas com
   <methodname>PDOStatement::fetchAll</methodname>.
  </simpara>
  <simpara>
   Quando combinado com <constant>PDO::FETCH_UNIQUE</constant>, ambos os modos
   usarão a mesma coluna, tornando a combinação desses modos inútil.
  </simpara>
  <simpara>
   Esta busca deve ser combinada com uma das seguintes constantes:
   <constant>PDO::FETCH_ASSOC</constant>, <constant>PDO::FETCH_BOTH</constant>,
   <constant>PDO::FETCH_NAMED</constant>, <constant>PDO::FETCH_NUM</constant>,
   <constant>PDO::FETCH_COLUMN</constant> ou
   <constant>PDO::FETCH_FUNC</constant>.
  </simpara>
  <simpara>
   Se nenhum modo de busca da lista acima for fornecido, o modo de busca padrão atual
   para o <classname>PDOStatement</classname> será usado.
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query("SELECT country, userid, name FROM users");
$row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [Ukraine] => Array
        (
            [0] => Array
                (
                    [userid] => 104
                    [name] => Chris
                )

            [1] => Array
                (
                    [userid] => 108
                    [name] => Sean
                )

        )
    [England] => Array
        (
            [0] => Array
                (
                    [userid] => 105
                    [name] => Jamie
                )

        )

    [Germany] => Array
        (
            [0] => Array
                (
                    [userid] => 107
                    [name] => Robin
                )

            [1] => Array
                (
                    [userid] => 109
                    [name] => Toni
                )
        )
)
]]>
   </screen>
  </informalexample>
  <simpara>
   No exemplo acima, pode ser observado que a primeira coluna é omitida do
   array de cada linha, estando disponível apenas como chave. Ela pode ser incluída
   repetindo a coluna, como no exemplo a seguir:
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query("SELECT country, userid, name, country FROM users");
$row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [Ukraine] => Array
        (
            [0] => Array
                (
                    [userid] => 104
                    [name] => Chris
                    [country] => Ukraine
                )

            [1] => Array
                (
                    [userid] => 108
                    [name] => Sean
                    [country] => Ukraine
                )

        )
    [England] => Array
        (
            [0] => Array
                (
                    [userid] => 105
                    [name] => Jamie
                    [country] => England
                )

        )

    [Germany] => Array
        (
            [0] => Array
                (
                    [userid] => 107
                    [name] => Robin
                    [country] => Germany
                )

            [1] => Array
                (
                    [userid] => 109
                    [name] => Toni
                    [country] => Germany
                )
        )
)
]]>
   </screen>
  </informalexample>
 </section>

 <section xml:id="pdo.constants.fetch-unique" annotations="chunk:false">
  <title>PDO::FETCH_UNIQUE (<type>int</type>)</title>
  <simpara>
   <constant>PDO::FETCH_UNIQUE</constant> usa a primeira coluna para indexar registros,
   retornando 1 registro por valor de índice. Este modo de busca funciona apenas com
   <methodname>PDOStatement::fetchAll</methodname>.
  </simpara>
  <simpara>
   Quando combinado com <constant>PDO::FETCH_GROUP</constant>, ambos os modos usarão
   a mesma coluna, tornando a combinação desses modos inútil.
  </simpara>
  <simpara>
   Esta busca deve ser combinada com uma das seguintes constantes
   <constant>PDO::FETCH_ASSOC</constant>, <constant>PDO::FETCH_BOTH</constant>,
   <constant>PDO::FETCH_NAMED</constant>, <constant>PDO::FETCH_NUM</constant>,
   <constant>PDO::FETCH_COLUMN</constant> ou
   <constant>PDO::FETCH_FUNC</constant>.
  </simpara>
  <simpara>
   Se nenhum modo de busca da lista acima for fornecido, o modo de busca padrão atual
   para o <classname>PDOStatement</classname> será usado.
  </simpara>
  <simpara>
   Quando usado com uma coluna que se sabe ser única (como o ID do registro), este
   modo oferece a capacidade de retornar rapidamente resultados indexados por esse valor.
  </simpara>
  <note>
   <simpara>
    Se a primeira coluna não for única, valores serão perdidos.
    Quais valores serão perdidos devem ser considerados indefinidos.
   </simpara>
  </note>
  <caution>
   <simpara>
    A filtragem de registros deve ser feita em SQL sempre que possível.
    O banco de dados usará índices para otimizar esse processo e retornar apenas os registros necessários.
    Selecionar mais registros do que o necessário do banco de dados pode aumentar significativamente o
    uso de memória e o tempo de consulta para conjuntos de resultados maiores.
   </simpara>
  </caution>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [104] => Array
        (
            [name] => Chris
            [country] => Ukraine
        )

    [105] => Array
        (
            [name] => Jamie
            [country] => England
        )

    [107] => Array
        (
            [name] => Robin
            [country] => Germany
        )

)
]]>
   </screen>
  </informalexample>
  <simpara>
   No exemplo acima, pode ser observado que a primeira coluna é omitida do
   array de cada linha, estando disponível apenas como chave. Ela pode ser incluída
   repetindo a coluna, como no exemplo a seguir:
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$stmt = $pdo->query("SELECT userid, userid, name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
print_r($row);
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Array
(
    [104] => Array
        (
            [userid] => 104
            [name] => Chris
            [country] => Ukraine
        )

    [105] => Array
        (
            [userid] => 105
            [name] => Jamie
            [country] => England
        )

    [107] => Array
        (
            [userid] => 107
            [name] => Robin
            [country] => Germany
        )

)
]]>
   </screen>
  </informalexample>
 </section>

</section>
<!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-omittag:t
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
 sgml-indent-step:1
 sgml-indent-data:t
 indent-tabs-mode:nil
 sgml-parent-document:nil
 sgml-default-dtd-file:"~/.phpdoc/manual.ced"
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
 vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->