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

Pobieranie sterownika PHP

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, bazą SQL w Microsoft Fabric, Azure SQL Managed Instance 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_DATABASE na 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.

• ConnectRetryCount i ConnectRetryInterval sterują ODBC odpornością 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=90 kontroluje nawiązywanie połączenia, a nie budżet 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 ustawij pdo_sqlsrv.log_severity w lub php.ini z podczas ini_set() wykonywania (runtime). Dla SQLSRV konfiguruj LogSeverity i LogSubsystems za 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 = 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. Użyj argumentu użytkownika konstruktora PDO zamiast osadzać tożsamość w DSN. 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.

• Dla skalowania odczytu lub czytelnego dodatkowego sygnału należy dodać ApplicationIntent=ReadOnly do 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 HostNameInCertificate tylko 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ź zwrot false i sprawdź przed sqlsrv_errors() podjęciem decyzji o ponownej próbie. Ustaw limity czasu zapytań osobno za pomocą QueryTimeout. Odporność na bezczynne połączenie świadczy o ponownym połączeniu ODBC, a nie o pętli powtórek na poziomie aplikacji.

• 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:

• 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 PHP: SQLSRV zapewnia funkcje proceduralne. PDO_SQLSRV implementuje PDO. Zainstaluj jedno z tych rozszerzeń lub oba.
• 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: Zarządzana tożsamość, principal 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; ActiveDirectoryServicePrincipal używa sekretu klienta.
• Always Encrypted: Szyfruj wrażliwe kolumny po stronie klienta, z bezpiecznymi enklawami obsługującymi operacje na zaszyfrowanych danych.
• Odporność połączeń: Wbudowane automatyczne ponawianie prób połączenia w stanie bezczynności z ConnectRetryCount i ConnectRetryInterval.
• Strumienie PHP: Wysyłaj duże wartości binarne i tekstowe z parametrów strumienia za pomocą dowolnego API. Używaj SQLSRV do strumieniowego pobierania.
• Obsługa typów danych Rich SQL Server: datetimeoffset, parametry tabelowe, nvarchar oraz Unicode z .PDO::SQLSRV_ENCODING_UTF8

Wprowadzenie

Konfigurowanie i łączenie

Authenticate

Secure

Pobieranie i aktualizacja danych

Typy danych

Błędy i diagnostyka

Wdrażanie i obsługa

Zawartość referencyjna

Zadania powiązane

Prośba o funkcję

Aby zażądać funkcji, otwórz problem w repozytorium Microsoft Drivers for PHP for SQL Server GitHub.

Treści powiązane

• Microsoft Drivers for PHP for SQL Server na GitHub
• Sterownik ODBC firmy Microsoft dla programu SQL Server
• Sterowniki i frameworki Microsoft SQL