PDOStatement::fetchAll

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetchAll Recupera las líneas restantes de un conjunto de resultados

Descripción

public PDOStatement::fetchAll(int $mode = PDO::FETCH_DEFAULT): array
public PDOStatement::fetchAll(int $mode = PDO::FETCH_COLUMN, int $column): array
public PDOStatement::fetchAll(int $mode = PDO::FETCH_CLASS, string $class, ?array $constructorArgs): array
public PDOStatement::fetchAll(int $mode = PDO::FETCH_FUNC, callable $callback): array

Parámetros

mode

Controla el contenido del array retornado como se documenta en la función PDOStatement::fetch(). Valor por omisión: PDO::ATTR_DEFAULT_FETCH_MODE (que toma su valor por omisión de PDO::FETCH_BOTH).

Para retornar un array que contenga todos los valores de una sola columna desde el conjunto de resultados, se especifica PDO::FETCH_COLUMN. Puede especificarse qué columna se desea con el argumento column.

Para indexar el array resultante por el valor de una cierta columna (en lugar de por números consecutivos), se coloca el nombre de esta columna en primer lugar en la lista de columnas en SQL, y se utiliza PDO::FETCH_UNIQUE. Esta columna debe contener únicamente valores únicos, de lo contrario se perderán algunos datos.

Para agrupar los resultados en forma de un array de tres dimensiones indexado por los valores de una columna especificada, se coloca el nombre de esta columna en primer lugar en la lista de columnas en SQL y se utiliza PDO::FETCH_GROUP.

Para agrupar los resultados en forma de un array de dos dimensiones, se utiliza un OU a nivel de bits con PDO::FETCH_GROUP y PDO::FETCH_COLUMN. Los resultados serán agrupados por la primera columna, el valor del elemento del array siendo una lista de entradas correspondientes de la segunda columna.

Los argumentos siguientes son dinámicos y dependen del modo de recuperación. No pueden ser utilizados con argumentos nombrados.
column

Utilizado con PDO::FETCH_COLUMN. Retorna la columna indicada indexada a 0.

class

Utilizado con PDO::FETCH_CLASS. Retorna instancias de la clase especificada, haciendo corresponder las columnas de cada línea a propiedades nombradas en la clase.

constructorArgs

Argumentos del constructor personalizado de la clase cuando el argumento mode es PDO::FETCH_CLASS.

callback

Utilizado con PDO::FETCH_FUNC. Retorna los resultados de la llamada de la función especificada, utilizando las columnas de cada línea como argumentos en la llamada.

Valores devueltos

PDOStatement::fetchAll() retorna un array que contiene todas las líneas del conjunto de registros. El array representa cada línea como un array de valores de las columnas, o un objeto con propiedades correspondientes a cada nombre de columna. Un array vacío es retornado si no hay resultados.

El uso de este método para recuperar grandes conjuntos de resultados puede aumentar el uso de recursos del sistema, pero también estos recursos. En lugar de recuperar todas las datos y manipularlas con PHP, se utiliza el servidor de base de datos para manipular los conjuntos de resultados. Por ejemplo, se utilizan las cláusulas WHERE y ORDER BY en las consultas SQL para restringir los resultados antes de recuperarlos y procesarlos con PHP.

Errores/Excepciones

Emits an error with level E_WARNING if the attribute PDO::ATTR_ERRMODE is set to PDO::ERRMODE_WARNING.

Throws a PDOException if the attribute PDO::ATTR_ERRMODE is set to PDO::ERRMODE_EXCEPTION.

Historial de cambios

Versión Descripción
8.0.0 Este método retorna ahora siempre un tableau, anteriormente false podía ser retornado en caso de fallo.

Ejemplos

Ejemplo #1 Recuperación de todas las líneas de un conjunto de resultados

<?php
$sth
= $dbh->prepare("SELECT nom, couleur FROM fruit");
$sth->execute();

/* Recuperación de todas las líneas de un conjunto de resultados */
print "Recuperación de todas las líneas de un conjunto de resultados :\n";
$result = $sth->fetchAll();
print_r($result);
?>

El resultado del ejemplo sería algo similar a:

