Sterowniki firmy Microsoft dla języka PHP dla programu SQL Server

Pobieranie sterownika PHP

Sterowniki Microsoft for PHP for SQL Server to rozszerzenia PHP, które pozwalają czytać i zapisywać dane w Microsoft SQL Database Engine z PHP skryptów. Pakiet zawiera dwa sterowniki, które opakowują ten sam sterownik Microsoft ODBC dla SQL Server i dzielą te same opcje połączenia, więc możesz wybrać API pasujące do twojego kodu:

• SQLSRV udostępnia proceduralne API (sqlsrv_*funkcje) dostosowane do funkcji SQL Server.
• PDO_SQLSRV implementuje interfejs PHP Data Objects (PDO), dzięki czemu kod, który już używa PDO dla innych baz danych, może celować SQL Server przy minimalnych zmianach.

Oba sterowniki łączą się z Azure SQL Database, bazą SQL w Microsoft Fabric, Azure SQL Managed Instance oraz wszystkimi obsługiwanymi wersjami i edycjami SQL Server (w tym edycjami Express). Używają strumieni PHP do przenoszenia dużych wartości binarnych i znakowych bez ładowania ich całkowicie do pamięci.

Wybieranie punktu początkowego

Goal	Zacznij tutaj
Ustaw środowisko programistyczne PHP i uruchom pierwsze zapytanie	Krok 1: Konfiguruj środowisko programistyczne, następnie Krok 2: Stwórz bazę danych SQL i Krok 3: Dowód koncepcji połączenia z SQL za pomocą PHP.
Zainstaluj sterownik na Linuksie lub macOS	Tutorial instalacji dla Linuksa i macOS oraz pobierz sterowniki Microsoft do PHP dla SQL Server.
Connect to Azure SQL z uwierzytelnianiem bez hasła	Połącz się za pomocą opcji uwierzytelniania i połączenia Microsoft Entra.
Spraw, by istniejąca aplikacja była odporna na przejściowe awarie	Odporność połączenia bezczynnościowego i Krok 4: Trwałe połączenie z SQL w PHP.
Zdecyduj między SQLSRV a PDO_SQLSRV	Przegląd sterowników Microsoft dla PHP dla SQL Server oraz porównanie funkcji wykonawczych.
Zdiagnozuj problem z instalacją, połączeniem lub zapytaniem	Rozwiązywanie problemów, obsługa błędów i ostrzeżeń oraz rejestrowanie aktywności.
Przyspiesz istniejącą aplikację	Strojenie wydajności.

Szybkie połączenie

Poniższy fragment przedstawia najkrótsze połączenie end-to-end, jakie działająca instalacja PHP może uruchomić na SQL Server lub Azure SQL. Użyj go, aby potwierdzić, że sterownik, zależności ODBC i ścieżka sieciowa są podłączone, zanim przejdziesz do bazowego poziomu produkcyjnego w następnej sekcji.

<?php
$server   = getenv('SQL_SERVER')   ?: 'localhost';
$database = getenv('SQL_DATABASE') ?: 'master';
$user     = getenv('SQL_USER');
$password = getenv('SQL_PASSWORD');

