PDO::prepare

Pobierz sterownik PHP

Przygotowuje oświadczenie do wykonania.

Składnia

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

Parameters

$ Oświadczenie

Ciąg znaków zawierający instrukcję SQL.

key_pair

Tablica zawierająca nazwę atrybutu i wartość. Aby uzyskać więcej informacji, zobacz sekcję Uwagi.

Wartość zwracana

Zwraca obiekt po PDOStatement sukcesie. W przypadku niepowodzenia zwraca PDOException obiekt lub false, w zależności od wartości PDO::ATTR_ERRMODE.

Uwagi

Sterowniki Microsoft dla PHP dla SQL Server nie oceniają przygotowanych instrukcji do momentu ich wykonania.

Aby zadeklarować typy i długości SQL łańcuchów wejściowych, ustaw PDO::SQLSRV_ATTR_PARAM_METADATA na zwróconej instrukcji, a nie w tablicy prepare opcji. Dla adaptacyjnego rozmiarowania ustaw PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH na połączenie przed wywołaniem prepare; nowa instrukcja kopiuje to ustawienie. Przykłady i ograniczenia znajdziesz w sekcji Deklarowanie typów i długości ciągów wejściowych (PDO_SQLSRV).

Poniższa tabela zawiera możliwe wartości key_pair .

Key Description
PDO::ATTR_CURSOR Określa zachowanie kursora. Domyślnie PDO::CURSOR_FWDONLYjest , nieprzewijany kursor do przodu. PDO::CURSOR_SCROLL jest przewijanym kursorem.

Na przykład array( PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY ).

Gdy ustawiono na PDO::CURSOR_SCROLL, możesz następnie ustawić PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE typ przewijanego kursora, co zostanie opisane później w tym artykule.

Zobacz Typy kursorów (PDO_SQLSRV Sterownik ), aby uzyskać więcej informacji o zestawach wyników i kursorach w sterowniku PDO_SQLSRV .
PDO::ATTR_EMULATE_PREPARES Domyślnie ten atrybut jest false, co można zmienić przez .PDO::ATTR_EMULATE_PREPARES => true Zobacz Emuluj Przygotowanie , aby uzyskać szczegóły i przykład.
PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE Określa typ przewijanego kursora. Prawidłowe tylko wtedy, gdy PDO::ATTR_CURSOR jest ustawione na PDO::CURSOR_SCROLL. Zobacz później w tym artykule wartości, jakie może przyjmować ten atrybut.
PDO::SQLSRV_ATTR_DECIMAL_PLACES Określa liczbę miejsc po przecinku przy formatowaniu wartości pobieranych pieniędzy. Ta opcja działa tylko wtedy, gdy PDO::SQLSRV_ATTR_FORMAT_DECIMALS ma wartość true. Więcej informacji można znaleźć w artykule Formatowanie łańcuchów dziesiętnych i wartości pieniężnych (PDO_SQLSRV Driver).
PDO::SQLSRV_ATTR_DIRECT_QUERY Gdy True, określa bezpośrednie wykonanie zapytania. False oznacza przygotowane wykonanie instrukcji. Aby uzyskać więcej informacji o PDO::SQLSRV_ATTR_DIRECT_QUERY, zobacz Bezpośrednie wykonywanie instrukcji oraz Przygotowane wykonywanie instrukcji w sterowniku PDO_SQLSRV.
PDO::SQLSRV_ATTR_ENCODING PDO::SQLSRV_ENCODING_UTF8 (domyślnie)
PDO::SQLSRV_ENCODING_UTF8_VARCHAR (wersja 5.14.0 i nowsze)
PDO::SQLSRV_ENCODING_SYSTEM
PDO::SQLSRV_ENCODING_BINARY
PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE Określa, czy należy pobierać typy daty i godziny jako obiekty PHP DateTime . Aby uzyskać więcej informacji, zobacz How to: Retrieve Date and Time Types as PHP DateTime Objects Using the PDO_SQLSRV Driver (Jak pobrać typy dat i godzin jako obiekty typu data/godzina w języku PHP przy użyciu sterownika PDO_SQLSRV).
PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE Obsługuje numeryczne pobieranie z kolumn o numerycznych typach SQL. Więcej informacji można znaleźć pod adresem PDO::setAttribute.
PDO::SQLSRV_ATTR_FORMAT_DECIMALS Określa, czy należy dodawać zera wiodące do ciągów dziesiętnych, gdy jest to stosowne. Jeśli jest ustawiona, ta opcja umożliwia PDO::SQLSRV_ATTR_DECIMAL_PLACES formatowanie typów pieniędzy. Więcej informacji można znaleźć w artykule Formatowanie łańcuchów dziesiętnych i wartości pieniężnych (PDO_SQLSRV Driver).
PDO::SQLSRV_ATTR_QUERY_TIMEOUT Więcej informacji można znaleźć pod adresem PDO::setAttribute.

