# PDOStatement::fetch

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

PDOStatement::fetch — Récupère la ligne suivante d'un jeu de résultats PDO

### Description

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

Récupère une ligne depuis un jeu de résultats associé à l'objet `PDOStatement`. Le paramètre `mode` détermine la façon dont PDO retourne la ligne.

### Liste de paramètres

`mode`

  Contrôle comment la prochaine ligne sera retournée à l'appelant. Cette valeur doit être une des constantes `PDO::FETCH_*`, et par défaut, vaut la valeur de `PDO::ATTR_DEFAULT_FETCH_MODE` (qui vaut par défaut la valeur de la constante `PDO::FETCH_BOTH`).

  - `PDO::FETCH_ASSOC`: retourne un tableau indexé par le nom de la colonne comme retourné dans le jeu de résultats

  - `PDO::FETCH_BOTH` (défaut): retourne un tableau indexé par les noms de colonnes et aussi par les numéros de colonnes, commençant à l'index 0, comme retournés dans le jeu de résultats

  - `PDO::FETCH_BOUND`: retourne `true` et assigne les valeurs des colonnes de votre jeu de résultats dans les variables PHP à laquelle elles sont liées avec la méthode PDOStatement::bindColumn()

  - `PDO::FETCH_CLASS`: retourne une nouvelle instance de la classe demandée. L'objet est initialisé en mappant les colonnes du jeu de résultats aux propriétés de la classe. Ce processus se produit avant que le constructeur ne soit appelé, permettant la population des propriétés, indépendamment de leur visibilité ou de leur marqueur comme `readonly`. Si une propriété n'existe pas dans la classe, la méthode magique __set() sera invoquée si elle existe ; sinon, une propriété publique dynamique sera créée. Cependant, lorsque `PDO::FETCH_PROPS_LATE` est également spécifié, le constructeur est appelé avant que les propriétés soient peuplées.

  - `PDO::FETCH_INTO` : met à jour une instance existante de la classe demandée, liant les colonnes du jeu de résultats aux noms des propriétés de la classe

  - `PDO::FETCH_LAZY` : combine `PDO::FETCH_BOTH` et `PDO::FETCH_OBJ`, et renvoie un objet PDORow qui crée les noms de propriété de l'objet au fur et à mesure de leur accès.

  - `PDO::FETCH_NAMED` : retourne un tableau de la même forme que `PDO::FETCH_ASSOC`, excepté que s'il y a plusieurs colonnes avec les mêmes noms, la valeur pointée par cette clé sera un tableau de toutes les valeurs de la ligne qui a ce nom comme colonne

  - `PDO::FETCH_NUM` : retourne un tableau indexé par le numéro de la colonne comme elle est retourné dans votre jeu de résultat, commençant à 0

  - `PDO::FETCH_OBJ` : retourne un objet anonyme avec les noms de propriétés qui correspondent aux noms des colonnes retournés dans le jeu de résultats

  - `PDO::FETCH_PROPS_LATE` : lorsqu'il est utilisé avec `PDO::FETCH_CLASS`, le constructeur de la classe est appelé avant que les propriétés ne soient assignées à partir des valeurs de colonne respectives.

`cursorOrientation`

  Pour un objet PDOStatement représentant un curseur scrollable, cette valeur détermine quelle ligne sera retournée à l'appelant. Cette valeur doit être une des constantes `PDO::FETCH_ORI_*`, et par défaut, vaut `PDO::FETCH_ORI_NEXT`. Pour demander un curseur scrollable pour votre objet PDOStatement, vous devez définir l'attribut `PDO::ATTR_CURSOR` à `PDO::CURSOR_SCROLL` lorsque vous préparez la requête SQL avec la fonction PDO::prepare().

`cursorOffset`

  Pour un objet PDOStatement représentant un curseur scrollable pour lequel le paramètre `cursorOrientation` est défini à `PDO::FETCH_ORI_ABS`, cette valeur spécifie le numéro absolu de la ligne dans le jeu de résultats qui doit être récupérée.

  Pour un objet PDOStatement représentant un curseur scrollable pour lequel le paramètre `cursorOrientation` est défini à `PDO::FETCH_ORI_REL`, cette valeur spécifie la ligne à récupérer relativement à la position du curseur avant l'appel à la fonction PDOStatement::fetch().

### Valeurs de retour