$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$database;Encrypt=true";
$pdo = new PDO($dsn, $user, $password, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

foreach ($pdo->query('SELECT @@VERSION AS version') as $row) {
    echo $row['version'], PHP_EOL;
}

Aby uzyskać połączenie bez hasła przeciwko Azure SQL, dodaj Authentication=ActiveDirectoryMsi (managed identity) lub inną Authentication wartość do DSN i usuń argumenty/$user$password. Następujący po nim poziom produkcyjny rozwija ten sam schemat poprzez próby, przerwy i diagnostykę.

Dla lokalnego SQL Server, który używa certyfikatu podpisanego samodzielnie, Encrypt=true weryfikacja nie przechodzi. Dodawaj TrustServerCertificate=true tylko do lokalnego rozwoju. Zobacz błędy certyfikatów TLS dla alternatyw produkcyjnych.

Plan bazowy produkcji dla Azure SQL

Użyj tego fragmentu jako punktu wyjścia do produkcyjnego Azure SQL połączenia ze sterownikiem PDO_SQLSRV. Odczytuje serwer i bazę danych ze zmiennych środowiskowych (np. ustawienia aplikacji Azure App Service), uwierzytelnia się za pomocą zarządzanej tożsamości, włącza Transport Layer Security (TLS) z walidacją certyfikatów serwera, ustawia czas logowania obejmujący awarię zimnego startu oraz dla ConnectRetryCountConnectRetryInterval SQL Server odporność połączenia bezczynnościowego. Aplikacje connectWithRetry i pomocniki owijają queryWithRetry zarówno początkowe połączenie, jak i każde polecenie ograniczonym odchyleniem wykładniczego oraz oddzielne błędy połączenia przejściowe (wymagające nowego połączenia) od błędów zapytań przejściowych (które ponownie wykorzystują to samo połączenie).

Wymaga wersji PHP 8.0 i nowszych, rozszerzenia PDO_SQLSRV oraz sterownika ODBC Microsoft dla SQL Server wersji Authentication=ActiveDirectoryMsi17.3.1.1 i nowszych. Pełną listę obsługiwanych Authentication wartości można znaleźć w artykule Połącz za pomocą uwierzytelniania Microsoft Entra.

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

/**
 * 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); // 1, 2, 4 seconds
            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');
}

/**
 * Run a parameterized query, retrying transient statement failures on the same
 * connection. Deadlocks (1205) roll back the transaction before the driver sees
 * the error, so rerunning a single statement is safe. If the statement was part
 * of a multistatement transaction, wrap the whole transaction in your own retry
 * loop so earlier statements replay too.
 */
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, TRANSIENT_SERVER_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.');
}

$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,
    $database
);

$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 TOP (?) name FROM sys.databases ORDER BY name', [5]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Ten fragment kodu jest przystosowany do grup pracy awaryjnej Azure SQL Database oraz Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} przypina sterownik ODBC 18. Jeśli host ma zainstalowany także ODBC 17, PDO_SQLSRV może powiązać z ODBC 17. Starsze wersje 17.x odrzucają nowsze Authentication wartości; na przykład wymaga Authentication=ActiveDirectoryMsi ODBC 17.3.1.1 lub nowszej wersji. Zobacz Nieprawidłowa wartość określona dla atrybutu parametry połączenia 'Authentication'.

• ConnectRetryCountoraz ConnectRetryInterval są słowami kluczowymi ODBC parametry połączenia, które umożliwiają odporność na połączenie w trybie idle w SQL Server: sterownik transparentnie ponownie łączy uszkodzone połączenie bezczynne. To różni się od poziomu aplikacji queryWithRetry, który ponownie próbuje wykonać błędy przejściowe, takie jak zablokowanie lub czas zapytania. Te dwie rzeczy się uzupełniają, więc zachowaj oba. Upewnij LoginTimeout się, że przynajmniej ConnectRetryCount * ConnectRetryInterval ścieżka bezczynności i ponownego połączenia zdążyła osiągnąć pełny budżet; próbka wykorzystuje 90 sekund na pokrycie 5 × 15 sekund powtórek plus zapas na początkowe logowanie podczas zimnego failoveru.

• Uzupełnij wywołania na poziomie error_log() aplikacji o diagnostykę po stronie kierowcy. Dla PDO_SQLSRV ustawia pdo_sqlsrv.log_severity się w ( php.ini konfigurowalne tylko przy inicjalizacji); dla SQLSRV wywołaj sqlsrv_configure("LogSubsystems", ...) w czasie działania. 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 = 1
  

