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

Pobieranie sterownika PHP

Sterowniki firmy Microsoft dla PHP do programu SQL Server to rozszerzenia PHP, które umożliwiają odczytywanie i zapisywanie danych z aparatu bazy danych Microsoft SQL Database Engine w skryptach PHP. 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

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 (na przykład z ustawień aplikacji usługi Azure App Service), uwierzytelnia się przy użyciu zarządzanej tożsamości, włącza zabezpieczenia Transport Layer Security (TLS) z walidacją certyfikatu serwera, ustawia limit czasu logowania uwzględniający przełączenie awaryjne przy zimnym starcie oraz ustawia ConnectRetryCount i ConnectRetryInterval na potrzeby odporności bezczynnych połączeń SQL Server. Pomocniki connectWithRetry i queryWithRetry na poziomie aplikacji stosują ograniczony wykładniczy mechanizm ponawiania zarówno przy początkowym nawiązywaniu połączenia, jak i przy każdej instrukcji, a także rozróżniają przejściowe błędy połączenia (wymagające nowego połączenia) od przejściowych błędów zapytań (które wykorzystują ponownie 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ę wartości obsługiwanych przez Authentication można znaleźć w artykule Łączenie przy użyciu 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 odróżnia się od mechanizmu na poziomie aplikacji queryWithRetry, który ponawia próbę wykonania instrukcji, gdy kończy się ona niepowodzeniem z powodu błędu przejściowego, takiego jak zakleszczenie lub przekroczenie limitu czasu zapytania. Te dwie rzeczy się uzupełniają, więc zachowaj oba. Upewnij się, że LoginTimeout wynosi co najmniej ConnectRetryCount * ConnectRetryInterval, aby ścieżka ponownego łączenia po bezczynności miała do dyspozycji pełny budżet czasowy; w przykładzie użyto 90 sekund, aby uwzględnić 5 × 15 sekund ponowień oraz zapas na początkowe logowanie podczas zimnego przełączenia awaryjnego.

  • Uzupełnij wywołania na poziomie aplikacji error_log() o diagnostykę po stronie sterownika. Dla PDO_SQLSRV ustaw pdo_sqlsrv.log_severity w php.ini (możliwe do ustawienia tylko podczas inicjalizacji); dla SQLSRV wywołaj sqlsrv_configure("LogSubsystems", ...) w czasie wykonywania. 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

  • W przypadku zarządzanej tożsamości przypisanej przez użytkownika przekaż identyfikator tożsamości jako argument $username PDO (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. PDO_SQLSRV odrzuca UID wewnątrz samego DSN, więc użyj argumentu konstruktora. Przekazanie null jako 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ż UID w 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.

  • 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. Tożsamość zarządzana, jednostka usługi i przepływy tokenów dostępu są obsługiwane 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ład znajdziesz w sekcji Krok 4: Niezawodne połączenie z SQL za pomocą PHP.

  • Funkcje pomocnicze ponawiania odczytują $e->errorInfo[1], zabezpieczone przez isset(). PDOException::$errorInfo jest zadeklarowane jako ?array i domyślnie ma wartość null, więc sprawdzenie zabezpieczające używa domyślnie kodu sterownika 0 i pozwala prefiksowi SQLSTATE 08 zdecydować, czy ponowić próbę.

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

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.
  • Obsługa wielu platform: działa w systemach Windows, Linux i macOS dla obsługiwanych wersji 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ść połączeń: Wbudowane automatyczne ponawianie prób połączenia w stanie bezczynności 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.
Ł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 Połącz aplikację PHP z bazą danych Azure SQL Database.
Połącz się na określonym porcie Wskaż niestandardowy port TCP.
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 łączenie zerwanych nieaktywnych połączeń.

Authenticate

Artykuł Description
Połączenie przy użyciu 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 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 Włącz zaawansowane operacje na zaszyfrowanych kolumnach przy użyciu bezpiecznych enklaw.

Pobieranie i aktualizacja danych

Artykuł Description
Przewodnik programowy Kompleksowy przewodnik programowania dla obu sterowników.
Porównywanie funkcji wykonawczych Wybierz odpowiednią funkcję wykonawczą dopasowaną do swojego obciążenia.
Bezpośrednie wykonywanie instrukcji oraz wykonywanie przygotowanych instrukcji (PDO_SQLSRV) Kiedy stosować bezpośrednie wykonanie, a kiedy przygotowane oświadczenia.
Pobieranie danych Pobieraj wiersze, kolumny i wartości przesyłane strumieniowo.
Aktualizacja danych Wstaw, aktualizuj i usuń wiersze.
Wykonuj zapytania parametryzowane Powiąż parametry, aby zabezpieczyć się przed wstrzyknięciem SQL.
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 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 Użyj PDO::SQLSRV_ENCODING_UTF8 do konwersji 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.
Formatowanie liczb dziesiętnych i wartości pieniężnych (SQLSRV) Sformatuj kolumny dziesiętne i pieniężne za pomocą sterownika SQLSRV.
Formatuj liczby dziesiętne i kwoty pieniężne (PDO_SQLSRV) Formatuj kolumny decimal i money za pomocą sterownika PDO_SQLSRV.
Ustawienia lokalizacji niezwiązane z systemem Lokalne separatory dziesiętne i inne uwarunkowania regionalne.

Błędy i diagnostyka

Artykuł Description
Błędy i ostrzeżenia dotyczące obsługi 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.
Działalność logowania Włącz logowanie sterowników w celu przechwytywania danych diagnostycznych.

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.

Zawartość referencyjna

Artykuł Description
SQLSRV driver API reference 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.
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

  • Last updated on