Podczas używania PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL, możesz użyć PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE do określenia typu kursora. Na przykład, przekaż następującą tablicę do , PDO::prepare aby ustawić dynamiczny kursor:

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

Poniższa tabela przedstawia możliwe wartości dla PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE. Aby uzyskać więcej informacji o przewijanych kursorach, zobacz Typy kursorów (PDO_SQLSRV Sterownik).

Value Description
PDO::SQLSRV_CURSOR_BUFFERED Tworzy statyczny kursor po stronie klienta (buforowany), który buforuje zestaw wyników w pamięci maszyny klienckiej.
PDO::SQLSRV_CURSOR_DYNAMIC Tworzy dynamiczny kursor po stronie serwera (niebuforowany), który pozwala na dostęp do wierszy w dowolnej kolejności i odzwierciedlanie zmian w bazie danych.
PDO::SQLSRV_CURSOR_KEYSET Tworzy kursor zestawu kluczy po stronie serwera. Kursor zestawu kluczy nie aktualizuje liczby wierszy, jeśli wiersz zostanie usunięty z tabeli (usunięty wiersz jest zwracany bez wartości).
PDO::SQLSRV_CURSOR_STATIC Tworzy statyczny kursor po stronie serwera, który pozwala na dostęp do wierszy w dowolnej kolejności, ale nie odzwierciedla zmian w bazie danych.

PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL implikuje PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE => PDO::SQLSRV_CURSOR_STATIC.

Możesz zamknąć obiekt, PDOStatement wywołując unset:

unset($stmt);

Przykład tylko do przodu

Ten przykład pokazuje, jak używać PDO::prepare markerów parametrów i kursora tylko do przodu.

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

Przykład statycznego kursora

Ten przykład pokazuje, jak używać PDO::prepare statycznego kursora po stronie serwera. Przykład pokazujący kursor po stronie klienta znajdziesz w sekcji Typy kursorów (sterownik 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);
?>

Przykład docelowy

Poniższe dwa fragmenty pokazują, jak używać PDO::prepare danych skierowanych do kolumn char / varchar . Ponieważ domyślne kodowanie dla PDO::prepare to UTF-8, użytkownik może użyć tej opcji PDO::SQLSRV_ENCODING_SYSTEM , aby uniknąć niejawnych konwersji.

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

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

Przygotuj przykład

Ten przykład pokazuje, jak używać PDO::p repare z PDO::ATTR_EMULATE_PREPARES ustawioną na 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);
?>

Sterownik PDO_SQLSRV wewnętrznie zastępuje wszystkie symbole zastępcze parametrami ograniczonymi przez PDOStatement::bindParam(). W związku z tym do serwera wysyłany jest ciąg zapytania SQL bez symboli zastępczych. Rozważ taki przykład:

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

Przy ustawieniu na PDO::ATTR_EMULATE_PREPARES false (domyślny przypadek), dane wysyłane do bazy danych to:

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