Recuperación de todas las líneas de un conjunto de resultados :
Array
(
    [0] => Array
        (
            [nom] => apple
            [0] => apple
            [couleur] => red
            [1] => red
        )

    [1] => Array
        (
            [nom] => pear
            [0] => pear
            [couleur] => green
            [1] => green
        )

    [2] => Array
        (
            [nom] => watermelon
            [0] => watermelon
            [couleur] => pink
            [1] => pink
        )

)

Ejemplo #2 Recuperación de todos los valores de una sola columna desde un conjunto de resultados

El siguiente ejemplo muestra cómo retornar todos los valores de una sola columna desde un conjunto de resultados, incluso si la consulta SQL retorna varias columnas por líneas.

<?php
$sth
= $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

/* Recuperación de todos los valores de la primera columna */
$result = $sth->fetchAll(PDO::FETCH_COLUMN, 0);
var_dump($result);
?>

El resultado del ejemplo sería algo similar a:

Array(3)
(
    [0] =>
    string(5) => apple
    [1] =>
    string(4) => pear
    [2] =>
    string(10) => watermelon
)

Ejemplo #3 Agrupar todos los valores de una sola columna

El siguiente ejemplo muestra cómo retornar un array asociativo agrupado por los valores de la columna especificada de un conjunto de resultados. El array contiene tres claves: los valores apple y pear son retornados en forma de arrays que contienen dos colores diferentes, mientras que watermelon es retornado en forma de un array que contiene únicamente un solo color.

<?php
$insert
= $dbh->prepare("INSERT INTO fruit(name, colour) VALUES (?, ?)");
$insert->execute(array('apple', 'green'));
$insert->execute(array('pear', 'yellow'));

$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

/* Agrupar los valores de la primera columna */
var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP));
?>

El resultado del ejemplo sería algo similar a:

array(3) {
  ["apple"]=>
    array(2) {
      [0]=>
        string(5) "green"
      [1]=>
        string(3) "red"
    }
  ["pear"]=>
    array(2) {
      [0]=>
        string(5) "green"
      [1]=>
        string(6) "yellow"
    }
  ["watermelon"]=>
    array(1) {
      [0]=>
        string(5) "pink"
    }
}

Ejemplo #4 Instanciar una clase para cada resultado

El siguiente ejemplo muestra el comportamiento de PDO::FETCH_CLASS.

<?php
class fruit {
public
$name;
public
$colour;
}

$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

$result = $sth->fetchAll(PDO::FETCH_CLASS, "fruit");
var_dump($result);
?>

El resultado del ejemplo sería algo similar a:

array(3) {
  [0]=>
  object(fruit)#1 (2) {
    ["name"]=>
    string(5) "apple"
    ["colour"]=>
    string(5) "green"
  }
  [1]=>
  object(fruit)#2 (2) {
    ["name"]=>
    string(4) "pear"
    ["colour"]=>
    string(6) "yellow"
  }
  [2]=>
  object(fruit)#3 (2) {
    ["name"]=>
    string(10) "watermelon"
    ["colour"]=>
    string(4) "pink"
  }
  [3]=>
  object(fruit)#4 (2) {
    ["name"]=>
    string(5) "apple"
    ["colour"]=>
    string(3) "red"
  }
  [4]=>
  object(fruit)#5 (2) {
    ["name"]=>
    string(4) "pear"
    ["colour"]=>
    string(5) "green"
  }
}

Ejemplo #5 Llamada de una función para cada resultado

El siguiente ejemplo muestra el comportamiento de PDO::FETCH_FUNC.

<?php
function fruit($name, $colour) {
return
"{$name}: {$colour}";
}

$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

$result = $sth->fetchAll(PDO::FETCH_FUNC, "fruit");
var_dump($result);
?>

El resultado del ejemplo sería algo similar a:

array(3) {
  [0]=>
  string(12) "apple: green"
  [1]=>
  string(12) "pear: yellow"
  [2]=>
  string(16) "watermelon: pink"
  [3]=>
  string(10) "apple: red"
  [4]=>
  string(11) "pear: green"
}

Ver también