PDO::prepare
(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)
PDO::prepare —
Prépare une requête à l'exécution et retourne un objet
Description
Vous devez inclure un marqueur avec un nom unique pour chaque valeur que
vous souhaitez passer dans la requête lorsque vous appelez
PDOStatement::execute(). Vous ne pouvez pas utiliser
un marqueur avec deux noms identiques dans une requête préparée, à moins que
le mode émulation ne soit actif.
Note:
Les marqueurs de paramètres peuvent représenter uniquement un littéral de
données complet.
Ni une partie de littéral, ni un mot clé, ni un identifiant, ni toute autre
requête arbitraire ne peuvent être liés en utilisant les paramètres.
Par exemple, vous ne pouvez associer plusieurs valeurs à un seul marqueur de nom entrant, dans la clause IN() d'une requête SQL.
Appeler PDO::prepare() et
PDOStatement::execute() pour les requêtes
qui doivent être exécutées plusieurs fois avec différentes valeurs de
paramètres optimisent les performances de votre application en autorisant
le pilote à négocier coté client et/ou serveur avec le cache des requêtes
et les meta-informations. De plus appeler PDO::prepare() et
PDOStatement::execute() aident à prévenir les attaques par
injection SQL en éliminant le besoin de protéger les paramètres manuellement.
PDO émule les requêtes préparées / les paramètres liés pour les pilotes
qui ne le supportent pas nativement, et peut également réécrire les
paramètres nommés ou les marqueurs en quelques choses de plus
approprié, si le pilote supporte un style et pas l'autre.
Note:
L'analyseur utilisé pour les déclarations préparés
émulées et pour réécrire les paramètres nommés ou du style point
d'intérogation supporte l'échappement antislash non standard pour les
guillemets simple et double. Ceci signifie que des guillemets terminant qui
sont précédés par un antislash ne seront pas reconnue comme tel, ce qui peut
résulter dans une mauvaise détection des paramètres causant la déclaration
préparer d'échouer lorsqu'elle est exécuté. Un contournement est de ne pas
utiliser les requêtes émulées pour de telles requêtes SQL, et d'éviter de
réécrite les paramètres en utilisant un style de paramètre qui est
supporté nativement par le pilote.
À partir de PHP 7.4.0, les points d'interrogation peuvent être échappés en les dédoublant.
Cela signifie que la chaîne ??
sera traduite en ?
lors de l'envoi de la requête à la base de données.
Liste de paramètres
query
-
Doit être un modèle de requête SQL valide pour le serveur de base de données ciblée.
options
-
Ce tableau contient une ou plusieurs paires clé=>valeur pour définir
les valeurs des attributs pour l'objet PDOStatement
que cette méthode retourne. Vous pouvez utiliser ceci pour définir la valeur
PDO::ATTR_CURSOR
à
PDO::CURSOR_SCROLL
pour demander un curseur scrollable.
Quelques pilotes ont des options spécifiques qui peuvent être définies
au moment de la préparation.
Valeurs de retour
Si le serveur de base de données prépare avec succès cette requête,
PDO::prepare() retourne un objet PDOStatement.
Si le serveur de base de données ne réussit pas à préparer la requête,
PDO::prepare() retourne false
ou émet une exception
PDOException (suivant le
gestionnaire des erreurs).
Note:
L'émulation de requêtes préparées ne communique pas avec le serveur de base
de données. Aussi, la fonction PDO::prepare() ne vérifie
pas la requête.
Exemples
Exemple #1 Modèle de déclaration SQL avec des paramètres nommés
<?php
/* Exécute une requête préparée en passant un tableau de valeurs */
$sql = 'SELECT nom, couleur, calories
FROM fruit
WHERE calories < :calories AND couleur = :couleur';
$sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
$sth->execute(['calories' => 150, 'couleur' => 'red']);
$red = $sth->fetchAll();
/* Les clés du tableau peuvent être préfixées par des deux-points ":" également (facultatif) */
$sth->execute([':calories' => 175, ':couleur' => 'yellow']);
$yellow = $sth->fetchAll();
?>
Exemple #2 Modèle de déclaration SQL avec des marqueurs
<?php
/* Exécute une requête préparée en passant un tableau de valeurs */
$sth = $dbh->prepare('SELECT nom, couleur, calories
FROM fruit
WHERE calories < ? AND couleur = ?');
$sth->execute([150, 'rouge']);
$red = $sth->fetchAll();
$sth->execute([175, 'jaune']);
$yellow = $sth->fetchAll();
?>
Exemple #3 Modèle de déclaration SQL avec un point d'interrogation échappé
<?php
/* note: ceci n'est valable que pour les bases de données PostgreSQL */
$sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
$sth->execute(['feature']);
$featureIssues = $sth->fetchAll();
$sth->execute(['performance']);
$performanceIssues = $sth->fetchAll();
?>