PDO::prepare

Article
06/08/2024

Prépare une instruction en vue de son exécution.

Syntaxe

PDOStatement PDO::prepare ( $statement [ , array(key_pair) ] )

Paramètres

$instruction

chaîne contenant l’instruction SQL.

key_pair

tableau contenant un nom et une valeur d’attribut. Pour plus d’informations, consultez la section Remarques.

Valeur retournée

Retourne un PDOStatement objet en cas de réussite. En cas d’échec, retourne un PDOException objet ou false en fonction de la valeur de PDO::ATTR_ERRMODE.

Notes

Les pilotes Microsoft pour PHP pour SQL Server n’évaluent pas les instructions préparées tant que l’exécution n’est pas exécutée.

Le tableau suivant répertorie les valeurs possibles de key_pair.

Clé	Description
`PDO::ATTR_CURSOR`	Spécifie le comportement du curseur. La valeur par défaut est `PDO::CURSOR_FWDONLY`, un curseur avant sans défilement. `PDO::CURSOR_SCROLL` est un curseur avec défilement. Par exemple : `array( PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY )`. Lorsque la valeur est définie `PDO::CURSOR_SCROLL`, vous pouvez ensuite utiliser `PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE` pour définir le type de curseur à défilement, qui est décrit plus loin dans cet article. Pour plus d’informations sur les jeux de résultats et les curseurs dans le `PDO_SQLSRV` pilote, consultez Types de curseurs (PDO_SQLSRV Pilote).
`PDO::ATTR_EMULATE_PREPARES`	Par défaut, cet attribut a la valeur false, que vous pouvez remplacer par `PDO::ATTR_EMULATE_PREPARES => true`. Pour plus d’informations et pour obtenir un exemple, consultez Emulate Prepare.
`PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE`	Spécifie le type de curseur avec défilement. Valide uniquement quand `PDO::ATTR_CURSOR` a la valeur `PDO::CURSOR_SCROLL`. Consultez plus loin dans cet article pour connaître les valeurs que cet attribut peut prendre.
`PDO::SQLSRV_ATTR_DECIMAL_PLACES`	Spécifie le nombre de décimales pour la mise en forme des valeurs monétaires extraites. Cette option fonctionne uniquement quand `PDO::SQLSRV_ATTR_FORMAT_DECIMALS` a la valeur true. Pour plus d’informations, consultez Mise en forme des chaînes décimales et valeurs monétaires (pilote PDO_SQLSR).
`PDO::SQLSRV_ATTR_DIRECT_QUERY`	Quand `True`, spécifie l’exécution directe de la requête. `False` signifie l’exécution de l’instruction préparée. Pour plus d’informations sur `PDO::SQLSRV_ATTR_DIRECT_QUERY`, consultez Exécution d’instruction directe et exécution d’instruction préparée dans le pilote PDO_SQLSRV.
`PDO::SQLSRV_ATTR_ENCODING`	`PDO::SQLSRV_ENCODING_UTF8` (valeur par défaut) `PDO::SQLSRV_ENCODING_SYSTEM` `PDO::SQLSRV_ENCODING_BINARY`
`PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE`	Spécifie s’il faut récupérer les types de date et d’heure en tant qu’objets DateTime PHP. Pour plus d’informations, consultez Procédure : Récupérer des types date et heure sous forme d’objets datetime PHP à l’aide du pilote PDO_SQLSRV.
`PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE`	Gère les extractions numériques à partir de colonnes avec des types numériques SQL. Pour plus d’informations, consultez PDO::setAttribute.
`PDO::SQLSRV_ATTR_FORMAT_DECIMALS`	Spécifie s’il faut ajouter des zéros au début des chaînes décimales si nécessaire. Si elle est définie, cette option active l’option `PDO::SQLSRV_ATTR_DECIMAL_PLACES` pour mettre en forme les types monétaires. Pour plus d’informations, consultez Mise en forme des chaînes décimales et valeurs monétaires (pilote PDO_SQLSR).
`PDO::SQLSRV_ATTR_QUERY_TIMEOUT`	Pour plus d’informations, consultez PDO::setAttribute.

En cas d’utilisation de PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL, vous pouvez utiliser PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE pour spécifier le type de curseur. Par exemple, passez le tableau suivant pour PDO::prepare définir un curseur dynamique :

array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL, PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE => PDO::SQLSRV_CURSOR_DYNAMIC));

