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

public PDO::prepare(string $query, array $options = []): PDOStatement|false

Prépare une requête SQL à être exécutée par la méthode PDOStatement::execute(). Le modèle de déclaration peut contenir zéro ou plusieurs paramètres nommés (:nom) ou marqueurs (?) pour lesquels les valeurs réelles seront substituées lorsque la requête sera exécutée. L'utilisation à la fois des paramètres nommés ainsi que les marqueurs est impossible dans un modèle de déclaration ; seul l'un ou l'autre style de paramètre. Il faut utiliser ces paramètres pour lier les entrées utilisateurs et ne pas les inclure directement dans la requête.

Il faut inclure un marqueur avec un nom unique pour chaque valeur que l'on souhaite passer dans la requête lorsque l'on appelle PDOStatement::execute(). Il n'est pas possible d'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, il n'est pas possible d'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 l'application en autorisant le pilote à négocier côté 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ées émulées et pour réécrire les paramètres nommés ou du style point d'interrogation supporte l'échappement antislash non standard pour les guillemets simples et doubles. Cela signifie que les guillemets de fin précédés d'un antislash ne sont pas reconnus comme tels, ce qui peut entraîner une mauvaise détection des paramètres provoquant l'échec de la déclaration préparée lors de son exécution. Un contournement est de ne pas utiliser les requêtes émulées pour de telles requêtes SQL, et d'éviter de réécrire 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. Il est possible d'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.

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 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();
?>

Voir aussi

PDO::exec() - Exécute une requête SQL et retourne le nombre de lignes affectées
PDO::query() - Prépare et Exécute une requête SQL sans marque substitutive
PDOStatement::execute() - Exécute une requête préparée