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 function 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é à une instance de 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_NAMED : retourne un tableau de la même forme que PDO::FETCH_ASSOC, excepté que s'il y a plusieurs colonnes avec le même nom, la valeur pointée par cette clé sera un tableau de toutes les valeurs de la ligne qui portent ce nom de colonne.
PDO::FETCH_NUM : retourne un tableau indexé par le numéro de la colonne comme retourné dans le jeu de résultats, en commençant à la colonne 0.
PDO::FETCH_BOTH : retourne un tableau indexé à la fois par le nom de la colonne et par son numéro, commençant à 0, comme retournés dans le jeu de résultats. Il s'agit en pratique d'une combinaison de PDO::FETCH_NUM et de PDO::FETCH_ASSOC.
PDO::FETCH_BOUND : retourne true et assigne les valeurs des colonnes du jeu de résultats aux variables PHP auxquelles elles sont liées avec la méthode PDOStatement::bindColumn().
PDO::FETCH_OBJ : retourne une instance de stdClass dont les noms de propriétés correspondent aux noms des colonnes retournés dans le jeu de résultats.
PDO::FETCH_CLASS : retourne une nouvelle instance de la classe demandée. À moins que la classe n'ait été définie avec PDOStatement::setFetchMode(), ce mode doit être combiné avec PDO::FETCH_CLASSTYPE, auquel cas la classe à instancier est déterminée par la valeur de la première colonne.

Par défaut, 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 l'appel du constructeur, ce qui permet de peupler les propriétés indépendamment de leur visibilité ou de leur marqueur readonly, tant que le constructeur ne les initialise pas lui-même. 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.

Il est possible de modifier ce comportement en utilisant le drapeau PDO::FETCH_PROPS_LATE afin d'appeler le constructeur avant que les propriétés ne soient peuplées.

Attention
Les valeurs des colonnes ne sont pas passées en arguments au constructeur, que PDO::FETCH_PROPS_LATE soit utilisé ou non. Seuls les arguments donnés à PDOStatement::setFetchMode() sont passés.
PDO::FETCH_INTO : met à jour une instance existante de la classe demandée, en mappant les colonnes du jeu de résultats aux propriétés nommées de la classe.
PDO::FETCH_LAZY : combine PDO::FETCH_BOTH et PDO::FETCH_OBJ, et retourne un objet PDORow qui crée les noms de propriété de l'objet au fur et à mesure de leur accès.

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 l'objet PDOStatement, l'attribut PDO::ATTR_CURSOR doit être défini à PDO::CURSOR_SCROLL lorsque la requête SQL est préparée avec la fonction PDO::prepare().

cursorOffset

Si la valeur du paramètre cursorOrientation est 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.

Si la valeur du paramètre cursorOrientation est 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
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE fruit (nom VARCHAR(100), couleur VARCHAR(100))");
$db->exec("INSERT INTO fruit (nom, couleur) VALUES
                             ('apple', 'red'),
                             ('banana', 'yellow'),
                             ('orange', 'orange'),
                             ('kiwi', 'green')");
$sth = $db->prepare("SELECT nom, couleur FROM fruit");
$sth->execute();

/* styles PDOStatement::fetch */
echo "PDO::FETCH_ASSOC: ";
echo "Retourne la ligne suivante sous la forme d'un tableau indexé par le nom des colonnes\n";
$result = $sth->fetch(PDO::FETCH_ASSOC);
var_dump($result);
echo "\n";

echo "PDO::FETCH_BOTH: ";
echo "Retourne la ligne suivante sous la forme d'un tableau indexé par le nom et le numéro de la colonne\n";
$result = $sth->fetch(PDO::FETCH_BOTH);
var_dump($result);
echo "\n";

echo "PDO::FETCH_LAZY: ";
echo "Retourne la ligne suivante sous la forme d'un objet PDORow ayant les noms de colonnes comme propriétés\n";
$result = $sth->fetch(PDO::FETCH_LAZY);
var_dump($result);
echo "\n";

echo "PDO::FETCH_OBJ: ";
echo "Retourne la ligne suivante sous la forme d'un objet stdClass ayant les noms de colonnes comme propriétés\n";
$result = $sth->fetch(PDO::FETCH_OBJ);
var_dump($result);
echo "\n";
?>

L'exemple ci-dessus va afficher :

PDO::FETCH_ASSOC: Retourne la ligne suivante sous la forme d'un tableau indexé par le nom des colonnes
array(2) {
  ["nom"]=>
  string(5) "apple"
  ["couleur"]=>
  string(3) "red"
}

PDO::FETCH_BOTH: Retourne la ligne suivante sous la forme d'un tableau indexé par le nom et le numéro de la colonne
array(4) {
  ["nom"]=>
  string(6) "banana"
  [0]=>
  string(6) "banana"
  ["couleur"]=>
  string(6) "yellow"
  [1]=>
  string(6) "yellow"
}

PDO::FETCH_LAZY: Retourne la ligne suivante sous la forme d'un objet PDORow ayant les noms de colonnes comme propriétés
object(PDORow)#3 (3) {
  ["queryString"]=>
  string(30) "SELECT nom, couleur FROM fruit"
  ["nom"]=>
  string(6) "orange"
  ["couleur"]=>
  string(6) "orange"
}

PDO::FETCH_OBJ: Retourne la ligne suivante sous la forme d'un objet stdClass ayant les noms de colonnes comme propriétés
object(stdClass)#4 (2) {
  ["nom"]=>
  string(4) "kiwi"
  ["couleur"]=>
  string(5) "green"
}

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