• Dla zarządzanej tożsamości przypisanej przez użytkownika przekażmy identyfikator tożsamości jako argument PDO $username (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 jej ID 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. PDO_SQLSRV odrzuca wewnątrz UID samego DSN, więc użyj slotu konstruktora. Passing null jako użytkownik (jak robi to przykład) wybiera systemowo przypisaną tożsamość zarządzaną hosta Azure. Dla SQLSRV (proceduralnego) przekaż UID pole opcji połączenia.

• Ustawiasz MultiSubnetFailover=true się, gdy łączysz się z nasłuchiwaczem grupy awaryjnej, grupą dostępności lub punktem końcowym instancji klastra awaryjnego. Ustawienie poprawia wydajność połączenia zarówno dla słuchaczy grup dostępności pojedynczej, jak i wielopodsieciowej. Więcej informacji można znaleźć w artykule Wsparcie dla wysokiej dostępności, odbudowywanie po awarii.

• Aby uzyskać skalowanie odczytu lub czytelny element wtórny, dodaj ApplicationIntent=ReadOnly do nazwy źródła danych (DSN).

• W przypadku chmur suwerennych, gdzie certyfikat Subject Alternative Name (SAN) nie zawiera hosta, do którego się łączysz, dodaj HostNameInCertificate do DSN (na przykład *.database.usgovcloudapi.net dla Azure Government).

• Sterownik opiera się na podstawowym sterowniku Microsoft ODBC dla SQL Server do pozyskiwania tokenów. Przepływy tożsamości zarządzanej, zasady usługi oraz tokenów dostępu przechodzą przez ODBC. Aby uzyskać więcej informacji, zobacz Using Microsoft Entra ID with the ODBC Driver (Używanie identyfikatora Entra firmy Microsoft ze sterownikiem ODBC).

• Dla wyższego bezpieczeństwa i przenośności między środowiskami zachowaj informacje o połączeniach poza kodem. Przechowuj informacje o połączeniach w systemie konfiguracji aplikacji i używaj Azure Key Vault do wartości wrażliwych oraz centralnie zarządzanych ustawień połączenia.

• Równoważne połączenie SQLSRV wykorzystuje sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) i zwraca zasób. Schemat powtórek jest taki sam: złap false powrót z sqlsrv_connect, sprawdź sqlsrv_errors() SQLSTATE i wycofaj się przed ponowną próbą. Przykładem roboczym zobacz Krok 4: Trwałe łączenie się z SQL za pomocą PHP.

• Pomocniki powtórek czytają $e->errorInfo[1] chronione przez isset(). PDOException::$errorInfo jest deklarowany jako i ?array domyślnie przyjmuje , nullwięc kontrola obronna wraca do kodu sterownika i 0 pozwala prefiksowi SQLSTATE 08 zdecydować, czy spróbować ponownie.

Aby uzyskać więcej informacji na temat każdej części tej konfiguracji, zobacz:

• Opcje połączenia
• Połączenie przy użyciu uwierzytelniania Microsoft Entra
• Odporność na połączenie bezczynne
• Nawiązywanie połączenia z usługą Microsoft Azure SQL Database
• Wsparcie dla wysokiej dostępności, 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, jeden pakiet sterowników: proceduralny SQLSRV dla kodu SQL Server-first lub PDO_SQLSRV dla przenośnego kodu PDO.
• 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 walidacją certyfikatu serwera kontrolowaną przez TrustServerCertificate.
• Uwierzytelnianie Microsoft Entra ID: Połączenia bezhasłowe z zarządzaną tożsamością, zasadą usługi i tokenem dostępu przepływają przez podstawowy sterownik Microsoft ODBC dla SQL Server.
• Always Encrypted: szyfrowanie po stronie klienta dla kolumn poufnych z opcjonalnymi bezpiecznymi enklawami dla operacji w miejscu.
• Odporność na połączenia: Wbudowane próby połączeń bezczynnych z ConnectRetryCount i ConnectRetryInterval.
• Strumienie PHP: Odczytuj i zapisuj duże wartości binarne i znakowe jako strumienie zamiast ładować je do pamięci.
• Obsługa typów danych Rich SQL Server: datetimeoffset, parametry tabelowe, nvarchar oraz Unicode z .PDO::SQLSRV_ENCODING_UTF8

Wprowadzenie

Artykuł	Description
Wymagania systemowe	Obsługiwane wersje PHP, systemu operacyjnego oraz SQL Server.
Tabela obsługi	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.
Poradnik instalacji dla Linuksa i macOS	Zainstaluj sterownik i jego wymagania ODBC na Linuksie i macOS.
Załadowanie sterowników	Włącz rozszerzenia w php.ini.
Rozpoczęcie pracy ze sterownikiem PHP SQL	Kompletny przewodnik, który łączy cztery etapy rozpoczęcia gry.
Przegląd sterownika SQL PHP	Co jest w pakiecie i kiedy wybrać SQLSRV lub PDO_SQLSRV.

Konfigurowanie i łączenie