Le tableau suivant montre les valeurs possibles pour PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE. Pour plus d’informations sur les curseurs avec défilement, consultez Types de curseurs (pilote PDO_SQLSRV).

Valeur	Description
`PDO::SQLSRV_CURSOR_BUFFERED`	Crée un curseur statique côté client (mis en mémoire tampon), qui met en mémoire tampon le jeu de résultats sur l’ordinateur client.
`PDO::SQLSRV_CURSOR_DYNAMIC`	Crée un curseur dynamique côté serveur (nonbuffer), qui vous permet d’accéder aux lignes dans n’importe quel ordre et de refléter les modifications dans la base de données.
`PDO::SQLSRV_CURSOR_KEYSET`	Crée un curseur de jeu de clés côté serveur. Un curseur d’ensemble de clés ne met pas à jour le nombre de lignes si une ligne est supprimée de la table (une ligne supprimée est retournée sans valeurs).
`PDO::SQLSRV_CURSOR_STATIC`	Crée un curseur statique côté serveur, qui vous permet d’accéder aux lignes dans n’importe quel ordre, mais ne reflète pas les modifications dans la base de données. `PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL` implique `PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE => PDO::SQLSRV_CURSOR_STATIC`.

Vous pouvez fermer un PDOStatement objet en appelant unset:

unset($stmt);

Exemple avant uniquement

Cet exemple montre comment utiliser PDO::prepare avec des marqueurs de paramètres et un curseur vers l’avant uniquement.

<?php
$database = "Test";
$server = "(local)";
$conn = new PDO( "sqlsrv:server=$server ; Database = $database", "", "");

$col1 = 'a';
$col2 = 'b';

$query = "insert into Table1(col1, col2) values(?, ?)";
$stmt = $conn->prepare( $query, array( PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY, PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 1  ) );
$stmt->execute( array( $col1, $col2 ) );
print $stmt->rowCount();
echo "\n";

$query = "insert into Table1(col1, col2) values(:col1, :col2)";
$stmt = $conn->prepare( $query, array( PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY, PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 1  ) );
$stmt->execute( array( ':col1' => $col1, ':col2' => $col2 ) );
print $stmt->rowCount();

unset($stmt);
?>

Exemple de curseur statique

Cet exemple montre comment utiliser PDO::prepare avec un curseur statique côté serveur. Pour obtenir un exemple de curseur côté client, consultez Types de curseurs (pilote PDO_SQLSRV).

<?php
$database = "AdventureWorks";
$server = "(local)";
$conn = new PDO( "sqlsrv:server=$server ; Database = $database", "", "");

$query = "select * from Person.ContactType";
$stmt = $conn->prepare( $query, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
$stmt->execute();

echo "\n";

while ( $row = $stmt->fetch( PDO::FETCH_ASSOC ) ){
   print "$row[Name]\n";
}
echo "\n..\n";

$row = $stmt->fetch( PDO::FETCH_BOTH, PDO::FETCH_ORI_FIRST );
print_r($row);

$row = $stmt->fetch( PDO::FETCH_ASSOC, PDO::FETCH_ORI_REL, 1 );
print "$row[Name]\n";

$row = $stmt->fetch( PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT );
print "$row[1]\n";

$row = $stmt->fetch( PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR );
print "$row[1]..\n";

$row = $stmt->fetch( PDO::FETCH_NUM, PDO::FETCH_ORI_ABS, 0 );
print_r($row);

$row = $stmt->fetch( PDO::FETCH_NUM, PDO::FETCH_ORI_LAST );
print_r($row);
?>

Exemple ciblé

Les deux extraits de code suivants montrent comment utiliser PDO::prepare les données ciblées pour / les colonnes char varchar. Comme l’encodage par défaut est PDO::prepare UTF-8, l’utilisateur peut utiliser l’option PDO::SQLSRV_ENCODING_SYSTEM pour éviter les conversions implicites.

Option 1 :

$options = array(PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_SYSTEM);
$statement = $pdo->prepare(
  'SELECT *
   FROM myTable
   WHERE myVarcharColumn = :myVarcharValue',
  $options
);

$statement->bindValue(':myVarcharValue', 'my data', PDO::PARAM_STR);

Option 2 :

$statement = $pdo->prepare(
  'SELECT *
   FROM myTable
   WHERE myVarcharColumn = :myVarcharValue'
);
$p = 'my data';
$statement->bindParam(':myVarcharValue', $p, PDO::PARAM_STR, 0, PDO::SQLSRV_ENCODING_SYSTEM);

Exemple de préparation

Cet exemple montre comment utiliser PDO::prepare avec PDO::ATTR_EMULATE_PREPARES défini sur true.

<?php
$serverName = "yourservername";
$username = "yourusername";
$password = "yourpassword";
$database = "tempdb";
$conn = new PDO("sqlsrv:server = $serverName; Database = $database", $username, $password);

$pdo_options = array();
$pdo_options[PDO::ATTR_EMULATE_PREPARES] = true;
$pdo_options[PDO::SQLSRV_ATTR_ENCODING] = PDO::SQLSRV_ENCODING_UTF8;

$stmt = $conn->prepare("CREATE TABLE TEST([id] [int] IDENTITY(1,1) NOT NULL,
                                          [name] nvarchar(max))",
                                          $pdo_options);