Serwer wykonuje zapytanie, używając funkcji parametryzowanego zapytania do powiązania parametrów. Z drugiej strony, przy PDO::ATTR_EMULATE_PREPARES ustawieniu na true, zapytanie wysyłane do serwera jest zasadniczo:

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

Ustawienie PDO::ATTR_EMULATE_PREPARES na true może obejść niektóre ograniczenia w SQL Server. Na przykład SQL Server nie obsługuje parametrów nazwanych ani pozycyjnych w niektórych klauzulach Transact-SQL. Ponadto SQL Server ma limit powiązania do 2 100 parametrów.

Note

Gdy emulate preprese ustawiono na true, bezpieczeństwo parametryzowanych zapytań nie jest aktywne. Dlatego Twoja aplikacja powinna upewnić się, że dane powiązane z tymi parametrami nie zawierają złośliwego kodu Transact-SQL.

Encoding

Jeśli użytkownik chce powiązać parametry z różnymi kodowaniami (na przykład UTF-8 lub binarne), powinien jasno określić kodowanie w skrypcie PHP.

Sterownik PDO_SQLSRV najpierw sprawdza kodowanie określone w ( PDO::bindParam() na przykład $statement->bindParam(:cus_name, "Cardinal", PDO::PARAM_STR, 10, PDO::SQLSRV_ENCODING_UTF8)).

Jeśli nie zostanie znaleziony, sterownik sprawdza, czy jakiekolwiek kodowanie jest ustawione w PDO::prepare() lub PDOStatement::setAttribute(). W przeciwnym razie sterownik używa kodowania określonego w PDO::__construct() lub PDO::setAttribute().

Dodatkowo, począwszy od wersji 5.8.0, używając PDO::p repare z PDO::ATTR_EMULATE_PREPARES ustawionym na true, użytkownik może korzystać z rozszerzonych typów ciągów znaków wprowadzonych w PHP 7.2 , aby upewnić się, że prefiks N jest używany. Poniższe fragmenty przedstawiają różne alternatywy.

Note

Domyślnie emulacja przygotowuje jest ustawiona na false, w takim przypadku rozszerzone stałe ciągowe PDO zostaną zignorowane.

Użyj opcji sterownika PDO::SQLSRV_ENCODING_UTF8 podczas wiązania

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

Użyj atrybutu 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]);

Użyj stałej 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();

Ustaw domyślny typ parametru łańcucha tekstów 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]);

Limitations

Jak widać, oprawianie odbywa się wewnętrznie przez sterownika. Prawidłowe zapytanie jest wysyłane do serwera do wykonania bez żadnych parametrów. W porównaniu do zwykłego przypadku, pewne ograniczenia pojawiają się, gdy funkcja zapytania parametrycznego nie jest używana.

  • Nie działa dla parametrów powiązanych jako PDO::PARAM_INPUT_OUTPUT.
    • Gdy użytkownik wskaże PDO::PARAM_INPUT_OUTPUT w , PDO::bindParam()wyjątek PDO jest rzucany.
  • Nie działa to dla parametrów, które są przypisane jako parametry wyjściowe.
    • Gdy użytkownik tworzy przygotowane zapytanie z zastępczymi przeznaczonymi dla parametrów wyjściowych (czyli z znakiem równości bezpośrednio po zastępczym symbolu, np SELECT ? = COUNT(*) FROM Table1. ), wyrzucany jest wyjątek PDO.
    • Gdy przygotowane polecenie wywołuje procedurę składowaną z symbolem zastępczym jako argumentem parametru wyjściowego, nie jest wywoływany żaden wyjątek, ponieważ sterownik nie jest w stanie wykryć parametru wyjściowego. Jednak zmienna podana przez użytkownika jako parametr wyjściowy pozostaje niezmieniona.
  • Duplikowane symbole zastępcze dla binarnego zakodowanego parametru nie działają.