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.
Microsoft Drivers for PHP for SQL Server to rozszerzenia PHP, których można używać do odczytu i zapisu danych w Microsoft SQL Database Engine ze skryptów PHP. Oba rozszerzenia wykorzystują ten sam sterownik Microsoft ODBC dla SQL Server, ale oferują różne API PHP oraz opcje specyficzne dla sterownika:
-
SQLSRV udostępnia proceduralne API (
sqlsrv_*funkcje) dostosowane do funkcji SQL Server. - PDO_SQLSRV implementuje interfejs PHP Data Objects (PDO). Możesz zachować wywołania PDO w istniejącym kodzie bazy danych, ale przed migracją do innej bazy danych przejrzyj jej zapytania i ustawienia specyficzne dla sterowników.
Oba sterowniki łączą się z Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, bazą danych SQL w Microsoft Fabric, Fabric Data Warehouse oraz wszystkimi obsługiwanymi wersjami i edycjami SQL Server, w tym edycjami Express. Oba sterowniki akceptują strumienie PHP jako parametry wejściowe. SQLSRV obsługuje pobieranie dużych wartości binarnych i znakowych jako strumieni. Nie zakładaj, że PDO_SQLSRV ma takie samo zachowanie strumieniowania wyjściowego.
Wybieranie punktu początkowego
- Aby zweryfikować instalację i uruchomić zapytanie parametryzowane za pomocą SQLSRV lub PDO_SQLSRV, zacznij od artykułu Szybki start: nawiązywanie połączenia i wykonywanie zapytań za pomocą sterowników Microsoft dla języka PHP.
- Aby zainstalować sterownik na Linuksie lub macOS, zacznij od samouczka instalacji dla Linuksa i macOS oraz pobierz sterowniki Microsoft dla PHP dla SQL Server.
- Aby połączyć się z Azure SQL z uwierzytelnieniem bez hasła, zacznij od Connect z użyciem uwierzytelniania Microsoft Entra oraz opcji połączenia.
- Aby uczynić istniejącą aplikację odporną na przejściowe awarie, przejdź do Idle connection resiliency.
- Aby zdecydować między SQLSRV a PDO_SQLSRV, przejdź do Przeglądu Microsoft sterowników dla PHP for SQL Server oraz Porównania funkcji wykonawczych.
- Aby zdiagnozować problem z instalacją, połączeniem lub zapytaniem, przejdź do Rozwiązywania problemów, Obsługi błędów i ostrzeżeń oraz Logowania aktywności.
- Aby przyspieszyć istniejącą aplikację, przejdź do Performance Tuning.
Plan bazowy produkcji dla Azure SQL
Ten przykład PDO_SQLSRV odczytuje serwer i bazę danych ze zmiennych środowiskowych i łączy się z zarządzaną tożsamością. Buduje nazwę źródła danych (DSN) i włącza zabezpieczenia Transport Layer Security (TLS) z walidacją certyfikatów. Odczytuj te wartości z zaufanej konfiguracji aplikacji, a nie z parametrów zapytania webowego. Uruchom program na hoście z endpointem zarządzanej tożsamości po przyznaniu tożsamości dostępu do bazy danych.
Funkcje pomocnicze wykonują do trzech prób połączenia lub uruchomienia zapytania tylko do odczytu, gdy pojawi się wymieniony błąd. Czekają dłużej między próbami, co jest wzorcem ponawiania zwanym wykładniczym opóźnieniem ponowienia. Jeśli błąd zapytania wymaga nowego połączenia, pomocnik zapytania rzuca wyjątek, który kod wywołujący ma obsłużyć do obsłudzenia.
Użyj obsługiwanej wersji PHP, rozszerzenia PDO_SQLSRV oraz sterownika Microsoft ODBC Driver 18 for SQL Server. Obsługiwane wartości uwierzytelniania można znaleźć w Połącz za pomocą uwierzytelniania Microsoft Entra. Nie używaj ponownie pomocnika zapytań do zapisów lub transakcji wieloinstrukcyjnych bez zaprojektowania specyficznej dla aplikacji polityki ponownej próby: błąd nie zawsze informuje, czy zapis został zatwierdzony.
<?php
declare(strict_types=1);
// Transient errors that require a fresh connection to recover. SQLSTATE values
// starting with '08' cover ODBC connection-established and connection-broken
// states (for example, 08001, 08S01).
const CONNECT_RETRY_SQLSTATE_PREFIX = '08';
// SQL Server error codes that are transient regardless of when they surface:
// 1205 (deadlock victim), 1222 (lock request timeout), and the Azure SQL
// throttling, mid-query failover, and "database not currently available"
// codes that arrive with SQLSTATE HY000.
const TRANSIENT_SERVER_ERROR_CODES = [1205, 1222, 40501, 40613, 40197, 10928, 10929, 49918];
// This read helper retries only the listed errors on the same connection.
// Other errors propagate; the caller must decide whether to reconnect.
const RETRYABLE_READ_ERROR_CODES = [1205, 1222, 40501, 10928, 10929];
/**
* Open a connection, retrying transient failures with exponential backoff.
*/
function connectWithRetry(string $dsn, array $options, int $maxAttempts = 3): PDO
{
for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
try {
$pdo = new PDO($dsn, null, null, $options);
error_log(sprintf('connected on attempt %d/%d', $attempt, $maxAttempts));
return $pdo;
} catch (PDOException $e) {
$sqlstate = (string) $e->getCode();
$driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
$isTransient = str_starts_with($sqlstate, CONNECT_RETRY_SQLSTATE_PREFIX)
|| in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
if (!$isTransient || $attempt === $maxAttempts) {
error_log(sprintf('connect failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
throw $e;
}
$delay = 2 ** ($attempt - 1);
error_log(sprintf('connect attempt %d hit transient %s/%d; retrying in %d seconds', $attempt, $sqlstate, $driverCode, $delay));
sleep($delay);
}
}
throw new RuntimeException('connectWithRetry exhausted retries');
}
/**
* Retry the standalone read-only query for errors that allow connection reuse.
*/
function queryWithRetry(PDO $pdo, string $sql, array $params = [], int $maxAttempts = 3): PDOStatement
{
for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
try {
$stmt = $pdo->prepare($sql);
$stmt->execute($params);
return $stmt;
} catch (PDOException $e) {
$driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
$isTransient = in_array($driverCode, RETRYABLE_READ_ERROR_CODES, true);
if (!$isTransient || $attempt === $maxAttempts) {
error_log(sprintf('query failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
throw $e;
}
$delay = 2 ** ($attempt - 1);
error_log(sprintf('query attempt %d hit transient code %d; retrying in %d seconds', $attempt, $driverCode, $delay));
sleep($delay);
}
}
throw new RuntimeException('queryWithRetry exhausted retries');
}
// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;
if ($server === null || $database === null) {
throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE in your application configuration.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$dsn = sprintf(
'sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=%s;Database=%s;'
. 'Encrypt=true;TrustServerCertificate=false;'
. 'LoginTimeout=90;Authentication=ActiveDirectoryMsi;'
. 'ConnectRetryCount=5;ConnectRetryInterval=15;'
. 'MultiSubnetFailover=true;',
$server,
$databaseValue
);
$options = [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
PDO::ATTR_EMULATE_PREPARES => false,
PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 30,
];
$pdo = connectWithRetry($dsn, $options);
$stmt = queryWithRetry($pdo, 'SELECT name FROM sys.databases WHERE database_id > ? ORDER BY name', [1]);
foreach ($stmt as $row) {
echo $row['name'], PHP_EOL;
}
Używaj tych ustawień dla grup trybu failover Azure SQL Database oraz Azure SQL Managed Instance.
Driver={ODBC Driver 18 for SQL Server}wybiera sterownik ODBC 18 jawnie, zamiast polegać na wykrywaniu sterowników. Zainstaluj go przed uruchomieniem przykładu.Ustaw
SQL_DATABASEna rzeczywistą nazwę bazy danych. Program podwaja zamykające nawiasy i ujmuje nazwę w nawiasy klamrowe przed umieszczeniem jej w DSN. Escaping zapobiega temu, aby znaki specjalne w nazwie zmieniały sposób, w jaki sterownik odczytuje ustawienia połączenia.ConnectRetryCountorazConnectRetryIntervalkontrolują ODBC odporność bezczynnego połączenia. Limit czasu zapytania instrukcji ogranicza odzyskiwanie po awarii podczas wykonywania. Przy 30-sekundowym przemiancie zapytania próbki ODBC może zatrzymać się przed wyczerpaniem wszystkich pięciu prób ponownego połączenia.LoginTimeout=90kontroluje nawiązywanie połączenia, a nie limit odzyskiwania. Pomocnik na poziomie aplikacji ponawia próby przy wybranych błędach serwera; nie ponawia próby po przekroczeniu limitu czasu zapytania ani nie odtwarza częściowo pobranych wyników.Włącz logowanie sterowników obok wywołań programu
error_log(). Dla PDO_SQLSRV ustawijpdo_sqlsrv.log_severityw lubphp.iniz podczasini_set()wykonywania (runtime). Dla SQLSRV konfigurujLogSeverityiLogSubsystemsza pomocąsqlsrv_configure(). Więcej informacji można znaleźć w sekcji Aktywność rejestrowa.; php.ini - enable PDO_SQLSRV driver diagnostics alongside the application-level ; error_log() calls in the sample. Use 1 (errors) in production; -1 (all) is ; useful during triage but very chatty. [pdo_sqlsrv] pdo_sqlsrv.log_severity = 1W przypadku zarządzanej tożsamości przypisanej przez użytkownika przekaż identyfikator tożsamości jako argument
$usernamePDO (new PDO($dsn, $identityId, null, $options)). Użyj identyfikatora klienta tożsamości na Azure App Service lub Azure Container Instance; w przeciwnym razie użyj identyfikatora obiektu. Sterowniki PHP dziedziczą to zachowanie po podstawowym sterowniku Microsoft ODBC dla SQL Server; więcej informacji można znaleźć w artykule Using Microsoft Entra ID with the ODBC Driver. Użyj argumentu użytkownika konstruktora PDO zamiast osadzać tożsamość w DSN. Przekazanienulljako użytkownika (jak w przykładzie) powoduje wybranie tożsamości zarządzanej hosta Azure przypisanej przez system. W przypadku SQLSRV (w wersji proceduralnej) przekażUIDw tablicy opcji połączenia.Ustaw
MultiSubnetFailover=true, gdy łączysz się z odbiornikiem grupy trybu failover, odbiornikiem grupy dostępności lub punktem końcowym instancji klastra trybu failover. Ustawienie tej opcji poprawia wydajność połączeń zarówno dla detektorów grup dostępności w konfiguracjach z jedną podsiecią, jak i wieloma podsieciami. Więcej informacji można znaleźć w artykule Wsparcie dla wysokiej dostępności, odbudowywanie po awarii.Dla skalowania odczytu lub czytelnego dodatkowego sygnału należy dodać
ApplicationIntent=ReadOnlydo DSN.Korzystaj z punktu końcowego dostarczanego przez usługę SQL, wraz z właściwą dla chmury domeną. Zbadaj niezgodności między nazwami certyfikatów zamiast wyłączać walidację certyfikatów. Używaj
HostNameInCertificatetylko wtedy, gdy znasz oczekiwaną nazwę certyfikatu dla danego punktu końcowego.ODBC pozyskuje tokeny do uwierzytelniania zarządzanej tożsamości i podmiotu usługi. Przy
AccessToken, twoja aplikacja przejmuje token i przekazuje go sterownikowi; ODBC nie pobiera go za ciebie. Aby uzyskać więcej informacji, zobacz Using Microsoft Entra ID with the ODBC Driver (Używanie identyfikatora Entra firmy Microsoft ze sterownikiem ODBC).Trzymaj informacje o połączeniu poza swoim kodem. Zapisz go w systemie konfiguracyjnym aplikacji i użyj Azure Key Vault do sekretów.
W SQLSRV ustaw opcje połączenia w tablicy przekazywanej do
sqlsrv_connect(). Sprawdź zwrotfalsei sprawdź przedsqlsrv_errors()podjęciem decyzji o ponownej próbie. Ustaw limity czasu zapytań osobno za pomocąQueryTimeout. Odporność bezczynnego połączenia demonstruje ponowne połączenie ODBC, a nie pętlę ponowień na poziomie aplikacji.Funkcje pomocnicze ponawiania odczytują
$e->errorInfo[1], zabezpieczone przezisset().PDOException::$errorInfojest deklarowany jako?arrayi domyślnie ma wartośćnull, więc defensywny check przechodzi na kod sterownika0i pozwala prefiksowi SQLSTATE08zdecydować, czy spróbować ponownie.
Aby uzyskać więcej informacji na temat każdej części tej konfiguracji, zobacz:
- Opcje połączenia
- Połącz się za pomocą uwierzytelniania Microsoft Entra
- Odporność nieaktywnego połączenia
- Łączenie z Microsoft Azure SQL Database
- Wsparcie dla wysokiej dostępności i odzyskiwania po awarii
Aby zapoznać się z wykazem błędów przejściowych Azure SQL, zobacz Rozwiązywanie problemów z przejściowymi błędami połączenia.
Kluczowe funkcje
- Dwa API PHP: SQLSRV oferuje funkcje proceduralne. PDO_SQLSRV implementuje PDO. Zainstaluj jedno z tych rozszerzeń lub oba.
- Szerokie wsparcie platformowe: działa na Windows, Linux i macOS z obsługiwanymi wersjami PHP.
-
Połączenia szyfrowane: połączenia szyfrowane TLS przez
Encrypt=true, z weryfikacją certyfikatu serwera kontrolowaną przezTrustServerCertificate. -
Uwierzytelnianie Microsoft Entra ID: Zarządzana tożsamość, podmiot usługi oraz zewnętrzne tokeny dostępu za pomocą podstawowego sterownika Microsoft ODBC dla SQL Server. Tożsamość zarządzana nie wymaga hasła;
ActiveDirectoryServicePrincipalużywa sekretu klienta. - Always Encrypted: Szyfruj wrażliwe kolumny na kliencie, z bezpiecznymi enklawami do obsługiwanych operacji na zaszyfrowanych danych.
-
Odporność połączenia: Wbudowane ponowne próby dla bezczynnych połączeń za pomocą
ConnectRetryCountiConnectRetryInterval. - Strumienie PHP: Wysyłaj duże wartości binarne i znakowe z parametrów strumienia za pomocą dowolnego API. Używaj SQLSRV do strumieniowego pobierania.
-
Rozbudowana obsługa typów danych SQL Server: datetimeoffset, parametry tabelaryczne, nvarchar oraz Unicode z
PDO::SQLSRV_ENCODING_UTF8.
Wprowadzenie
| Artykuł | Description |
|---|---|
| Wymagania systemowe | Obsługiwane wersje PHP, systemu operacyjnego oraz SQL Server. |
| Macierz zgodności | Szczegółowa matryca kompatybilności dla wydań sterowników PHP. |
| Pobierz sterowniki Microsoft dla PHP dla SQL Server | Linki do pobrania i wypuszczanie artefaktów. |
| Samouczek instalacji dla Linux i macOS | Zainstaluj sterownik i jego wymagania ODBC na Linuksie i macOS. |
| Ładowanie sterowników | Włącz rozszerzenia w php.ini. |
| Szybki start: Połącz się i wykonuj zapytania za pomocą sterowników Microsoft dla PHP | Zweryfikować rozszerzenia, skonfigurować połączenie i uruchomić to samo parametryzowane zapytanie za pomocą SQLSRV lub PDO_SQLSRV. |
| Przegląd sterownika SQL PHP | Co jest w pakiecie i kiedy wybrać SQLSRV lub PDO_SQLSRV. |
Konfigurowanie i łączenie
| Artykuł | Description |
|---|---|
| Łączenie się z serwerem | Otwórz połączenie z instancją SQL Server z PHP. |
| Opcje połączenia | Pełne informacje o kluczach kluczowych połączenia, domyślnych ustawieniach i sposobach ich ustawiania. |
| Łączenie z Microsoft Azure SQL Database | Połącz aplikację PHP z bazą danych Azure SQL Database. |
| Połącz się na określonym porcie | Wskaż niestandardowy port TCP. |
| Pula połączeń | Ponownie wykorzystaj połączenia ODBC na żądaniach PHP. |
| Wyłącz wiele aktywnych zestawów wyników (MARS) | Wyłącz MARS dla kompatybilności. |
| Wsparcie dla LocalDB | Połącz się z instancją SQL Server LocalDB. |
| Wsparcie dla wysokiej dostępności i odzyskiwania po awarii | Nasłuchiwacze grup dostępności i przełączanie awaryjne w wielu podsieciach. |
| Odporność nieaktywnego połączenia | Automatyczne ponowne łączenie zerwanych nieaktywnych połączeń. |
Authenticate
| Artykuł | Description |
|---|---|
| Połącz się za pomocą uwierzytelniania Microsoft Entra | Przepływy zarządzanej tożsamości, jednostki usługi, tokenu dostępu i hasła. |
| Połącz się za pomocą uwierzytelniania SQL Server | Użyj logowania SQL z nazwą użytkownika i hasłem. |
| Połącz się za pomocą Windows authentication | Używaj zintegrowanej autentykacji na Windows lub Kerberos na Linuksie i macOS. |
Secure
| Artykuł | Description |
|---|---|
| Zagadnienia dotyczące zabezpieczeń | Model zagrożeń i szczegółowe wskazówki dotyczące obrony dla aplikacji PHP. |
| Always Encrypted za pomocą sterowników PHP | Skonfiguruj szyfrowanie po stronie klienta dla kolumn poufnych. |
| Always Encrypted z bezpiecznymi enklawami | Włącz zaawansowane operacje na zaszyfrowanych kolumnach przy użyciu bezpiecznych enklaw. |
Pobieranie i aktualizacja danych
| Artykuł | Description |
|---|---|
| Przewodnik programowania | Znajdź zadania programistyczne dla obu kierowców. |
| Porównywanie funkcji wykonawczych | Wybierz odpowiednią funkcję wykonawczą dopasowaną do swojego obciążenia. |
| Bezpośrednie i przygotowane wykonanie instrukcji (PDO_SQLSRV) | Kiedy stosować bezpośrednie wykonanie, a kiedy przygotowane oświadczenia. |
| Pobieranie danych | Pobieraj wiersze, kolumny i wartości przesyłane strumieniowo. |
| Aktualizowanie danych | Wstaw, aktualizuj i usuń wiersze. |
| Wykonuj zapytania parametryzowane | Powiąż parametry, aby zabezpieczyć się przed wstrzyknięciem SQL. |
| Wysyłanie danych jako strumienia | Przesyłaj duże wartości binarne i znakowe do SQL Server. |
| Wykonuj transakcje | Zatwierdź lub wycofaj grupę instrukcji razem. |
| Używaj parametrów tabelarycznych | Przekaż TABLE parametr do procedury przechowywanej. |
| Określ typ kursora i wybierz wiersze | Wybierz kursory przewijane tylko do przodu, statyczne, dynamiczne lub oparte na kluczu. |
Typy danych
| Artykuł | Description |
|---|---|
| Konwersja typów danych | Jak sterownik mapuje typy PHP na typy SQL Server. |
| Domyślne typy danych SQL Server | Domyślny typ SQL Server dla każdej wartości PHP. |
| Domyślne typy danych PHP | Domyślny typ PHP dla każdego typu kolumny SQL Server. |
| Określ typy danych SQL Server (SQLSRV) | Zastąp typ SQL Server podczas wiązania parametrów. |
| Określ typy danych PHP | Nadpisuj typ PHP podczas pobierania. |
| Wysyłanie i pobieranie danych UTF-8 | Ustaw opcję CharacterSet SQLSRV lub atrybut PDO::SQLSRV_ATTR_ENCODING PDO_SQLSRV. |
| Wysyłanie i pobieranie danych ASCII na Linux i macOS | Obsługuję połączenia ASCII w obie strony na hostach innych niż Windows. |
| Formatowanie liczb dziesiętnych i pieniędzy (SQLSRV) | Sformatuj kolumny dziesiętne i pieniężne za pomocą sterownika SQLSRV. |
| Formatowanie wartości dziesiętnych i pieniężnych (PDO_SQLSRV) | Formatuj kolumny decimal i money za pomocą sterownika PDO_SQLSRV. |
| Niesystemowe ustawienia regionalne | Lokalne separatory dziesiętne i inne uwarunkowania regionalne. |
Błędy i diagnostyka
| Artykuł | Description |
|---|---|
| Obsługa błędów i ostrzeżeń | Obsługa błędów i ostrzeżeń w obu sterownikach. |
| Konfiguracja obsługi błędów i ostrzeżeń (SQLSRV) | Dostosuj sposób, w jaki sterownik SQLSRV zgłasza błędy i ostrzeżenia. |
| Obsługa błędów i ostrzeżeń (SQLSRV) | Inspekcja błędów zwracanych przez funkcje SQLSRV. |
| Aktywność rejestrowania | Włącz logowanie sterowników w celu przechwytywania danych diagnostycznych. |
Wdrażanie i obsługa
| Artykuł | Description |
|---|---|
| Strojenie wydajności | Zarządzanie połączeniami, grupowanie, przygotowane instrukcje, kursory, pamięć oraz monitorowanie po stronie serwera. |
| Troubleshooting | Zdiagnozuj typowe problemy z instalacją, połączeniem, zapytaniem, typem danych, transakcją i kontenerem. |
Zawartość referencyjna
| Artykuł | Description |
|---|---|
| Odniesienie do API sterownika SQLSRV | Wszystkie sqlsrv_* funkcje, parametry i wartości zwracane. |
| Dokumentacja sterownika PDO_SQLSRV | Metody PDO i PDOStatement obsługiwane przez sterownik PDO_SQLSRV. |
| Stałe | Stałe ujawniane przez sterowniki, w tym stałe typu i kodowania. |
Zadania powiązane
| Artykuł | Description |
|---|---|
| Notatki z wydania | Historia każdej wersji z nowymi funkcjami, poprawkami błędów, zmianami wsparcia platformy i linkami do pobrania. |
| O przykładach kodu w dokumentacji | Konwencje stosowane przez przykłady kodu w tej sekcji. |
| Przykłady kodu dla sterownika SQL PHP | Przykładowe aplikacje end-to-end dla SQLSRV i PDO_SQLSRV. |
| Pomoc i zasoby | Społeczność i kanały wsparcia. |
Prośba o funkcję
Aby zażądać funkcji, otwórz problem w repozytorium Microsoft Drivers for PHP for SQL Server GitHub.