$stmt->execute();

$prefix = '가각';
$name = '가각ácasa';
$name2 = '가각sample2';

$stmt = $conn->prepare("INSERT INTO TEST(name) VALUES(:p0)", $pdo_options);
$stmt->execute(['p0' => $name]);
unset($stmt);

$stmt = $conn->prepare("SELECT * FROM TEST WHERE NAME LIKE :p0", $pdo_options);
$stmt->execute(['p0' => "$prefix%"]);
foreach ($stmt as $row) {
    echo "\n" . 'FOUND: ' . $row['name'];
}

unset($stmt);
unset($conn);
?>

Le PDO_SQLSRV pilote remplace en interne tous les espaces réservés par les paramètres liés par PDOStatement ::bindParam(). Ainsi, une chaîne de requête SQL sans espace réservé est envoyée au serveur. Prenons cet exemple :

$statement = $PDO->prepare("INSERT into Customers (CustomerName, ContactName) VALUES (:cus_name, :con_name)");
$statement->bindParam(:cus_name, "Cardinal");
$statement->bindParam(:con_name, "Tom B. Erichsen");
$statement->execute();

Avec PDO::ATTR_EMULATE_PREPARES défini sur false (le cas par défaut), les données envoyées à la base de données sont :

"INSERT into Customers (CustomerName, ContactName) VALUES (:cus_name, :con_name)"
Information on :cus_name parameter
Information on :con_name parameter

Le serveur exécute la requête à l’aide de sa fonctionnalité de requête paramétrable pour les paramètres de liaison. En revanche, avec PDO::ATTR_EMULATE_PREPARES défini sur true, la requête envoyée au serveur est :

"INSERT into Customers (CustomerName, ContactName) VALUES ('Cardinal', 'Tom B. Erichsen')"

L’affectation de la valeur true à PDO::ATTR_EMULATE_PREPARES peut contourner certaines restrictions dans SQL Server. Par exemple, SQL Server ne prend pas en charge les paramètres nommés ou positionnels dans certaines clauses Transact-SQL. De plus, SQL Server a une limite de 2 100 paramètres de liaison.

Remarque

Avec l’émulation définie sur true, la sécurité des requêtes paramétrables n’est pas en vigueur. Par conséquent, votre application doit s’assurer que les données liées aux paramètres ne contiennent pas de code Transact-SQL malveillant.

Encodage

Si l’utilisateur souhaite lier des paramètres avec des encodages différents (par exemple UTF-8 ou binaire), l’utilisateur doit indiquer clairement l’encodage dans le script PHP.

Le PDO_SQLSRV pilote vérifie d’abord l’encodage spécifié dans PDO::bindParam() (par exemple, $statement->bindParam(:cus_name, "Cardinal", PDO::PARAM_STR, 10, PDO::SQLSRV_ENCODING_UTF8)).

S’il est introuvable, le pilote vérifie si un encodage est défini dans PDO::prepare() ou PDOStatement::setAttribute(). Sinon, le pilote utilise l’encodage spécifié dans PDO::__construct() ou PDO::setAttribute().

En outre, à compter de la version 5.8.0, lors de l’utilisation de PDO ::p repare avec PDO::ATTR_EMULATE_PREPARES la valeur true, l’utilisateur peut utiliser les types de chaînes étendus introduits dans PHP 7.2 pour s’assurer que le N préfixe est utilisé. Les extraits de code suivants affichent différentes alternatives.

Remarque

