PDO::prepare

Télécharger le pilote PHP

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.

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).

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.

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.

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.

Contenu connexe

• PDO, classe
• PDO