PDO::prepare

Descargar controlador PHP

Prepara una instrucción para su ejecución.

Sintaxis

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

Parámetros

$instrucción

una cadena que contiene la instrucción SQL.

key_pair

una matriz que contiene un valor y un nombre de atributo. Para obtener más información, vea la sección Notas.

Valor devuelto

Devuelve un PDOStatement objeto si se ejecuta correctamente. Si se produce un error, devuelve un PDOException objeto o false en función del valor de PDO::ATTR_ERRMODE.

Comentarios

Los controladores de Microsoft para PHP para SQL Server no evalúan las instrucciones preparadas hasta la ejecución.

En la siguiente tabla se incluyen los posibles valores key_pair.

Cuando se usa PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL, puede usar PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE para especificar el tipo de cursor. Por ejemplo, pase la siguiente matriz para PDO::prepare establecer un cursor dinámico:

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

En la tabla siguiente se muestran los valores posibles para PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE. Para más información sobre los cursores desplazables, vea Tipos de cursor (controlador PDO_SQLSRV).

Puede cerrar un PDOStatement objeto llamando a unset:

unset($stmt);

Ejemplo de solo avance

En este ejemplo se muestra cómo usar PDO::prepare con marcadores de parámetro y un cursor de solo avance.

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

Ejemplo de cursor estático

En este ejemplo se muestra cómo usar PDO::prepare con un cursor estático del lado servidor. Para ver un ejemplo en el que se muestre un cursor del lado cliente, vea Tipos de cursor (controlador 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);
?>

Ejemplo de destino

Los dos fragmentos de código siguientes muestran cómo usar PDO::prepare con datos destinados a columnas / char varchar. Dado que la codificación predeterminada para PDO::prepare es UTF-8, el usuario puede usar la opción PDO::SQLSRV_ENCODING_SYSTEM para evitar conversiones implícitas.

Opción 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);

Opción 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);

Ejemplo de preparación

En este ejemplo se muestra cómo usar PDO::prepare con PDO::ATTR_EMULATE_PREPARES establecido en 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);
?>

El PDO_SQLSRV controlador reemplaza internamente todos los marcadores de posición por los parámetros enlazados por PDOStatement::bindParam().. Por tanto, se envía al servidor una cadena de consulta SQL sin ningún marcador de posición. Considere este ejemplo:

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

Con PDO::ATTR_EMULATE_PREPARES establecido en false (el caso predeterminado), los datos enviados a la base de datos son:

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

El servidor ejecuta la consulta mediante su característica de consulta parametrizada para los parámetros de enlace. Por otro lado, con PDO::ATTR_EMULATE_PREPARES establecido en true, la consulta enviada al servidor es básicamente:

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

Establecer PDO::ATTR_EMULATE_PREPARES en true puede omitir algunas restricciones en SQL Server. Por ejemplo, SQL Server no admite parámetros con nombre o posicionales en algunas cláusulas Transact-SQL. Además, SQL Server tiene un límite de enlace de 2100 parámetros.

Encoding

Si el usuario desea enlazar parámetros con distintas codificaciones (por ejemplo, UTF-8 o binario), el usuario debe especificar claramente la codificación en el script PHP.

El PDO_SQLSRV controlador comprueba primero la codificación especificada en PDO::bindParam() (por ejemplo, $statement->bindParam(:cus_name, "Cardinal", PDO::PARAM_STR, 10, PDO::SQLSRV_ENCODING_UTF8)).

Si no se encuentra, el controlador comprueba si cualquier codificación está establecida en PDO::prepare() o PDOStatement::setAttribute(). De lo contrario, el controlador usa la codificación especificada en PDO::__construct() o PDO::setAttribute().

Además, a partir de la versión 5.8.0, al usar PDO::p repare con establecido en PDO::ATTR_EMULATE_PREPARES true, el usuario puede usar los tipos de cadena extendidos introducidos en PHP 7.2 para asegurarse de que se usa el N prefijo. Los fragmentos de código siguientes muestran varias alternativas.

Usar la opción de controlador PDO::SQLSRV_ENCODING_UTF8 al enlazar

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

Uso del atributo 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]);

Uso de 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();

Establecer el tipo de parámetro de cadena predeterminado 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]);

Limitaciones

Como puede ver, el enlace lo realiza el controlador internamente. Se envía una consulta válida al servidor para su ejecución sin ningún parámetro. En comparación con el caso normal, algunas limitaciones resultan cuando la característica de consulta con parámetros no está en uso.

• No funciona para los parámetros enlazados como PDO::PARAM_INPUT_OUTPUT.
  • Cuando el usuario especifica PDO::PARAM_INPUT_OUTPUT en PDO::bindParam(), se produce una excepción de PDO.
• No funciona para los parámetros enlazados como parámetros de salida.
  • Cuando el usuario crea una instrucción preparada con marcadores de posición que están destinados a los parámetros de salida (es decir, con un signo igual inmediatamente después de un marcador de posición, como SELECT ? = COUNT(*) FROM Table1), se produce una excepción PDO.
  • Cuando una instrucción preparada invoca un procedimiento almacenado con un marcador de posición como argumento para un parámetro de salida, no se produce ninguna excepción porque el controlador no puede detectar el parámetro de salida. Sin embargo, la variable que proporciona el usuario para el parámetro de salida permanece sin cambios.
• Los marcadores de posición duplicados para un parámetro codificado binario no funcionan.

Contenido relacionado

• Clase PDO
• PDO