Recupera la siguiente línea de un conjunto de resultados PDO

# PDOStatement::fetch

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

PDOStatement::fetch — Recupera la siguiente línea de un conjunto de resultados PDO

### Descripción

public function PDOStatement::fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed

Recupera una línea desde un conjunto de resultados asociado al objeto PDOStatement. El argumento `mode` determina la forma en que PDO devuelve la línea.

### Parámetros

`mode`

  Controla cómo se devolverá la siguiente línea al llamante. Este valor debe ser una de las constantes `PDO::FETCH_*`, y por omisión, vale la constante `PDO::ATTR_DEFAULT_FETCH_MODE` (que por omisión vale la constante `PDO::FETCH_BOTH`).

  - `PDO::FETCH_ASSOC`: devuelve un array indexado por el nombre de la columna como se devuelve en el conjunto de resultados

  - `PDO::FETCH_BOTH` (por omisión): devuelve un array indexado por los nombres de columnas y también por los números de columnas, comenzando en el índice 0, como se devuelve en el conjunto de resultados

  - `PDO::FETCH_BOUND`: devuelve `true` y asigna los valores de las columnas de su conjunto de resultados en las variables PHP a las que están vinculadas con el método PDOStatement::bindColumn()

  - `PDO::FETCH_CLASS`: devuelve una nueva instancia de la clase solicitada. El objeto se inicializa mapeando las columnas del conjunto de resultados a las propiedades de la clase. Este proceso ocurre antes de que se llame al constructor, permitiendo la población de las propiedades, independientemente de su visibilidad o de su marca como `readonly`. Si una propiedad no existe en la clase, se invocará el método mágico __set() si existe; de lo contrario, se creará una propiedad pública dinámica. Sin embargo, cuando `PDO::FETCH_PROPS_LATE` también está especificado, el constructor se llama antes de que las propiedades sean pobladas. Si `mode` incluye `PDO::FETCH_CLASSTYPE` (p.ej. `PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE`), el nombre de la clase se determina a partir del valor de la primera columna.

  - `PDO::FETCH_INTO` : actualiza una instancia existente de la clase solicitada, vinculando las columnas del conjunto de resultados a los nombres de las propiedades de la clase

  - `PDO::FETCH_LAZY` : combina `PDO::FETCH_BOTH` y `PDO::FETCH_OBJ`, y devuelve un objeto PDORow que crea los nombres de propiedad del objeto a medida que se acceden.

  - `PDO::FETCH_NAMED` : devuelve un array de la misma forma que `PDO::FETCH_ASSOC`, excepto que si hay múltiples columnas con los mismos nombres, el valor apuntado por esta clave será un array de todas las valores de la línea que tiene ese nombre como columna

  - `PDO::FETCH_NUM` : devuelve un array indexado por el número de la columna como se devuelve en su conjunto de resultados, comenzando en 0

  - `PDO::FETCH_OBJ` : devuelve un objeto anónimo con los nombres de propiedades que corresponden a los nombres de las columnas devueltas en el conjunto de resultados

  - `PDO::FETCH_PROPS_LATE` : cuando se usa con `PDO::FETCH_CLASS`, el constructor de la clase es llamado antes de que las propiedades sean asignadas a partir de los valores de columna respectivos.

`cursorOrientation`

  Para un objeto PDOStatement que representa un cursor desplazable, este valor determina qué línea se devolverá al llamante. Este valor debe ser una de las constantes `PDO::FETCH_ORI_*`, y por omisión, vale `PDO::FETCH_ORI_NEXT`. Para solicitar un cursor desplazable para su objeto PDOStatement, debe definir el atributo `PDO::ATTR_CURSOR` a `PDO::CURSOR_SCROLL` cuando prepare la consulta SQL con la función PDO::prepare().

`cursorOffset`

  Para un objeto PDOStatement que representa un cursor desplazable para el cual el argumento `cursorOrientation` está definido a `PDO::FETCH_ORI_ABS`, este valor especifica el número absoluto de la línea en el conjunto de resultados que debe ser recuperada.

  Para un objeto PDOStatement que representa un cursor desplazable para el cual el argumento `cursorOrientation` está definido a `PDO::FETCH_ORI_REL`, este valor especifica la línea a recuperar relativamente a la posición del cursor antes de la llamada a la función PDOStatement::fetch().

### Valores devueltos

El valor devuelto por esta función en caso de éxito depende del tipo recuperado. En todos los casos, `false` se devuelve si ocurre un error o si no hay más líneas.