Artykuł	Description
Łączenie 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.
Nawiązywanie połączenia z usługą Microsoft Azure SQL Database	Connect a PHP application to Azure SQL Database.
Połącz się na określonym porcie	Celuj w port TCP niedomyślny.
Buforowanie 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.
Obsługa bazy danych LocalDB	Połącz się z instancją SQL Server LocalDB.
Wsparcie dla wysokiej dostępności, odzyskiwania po awarii	Nasłuchiwacze grup dostępności i przełączanie awaryjne w wielu podsieciach.
Odporność na połączenie bezczynne	Automatyczne ponowne podłączenie przy zerwaniu połączeń jałowych.

Authenticate

Artykuł	Description
Połączenie przy użyciu uwierzytelniania Microsoft Entra	Toki zarządzanej tożsamości, zasady usługi, tokena dostępu i haseł.
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	Korzystaj z uwierzytelniania zintegrowanego z Windows na hostach dołączonych do domeny.

Secure

Artykuł	Description
Zagadnienia związane z zabezpieczeniami	Model zagrożeń i szczegółowe wskazówki dotyczące obrony dla aplikacji PHP.
Zawsze szyfrowane sterownikami PHP	Skonfiguruj szyfrowanie po stronie klienta dla kolumn poufnych.
Ciągłe Szyfrowanie z bezpiecznymi enklawami	Umożliwić bogate operacje na zaszyfrowanych kolumnach z bezpiecznymi enklawami.

Pobieranie i aktualizacja danych

Artykuł	Description
Przewodnik programowy	Przewodnik programowania end-to-end dla obu sterowników.
Porównywanie funkcji wykonawczych	Wybierz odpowiednią funkcję wykonawczą dopasowaną do swojego obciążenia.
Bezpośrednie i przygotowane wykonanie oświadczenia (PDO_SQLSRV)	Kiedy stosować bezpośrednie wykonanie, a kiedy przygotowane oświadczenia.
Pobieranie danych	Pobieraj wiersze, kolumny i wartości strumieniowe.
Aktualizacja danych	Wstaw, aktualizuj i usuń wiersze.
Wykonuj zapytania parametryzowane	Bind parametry, aby chronić przed SQL injection.
Wysyłaj dane jako strumień	Przesyłaj duże wartości binarne i znakowe do SQL Server.
Wykonywanie transakcji	Grupuj wypowiedzi w transakcje atomowe.
Użyj parametrów tabelowych	Przekaż TABLE parametr do procedury przechowywanej.
Określ typ kursora i wybierz wiersze	Wybierz kursory tylko do przodu, statyczne, dynamiczne lub zestawy klawiszy.

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)	Nadpisywanie typu SQL Server podczas wiązania parametrów.
Określ typy danych PHP	Nadpisuj typ PHP podczas pobierania.
Wysyłanie i pobieranie danych UTF-8	Zastosowanie PDO::SQLSRV_ENCODING_UTF8 do podróży Unicode w obie strony.
Wysyłanie i pobieranie danych ASCII na Linuksie i macOS	Obsługuję połączenia ASCII w obie strony na hostach innych niż Windows.
Format dziesiętnych i pieniędzy (SQLSRV)	Sformatuj kolumny dziesiętne i pieniężne za pomocą sterownika SQLSRV.
Format dziesiętnych i pieniądza (PDO_SQLSRV)	Formatuj kolumny dziesiętne i pieniężne z PDO_SQLSRV sterownikiem.
Ustawienia lokalizacji niezwiązane z systemem	Zlokalizowane separatory dziesiętne i inne kwestie dotyczące lokalizacji.

Błędy i diagnostyka

Artykuł	Description
Błędy i ostrzeżenia dotyczące obsługi	Obsługa błędów i ostrzeżeń z obiema sterownikami.
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.
Działalność logowania	Włącz logowanie sterowników do rejestrowania diagnostyki.

Wdrażanie i obsługa

Artykuł	Description
Dostrajanie 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.

Reference

Artykuł	Description
SQLSRV driver API reference	Wszystkie sqlsrv_* funkcje, parametry i wartości zwracane.
PDO_SQLSRV referencja kierowcy	PDO i metody 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
Informacje o wydaniu	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 sterownika PHP SQL	Przykładowe aplikacje end-to-end dla SQLSRV i PDO_SQLSRV.
Zasoby wsparcia	Społeczność i kanały wsparcia.

Treści powiązane

• Microsoft Drivers for PHP for SQL Server na GitHub
• Sterownik ODBC firmy Microsoft dla programu SQL Server
• sterowników programu SQL Server