Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Użyj jawnych deklaracji, aby wysłać ciąg wejściowy jako varchar lub nvarchar o określonej długości SQL. Alternatywnie, wybierz adaptacyjne rozmiarowanie, aby zacząć od wybranej długości i powiększać deklarację przy wysyłaniu dłuższych wartości.
Te opcje wymagają wersji 5.14.0 lub nowszej i dotyczą tylko PDO_SQLSRV, czyli sterownika PHP Data Objects (PDO). Dla SQLSRV kontynuuj określanie typów SQL w tablicy parametrów opisanej w sekcji Określanie typów danych SQL Server. Żadne z tych podejść nie zmienia definicji kolumny docelowej.
Wybierz metodę deklaracji
| Method | Konfiguracja | Behavior |
|---|---|---|
| Metadane jawnej deklaracji | Zadzwoń PDOStatement::setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, $metadata) po prepare. |
Dotyczy bindParam, bindValue, oraz execute($params). |
| Jawne metadane wiązania | Przekaż tablicę deklaracji jako piąty argument bindParam. |
Zastępuje cały wpis metadanych instrukcji dla tego powiązania, włącznie z jego opcjonalnym kodowaniem. |
| Rozmiarowanie adaptacyjne | Ustaw PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH w połączeniu przed utworzeniem instrukcji. |
Dotyczy kwalifikujących się ciągów wejściowych bez jawnej deklaracji. |
Bez wyraźnych metadanych lub adaptacyjnego rozmiarowania istniejące zachowanie rozmiarowania parametrów pozostaje bez zmian. Nie potrzebujesz tych opcji dla zwykłych zapytań parametrycznych.
Zadeklaruj ciąg wejściowy
Każda deklaracja to tablica z kluczami będącymi stałymi całkowitoliczbowymi i wartościami całkowitymi.
| Key | Value |
|---|---|
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE |
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR lub PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR. |
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH |
Dla varchar, od 1 do 8 000 bajtów. Dla nvarchar, od 1 do 4 000 jednostek kodu w 16-bitowym Unicode Transformation Format (UTF-16). Użyj PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH_MAX dla varchar(max) lub nvarchar(max). |
PDO::SQLSRV_ATTR_ENCODING (opcjonalnie) |
Kodowanie znaków ciągu wejściowego PHP. Do wprowadzania w 8-bitowym Unicode Transformation Format (UTF-8) użyj PDO::SQLSRV_ENCODING_UTF8 lub PDO::SQLSRV_ENCODING_UTF8_VARCHAR. Zadeklarowany typ, a nie kodowanie, ustawia typ SQL. Możesz też użyć PDO::SQLSRV_ENCODING_SYSTEM do wprowadzania danych w kodowaniu systemu. Kodowanie binarne nie jest obsługiwane. |
Musisz uwzględnić oba klucze deklaracji. Ciągi znaków liczbowych, wartości logiczne, zerowe długości oraz nierozpoznane klucze są nieprawidłowe. Dodatkowy znak Unicode, taki jak "\u{1F600}", zajmuje dwie jednostki kodu UTF-16, mimo że PHP przechowuje swoją reprezentację UTF-8 w czterech bajtach.
Kodowanie opisuje bajty źródłowe. Zadeklarowany typ opisuje parametr SQL wysyłany do serwera. Na przykład możesz wysłać dane wejściowe UTF-8 jako varchar bez zmiany bajtów źródłowych na kodowanie systemowe. Konwersja na varchar nadal zależy od SQL kolejacji i jej repertuaru znaków. Jawnie określona długość w SQL nie przydziela bufora PHP.
Gdy sterownik deklaruje parametr powiązany dla przygotowanej instrukcji, ignoruje flagi PDO::PARAM_STR_NATL i PDO::PARAM_STR_CHAR . Użyj deklaracji, aby wybrać varchar lub nvarchar.
Dla metadanych instrukcji użyj mapy identyfikatorów parametrów na tablice deklaracji:
- Używaj pozycji numerowanych od 1 dla symboli zastępczych ze znakiem zapytania, takich jak
[1 => $declaration]. Pozycje muszą być liczbami całkowitymi od 1 do 2 100 i muszą identyfikować parametry związane podczas wykonywania. - Użyj unikalnej nazwy zastępczej, z dwukropkiem lub bez, na przykład
['name' => $declaration]lub[':name' => $declaration]. Powtarzająca się nazwa zastępcza nie identyfikuje unikalnej pozycji. Nie podawaj tej samej pozycji dwa razy przez różne nazwy lub klucze numeryczne. - Ustaw metadane po
prepare, a nie w tablicy opcji. Każdy udany setter zastępuje całą mapę i resetuje historię adaptacyjnych rozmiarów. Nieprawidłowe zastąpienie zachowuje poprzednią mapę. Przekaż[], aby wyczyścić mapę;nulljest nieprawidłowe. - Wywołaj
getAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA)na instrukcji, aby pobrać odwzorowanie znormalizowane do pozycji opartych na 1. Zwraca metadane instrukcji, a nie nadpisania dla poszczególnych powiązań czy adaptacyjnej historii rozmiaru.
Tablica przekazywana do execute dostarcza wartości, a nie deklaracji. Jego wartości pozycyjne używają zwykłej tablicy PHP opartej na zerze, takiej jak ['text']; mapa metadanych nadal używa [1 => $declaration].
Dla bindParam, zachowaj czwarty argument na poziomie 0 dla deklaracji wejściowej. Dodatni czwarty argument wybiera zachowanie bufora wyjściowego; nie jest to nowa długość deklaracji SQL. Opcje kodowania liczb całkowitych w piątym argumencie nadal działają. Tablica deklaracji nadpisuje cały wpis instrukcji dla tego powiązania, podczas gdy opcja kodowania całkowitego nadpisuje jedynie kodowanie. Ponowne powiązanie bez tablicy deklaracji usuwa nadpisanie tego powiązania, ale zachowuje metadane instrukcji.
Przykład: deklaracje jawne
Przykłady w tym artykule zakładają otwarte połączenie PDO w $conn, które używa PDO::ERRMODE_EXCEPTION. Aby je otworzyć, zobacz Łączenie z serwerem. Skorzystaj z poniższej tabeli:
CREATE TABLE dbo.Customers
(
CustomerID int IDENTITY PRIMARY KEY,
Name nvarchar(100) NOT NULL,
Code varchar(10) NOT NULL
);
Bez deklaracji sterownik wysyła każdą wartość ciągu znaków w poniższych przykładach jako nvarchar(4000). Każdy przykład deklaruje typ i długość odpowiadającej kolumny.
Poniższy przykład używa nazwanych parametrów, metadanych instrukcji oraz tablicy przekazanej do execute. Serwer otrzymuje @P1 nvarchar(100) i @P2 varchar(10).
$stmt = $conn->prepare('INSERT INTO dbo.Customers (Name, Code) VALUES (:name, :code)');
$stmt->setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, [
'name' => [
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR,
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 100,
],
'code' => [
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR,
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 10,
],
]);
$stmt->execute(['name' => 'Zoë Martín', 'code' => 'C-1001']);
Poniższy przykład używa symbolu zastępczego znaku zapytania oraz bindValue do znalezienia klienta po kodzie. Klucz 1 metadanych identyfikuje pierwszy symbol zastępczy. Deklarowanie varchar(10) odpowiada kolumnie Code. Gdy kolumna varchar jest porównywana z parametrem nvarchar, SQL Server konwertuje wartość kolumny, co może zapobiec wyszukiwaniu indeksu.
$stmt = $conn->prepare('SELECT CustomerID, Name FROM dbo.Customers WHERE Code = ?');
$stmt->setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, [
1 => [
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR,
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 10,
],
]);
$stmt->bindValue(1, 'C-1001', PDO::PARAM_STR);
$stmt->execute();
$customer = $stmt->fetch(PDO::FETCH_ASSOC);
echo $customer['Name'], "\n";
Poniższy przykład przekazuje tablicę deklaracji jako piąty argument elementu bindParam, przy czym 0 jest czwartym argumentem. Deklarowana długość pozostaje stała w różnych egzekucjach. Wartość dłuższa niż 10 znaków kończy się niepowodzeniem z kodem SQLSTATE 22001 i nie wstawia żadnego wiersza.
$stmt = $conn->prepare('INSERT INTO dbo.Customers (Name, Code) VALUES (?, ?)');
$name = 'Kim Abercrombie';
$code = 'C-1002';
$stmt->bindParam(1, $name, PDO::PARAM_STR, 0, [
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR,
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 100,
]);
$stmt->bindParam(2, $code, PDO::PARAM_STR, 0, [
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR,
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 10,
]);
$stmt->execute();
$name = 'Thomas Hardy';
$code = 'C-100000003';
try {
$stmt->execute();
} catch (PDOException $error) {
if ($error->getCode() !== '22001') {
throw $error;
}
echo "The code is longer than 10 characters.\n";
}
Włącz adaptacyjne dopasowywanie rozmiaru
Ustaw PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH w tablicy opcji konstruktora połączenia lub za pomocą PDO::setAttribute. Wartość musi być liczbą całkowitą od 0 do 8 000. Wartość domyślna 0 wyłącza adaptacyjne rozmiarowanie.
Każde nowe polecenie kopiuje ustawienie połączenia. Późniejsza zmiana wpływa na nowe instrukcje SQL, a nie na istniejące. Ten atrybut nie jest instrukcją ani opcją prepare.
Dla każdej kwalifikującej się pozycji parametru sterownik zaczyna od skonfigurowanej wartości minimalnej i rozwija deklarację, aby dopasować dłuższe wartości. Zachowuje największy rozmiar używany na tej pozycji, gdy później wysyłasz krótsze, puste lub wartości null. Dla danych wejściowych UTF-8 z domyślnym kodowaniem używa się nvarchar i mierzy przyrost w jednostkach kodu UTF-16. Dla wejścia kodowanego systemowo używa się varchar i rezerwuje trzy dodatkowe bajty dla każdego bajtu niebędącego ASCII, ponieważ konwersja na sortowanie UTF-8 może wydłużyć wartość. Promuje deklaracje powyżej 4 000 jednostek nvarchar lub 8 000 bajtów varchar do max, także gdy początkowa wartość minimalna przekracza ograniczony limit typu.
Deklaracje jawne mają pierwszeństwo przed adaptacyjnym rozmiarowaniem. Parametry powiązane jako liczby całkowite, dane binarne, strumienie lub parametry wyjściowe/wejściowo-wyjściowe zachowują swoje dotychczasowe zachowanie. Zmiana wnioskowanego typu SQL poprzez zmianę kodowania rozpoczyna nową historię rozmiaru dla tego parametru.
Przykład: adaptacyjne dopasowywanie rozmiaru
Poniższy przykład używa tabeli z przykładu jawnej deklaracji. Ustawia minimalną wartość 20 dla połączenia przed przygotowaniem instrukcji. Pierwsze wykonanie wysyła @P1 nvarchar(20) i @P2 nvarchar(20). Druga nazwa ma 30 znaków, więc sterownik zwiększa rozmiar @P1 do nvarchar(30). Oba parametry to nvarchar , ponieważ wejście to UTF-8, mimo że kolumna Code to varchar. Aby dopasować kolumnę varchar , użyj jawnej deklaracji.
$conn->setAttribute(PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH, 20);
$stmt = $conn->prepare('INSERT INTO dbo.Customers (Name, Code) VALUES (?, ?)');
$stmt->execute(['Ana Trujillo', 'C-1003']);
$stmt->execute(['Hanna Moos-Fernández Bergström', 'C-1004']);
Ustawienie rozmiaru kontroluje deklaracje parametrów, a nie pojemność kolumny docelowej.
Ograniczenia i błędy
- Deklaracje jawne obsługują tylko łańcuchy wejściowe oraz wartości null powiązane za pomocą
PDO::PARAM_STRlubPDO::PARAM_NULL. Odrzucają kodowanie binarne, strumienie, inne typy parametrów oraz parametry wyjściowe i wejściowo-wyjściowe. - W wersji 5.14.0 jawnie określony ograniczony varchar akceptuje tylko dane wejściowe American Standard Code for Information Interchange (ASCII). Do wprowadzania danych innych niż ASCII użyj nvarchar, varchar(max) z odpowiednią kolacją lub adaptacyjnego rozmiarowania. Adaptacyjne rozmiarowanie nie usuwa ograniczeń konwersji kolacji.
- Jawne deklaracje i adaptacyjne dopasowywanie rozmiaru nie są obsługiwane w Always Encrypted ani przy emulowanych instrukcjach prepare. Niezerowe ustawienie adaptacyjne powoduje, że tworzenie instrukcji kończy się niepowodzeniem dla każdej z tych ścieżek. Wyłącz to przed utworzeniem tych instrukcji SQL. Bezpośrednie wykonanie przez
PDO::SQLSRV_ATTR_DIRECT_QUERYróżni się od emulowanego przygotowania i wspiera te deklaracje. - Nieprawidłowe metadane, nieobsługiwane ścieżki deklaracji oraz nieprawidłowe ustawienia adaptacyjne raportują SQLSTATE
IMSSP. Dane wejściowe przekraczające prawidłowo ograniczoną deklarację zgłaszają22001. Obsługuj błędy zgodnie zPDO::ATTR_ERRMODE; przykłady zakładają tryb wyjątków. - Sterownik nie wyszukuje kolumny docelowej ani nie przepisuje twojego Transact-SQL, aby wybrać deklarację. Wybierz typy i długości odpowiadające twojemu schematowi.