Par défaut, emulate prepares est définie sur false, auquel cas les constantes de la chaîne PDO étendue seront ignorées.

Utiliser l’option de pilote PDO ::SQLSRV_ENCODING_UTF8 lors de la liaison

$p = '가각';
$sql = 'SELECT :value';
$options = array(PDO::ATTR_EMULATE_PREPARES => true);
$stmt = $conn->prepare($sql, $options);
$stmt->bindParam(':value', $p, PDO::PARAM_STR, 0, PDO::SQLSRV_ENCODING_UTF8);
$stmt->execute();

Utiliser l’attribut PDO ::SQLSRV_ATTR_ENCODING

$p = '가각';
$sql = 'SELECT :value';
$options = array(PDO::ATTR_EMULATE_PREPARES => true, PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8);
$stmt = $conn->prepare($sql, $options);
$stmt->execute([':value' => $p]);

Utiliser la constante PDO PDO ::P ARAM_STR_NATL

$p = '가각';
$sql = 'SELECT :value';
$options = array(PDO::ATTR_EMULATE_PREPARES => true);
$stmt = $conn->prepare($sql, $options);
$stmt->bindParam(':value', $p, PDO::PARAM_STR | PDO::PARAM_STR_NATL);
$stmt->execute();

Définir le type d’analyseur de chaîne par défaut PDO ::P ARAM_STR_NATL

$conn->setAttribute(PDO::ATTR_DEFAULT_STR_PARAM, PDO::PARAM_STR_NATL);
$p = '가각';
$sql = 'SELECT :value';
$options = array(PDO::ATTR_EMULATE_PREPARES => true);
$stmt = $conn->prepare($sql, $options);
$stmt->execute([':value' => $p]);

Limites

Comme vous pouvez le voir, la liaison est effectuée en interne par le pilote. Une requête valide est envoyée au serveur pour l’exécution sans aucun paramètre. Par rapport au cas normal, certaines limitations se traduisent lorsque la fonctionnalité de requête paramétrable n’est pas utilisée.

Il ne fonctionne pas pour les paramètres liés en tant que PDO::PARAM_INPUT_OUTPUT.
- Quand l’utilisateur spécifie PDO::PARAM_INPUT_OUTPUT dans PDO::bindParam(), une exception PDO est levée.
Elle ne fonctionne pas pour les paramètres liés en tant que paramètres de sortie.
- Quand l’utilisateur crée une instruction préparée avec des espaces réservés qui sont destinés à des paramètres de sortie (autrement dit, un signe égal juste après un espace réservé, tel que SELECT ? = COUNT(*) FROM Table1), une exception PDO est levée.
- Lorsqu’une instruction préparée appelle une procédure stockée avec un espace réservé comme argument d’un paramètre de sortie, aucune exception n’est levée, car le pilote ne peut pas détecter le paramètre de sortie. Toutefois, la variable que l’utilisateur fournit pour le paramètre de sortie reste inchangée.
Les espaces réservés en double pour un paramètre encodé binaire ne fonctionnent pas.

Partager via

PDO::prepare

Syntaxe

Paramètres

$instruction

key_pair

Valeur retournée

Notes

Exemple avant uniquement

Exemple de curseur statique

Exemple ciblé

Option 1 :

Option 2 :

Exemple de préparation

Encodage

Utiliser l’option de pilote PDO ::SQLSRV_ENCODING_UTF8 lors de la liaison

Utiliser l’attribut PDO ::SQLSRV_ATTR_ENCODING

Utiliser la constante PDO PDO ::P ARAM_STR_NATL

Définir le type d’analyseur de chaîne par défaut PDO ::P ARAM_STR_NATL

Limites

Commentaires

Commentaires

Ressources supplémentaires

Partager via

PDO::prepare

Syntaxe

Paramètres

$instruction

key_pair

Valeur retournée

Notes

Exemple avant uniquement

Exemple de curseur statique

Exemple ciblé

Option 1 :

Option 2 :

Exemple de préparation

Encodage

Utiliser l’option de pilote PDO ::SQLSRV_ENCODING_UTF8 lors de la liaison

Utiliser l’attribut PDO ::SQLSRV_ATTR_ENCODING

Utiliser la constante PDO PDO ::P ARAM_STR_NATL

Définir le type d’analyseur de chaîne par défaut PDO ::P ARAM_STR_NATL

Limites

Contenu connexe

Commentaires

Commentaires

Ressources supplémentaires