### Errores/Excepciones

Emite un error de nivel `E_WARNING` si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_WARNING`.

Lanza una excepción PDOException si el atributo `PDO::ATTR_ERRMODE` está definido a `PDO::ERRMODE_EXCEPTION`.

### Ejemplos

Ejemplo #1 Recuperación de líneas utilizando diferentes métodos

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

    /* estilos PDOStatement::fetch */
    print "PDO::FETCH_ASSOC: ";
    print "Devuelve la siguiente línea como un array indexado por el nombre de las columnas\n";
    $result = $sth->fetch(PDO::FETCH_ASSOC);
    print_r($result);
    print "\n";

    print "PDO::FETCH_BOTH: ";
    print "Devuelve la siguiente línea como un array indexado por el nombre y el número de la columna\n";
    $result = $sth->fetch(PDO::FETCH_BOTH);
    print_r($result);
    print "\n";

    print "PDO::FETCH_LAZY: ";
    print "Devuelve la siguiente línea como objeto PDORow con los nombres de columnas como propiedades\n";
    $result = $sth->fetch(PDO::FETCH_LAZY);
    print_r($result);
    print "\n";

    print "PDO::FETCH_OBJ: ";
    print "Devuelve la siguiente línea como objeto anónimo con los nombres de columnas como propiedades\n";
    $result = $sth->fetch(PDO::FETCH_OBJ);
    print $result->name;
    print "\n";
    ?>

El ejemplo anterior mostrará:

    PDO::FETCH_ASSOC: Devuelve la siguiente línea como un array indexado por el nombre de las columnas
    Array
    (
        [nom] => apple
        [couleur] => red
    )

    PDO::FETCH_BOTH: Devuelve la siguiente línea como un array indexado por el nombre y el número de la columna
    Array
    (
        [nom] => banana
        [0] => banana
        [couleur] => yellow
        [1] => yellow
    )

    PDO::FETCH_LAZY: Devuelve la siguiente línea como objeto PDORow con los nombres de columnas como propiedades PDORow Object
    (
        [nom] => orange
        [couleur] => orange
    )

    PDO::FETCH_OBJ: Devuelve la siguiente línea como objeto anónimo con los nombres de columnas como propiedades kiwi

Ejemplo #2 Recuperación de líneas con un cursor desplazable

    <?php
    function readDataForwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        }
    }
    function readDataBackwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        $row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
        do {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        } while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
    }

    print "Lectura hacia adelante :\n";
    readDataForwards($conn);

    print "Lectura hacia atrás :\n";
    readDataBackwards($conn);
    ?>

El ejemplo anterior mostrará:

    Lectura hacia adelante :
    21    10    5
    16    0     5
    19    20    10

    Lectura hacia atrás :
    19    20    10
    16    0     5
    21    10    5

Ejemplo #3 Orden de construcción

Cuando los objetos son recuperados mediante `PDO::FETCH_CLASS`, las propiedades del objeto se asignan primero, luego se llama al constructor de la clase. Sin embargo, cuando `PDO::FETCH_PROPS_LATE` también está especificado, este orden se invierte, es decir, el constructor se llama primero, luego las propiedades son asignadas.

    <?php
    class Person
    {
        private $name;

        public function __construct()
        {
            $this->tell();
        }

        public function tell()
        {
            if (isset($this->name)) {
                echo "Soy {$this->name}.\n";
            } else {
                echo "Aún no tengo nombre.\n";
            }
        }
    }

    $sth = $dbh->query("SELECT * FROM people");
    $sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
    $person = $sth->fetch();
    $person->tell();
    $sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
    $person = $sth->fetch();
    $person->tell();
    ?>

Resultado del ejemplo anterior es similar a:

    Soy Alice.
    Soy Alice.
    Aún no tengo nombre.
    Soy Bob.

### Ver también

- PDO::prepare() - Prepara una consulta para su ejecución y devuelve un objeto
- PDOStatement::execute() - Ejecuta una consulta preparada
- PDOStatement::fetchAll() - Recupera las líneas restantes de un conjunto de resultados
- PDOStatement::fetchColumn() - Devuelve una columna de la siguiente fila de un conjunto de resultados
- PDOStatement::fetchObject() - Recupera la siguiente línea y la devuelve como objeto
- PDOStatement::setFetchMode() - Establece el modo de recuperación por defecto para esta consulta

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open