La valeur retournée par cette fonction en cas de succès dépend du type récupéré. Dans tous les cas, `false` est retourné si une erreur survient ou s'il n'y a plus de lignes.

### Erreurs / Exceptions

Émet une erreur de niveau `E_WARNING` si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_WARNING`.

Lève une exception PDOException si l'attribut `PDO::ATTR_ERRMODE` est défini à `PDO::ERRMODE_EXCEPTION`.

### Exemples

Exemple #1 Récupération de lignes en utilisant différentes méthodes

`<?php
$sth = $dbh->prepare("SELECT nom, couleur FROM fruit");
$sth->execute();
/* styles PDOStatement::fetch */
print "PDO::FETCH_ASSOC: ";
print "Retourne la ligne suivante en tant qu'un tableau indexé par le nom des colonnes\n";
$result = $sth->fetch(PDO::FETCH_ASSOC);
print_r($result);
print "\n";
print "PDO::FETCH_BOTH: ";
print "Retourne la ligne suivante en tant qu'un tableau indexé par le nom et le numéro de la colonne\n";
$result = $sth->fetch(PDO::FETCH_BOTH);
print_r($result);
print "\n";
print "PDO::FETCH_LAZY: ";
print "Retourne la ligne suivante en tant qu'objet PDORow ayant les noms de colonnes comme propriétés\n";
$result = $sth->fetch(PDO::FETCH_LAZY);
print_r($result);
print "\n";
print "PDO::FETCH_OBJ: ";
print "Retourne la ligne suivante en tant qu'objet anonyme ayant les noms de colonnes comme propriétés\n";
$result = $sth->fetch(PDO::FETCH_OBJ);
print $result->name;
print "\n";
?>`

L'exemple ci-dessus va afficher :

    PDO::FETCH_ASSOC: Retourne la ligne suivante en tant qu'un tableau indexé par le nom des colonnes
    Array
    (
        [nom] => apple
        [couleur] => red
    )

    PDO::FETCH_BOTH: Retourne la ligne suivante en tant qu'un tableau indexé par le nom et le numéro de la colonne
    Array
    (
        [nom] => banana
        [0] => banana
        [couleur] => yellow
        [1] => yellow
    )

    PDO::FETCH_LAZY: Retourne la ligne suivante en tant qu'objet PDORow ayant les noms de colonnes comme propriétés PDORow Object
    (
        [nom] => orange
        [couleur] => orange
    )

    PDO::FETCH_OBJ: Retourne la ligne suivante en tant qu'objet anonyme ayant les noms de colonnes comme propriétés kiwi

Exemple #2 Récupération des lignes avec un curseur scrollable

`<?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 "Lecture en avant :\n";
readDataForwards($conn);
print "Lecture en arrière :\n";
readDataBackwards($conn);
?>`

L'exemple ci-dessus va afficher :

    Lecture en avant :
    21    10    5
    16    0     5
    19    20    10

    Lecture en arrière :
    19    20    10
    16    0     5
    21    10    5

Exemple #3 Ordre de construction

Lorsque des objets sont récupérés via `PDO::FETCH_CLASS`, les propriétés de l'objet sont assignées en premier, puis le constructeur de la classe est appelé. Cependant, lorsque `PDO::FETCH_PROPS_LATE` est également spécifié, cet ordre est inversé, c'est-à-dire que le constructeur est d'abord appelé, puis les propriétés sont assignées.

`<?php
class Person
{
private $name;
public function __construct()
{
$this->tell();
}
public function tell()
{
if (isset($this->name)) {
echo "Je suis {$this->name}.\n";
} else {
echo "Je n'ai pas encore de nom.\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();
?>`

Résultat de l'exemple ci-dessus est similaire à :

    Je suis Alice.
    Je suis Alice.
    Je n'ai pas encore de nom.
    Je suis Bob.

### Voir aussi

- PDO::prepare() - Prépare une requête à l'exécution et retourne un objet
- PDOStatement::execute() - Exécute une requête préparée
- PDOStatement::fetchAll() - Récupère les lignes restantes d'un ensemble de résultats
- PDOStatement::fetchColumn() - Retourne une colonne depuis la ligne suivante d'un jeu de résultats
- PDOStatement::fetchObject() - Récupère la prochaine ligne et la retourne en tant qu'objet
- PDOStatement::setFetchMode() - Définit le mode de récupération par défaut pour cette requête