Ovladače Microsoftu pro PHP pro SQL Server

Stáhnout ovladač PHP

Microsoft Drivers for PHP for SQL Server jsou rozšíření PHP, která umožňují číst a zapisovat data v Microsoft SQL Database Engine přímo z PHP skriptů. Balíček obsahuje dva ovladače, které obsahují stejný Microsoft ODBC ovladač pro SQL Server a sdílejí stejné možnosti připojení, takže si můžete vybrat API, které odpovídá vašemu kódu:

  • SQLSRV nabízí procedurální API (sqlsrv_*funkce) přizpůsobené funkcím SQL Server.
  • PDO_SQLSRV implementuje rozhraní PHP Data Objects (PDO), takže kód, který již používá PDO pro jiné databáze, může cílit SQL Server s minimálními změnami.

Oba ovladače se připojují k Azure SQL Database, SQL databázi v Microsoft Fabric, Azure SQL Managed Instance a ke všem podporovaným verzím a edicím SQL Server (včetně Express edic). Používají PHP streamy k přesunu velkých binárních a znakových hodnot, aniž by je načítaly zcela do paměti.

Výběr výchozího bodu

Směrný plán výroby pro Azure SQL

Použijte tento úryvek jako výchozí bod pro produkčně orientované Azure SQL spojení s ovladačem PDO_SQLSRV. Načítá server a databázi z proměnných prostředí (například z nastavení aplikace ve službě Azure App Service), ověřuje se pomocí spravované identity, povoluje zabezpečení TLS s ověřením certifikátu serveru, nastavuje časový limit přihlášení, který pokrývá převzetí služeb při selhání po studeném startu, a nastavuje ConnectRetryCount a ConnectRetryInterval pro odolnost nečinných připojení SQL Serveru. Pomocné funkce connectWithRetry a queryWithRetry na aplikační úrovni používají jak pro počáteční připojení, tak pro každý příkaz mechanismus omezeného exponenciálního backoffu a rozlišují mezi přechodnými chybami připojení (které vyžadují nové připojení) a přechodnými chybami dotazů (které využívají totéž připojení).

Vyžaduje verze PHP 8.0 a novější, rozšíření PDO_SQLSRV a Microsoft ODBC ovladač pro SQL Server verze 17.3.1.1 a pozdější pro Authentication=ActiveDirectoryMsi. Pro úplný seznam podporovaných Authentication hodnot viz Připojit pomocí autentizace 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;
}

Tato ukázka kódu je přizpůsobena pro skupiny převzetí služeb při selhání ve službě Azure SQL Database a pro Azure SQL Managed Instance.

  • Driver={ODBC Driver 18 for SQL Server} připíná driver ODBC 18. Pokud má hostitel také nainstalovaný ODBC 17, může PDO_SQLSRV navázat na ODBC 17. Starší verze 17.x odmítají novější Authentication hodnoty; například vyžaduje Authentication=ActiveDirectoryMsi ODBC 17.3.1.1 nebo novější verzi. Viz Neplatná hodnota specifikovaná pro atribut připojovací řetězec 'Authentication'.

  • ConnectRetryCount a ConnectRetryInterval jsou klíčová slova připojovacího řetězce ODBC, která v SQL Serveru umožňují odolnost nečinného připojení: ovladač transparentně znovu naváže přerušené nečinné připojení. To se liší od queryWithRetry na aplikační úrovni, který zopakuje příkaz, jenž selže kvůli přechodné chybě, jako je uvíznutí nebo vypršení časového limitu dotazu. Oba jsou vzájemně doplňující, takže si nechte obojí. Ujistěte se, že LoginTimeout je alespoň ConnectRetryCount * ConnectRetryInterval, aby mechanismus opětovného připojení po nečinnosti měl k dispozici celý vyhrazený čas; ukázka používá 90 sekund na pokrytí 5 × 15 sekund opakovaných pokusů plus rezervu pro počáteční přihlášení při studeném převzetí služeb při selhání.

  • Doplňte volání na úrovni error_log() aplikace diagnostikou na straně řidiče. Pro PDO_SQLSRV nastavte pdo_sqlsrv.log_severity v php.ini (lze nastavit pouze při inicializaci); pro SQLSRV volejte sqlsrv_configure("LogSubsystems", ...) za běhu. Pro více informací viz Aktivita zaznamenávání.

    ; 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

  • Pro spravovanou identitu přiřazenou uživatelem předejte ID této identity jako argument $username PDO (new PDO($dsn, $identityId, null, $options)). Použijte ID klienta identity na Azure App Service nebo Azure Container Instance; jinak použijte její ID objektu. PHP ovladače dědí toto chování z podkladového Microsoft ODBC ovladače pro SQL Server; pro více informací viz Použití Microsoft Entra ID s ovladačem ODBC. PDO_SQLSRV odmítá UID uvnitř samotného DSN, proto použijte parametr konstruktoru. Procházením null jako uživatel (jak to dělá ukázka) vybírá systémově přiřazenou spravovanou identitu hostitele Azure. Pro SQLSRV (procedurální) předejte UID v poli možností připojení.

  • Nastavte MultiSubnetFailover=true při připojení k naslouchacímu procesu skupiny převzetí služeb při selhání, naslouchacímu procesu skupiny dostupnosti nebo koncovému bodu instance clusteru převzetí služeb při selhání. Nastavení této možnosti zlepšuje výkon připojení jak pro naslouchače skupiny dostupnosti v jedné podsíti, tak i ve více podsítích. Pro více informací viz Podpora vysoké dostupnosti, obnova po havárii.

  • Pro škálování čtení nebo čitelnou sekundární hodnotu přidejte ApplicationIntent=ReadOnly k názvu zdroje dat (DSN).

  • Pro suverénní cloudy, kde certifikát Subject Alternative Name (SAN) neobsahuje hostitele, ke kterému se připojujete, přidejte HostNameInCertificate do DSN (například *.database.usgovcloudapi.net pro Azure Government).

  • Ovladač spoléhá na základní Microsoft ODBC Driver for SQL Server pro získávání tokenů. Spravovaná identita, instanční objekt služby a toky přístupových tokenů všechny probíhají přes ODBC. Další informace naleznete v tématu Použití rozhraní Microsoft Entra ID s ovladačem ODBC.

  • Pro vyšší bezpečnost a přenosnost mezi prostředími udržujte informace o připojení mimo svůj kód. Ukládejte informace o připojení do konfiguračního systému vaší aplikace a používejte Azure Key Vault pro citlivé hodnoty a centrálně spravovaná nastavení připojení.

  • Ekvivalentní SQLSRV spojení používá sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) a vrací zdroj. Vzorec opakování pokusu je stejný: zachytit návratovou hodnotu false z sqlsrv_connect, zkontrolovat v sqlsrv_errors() hodnotu SQLSTATE a před dalším pokusem počkat. Pro praktický příklad viz Krok 4: Odolné připojení k SQL pomocí PHP.

  • Pomocné funkce pro opakování načítají $e->errorInfo[1], chráněné pomocí isset(). PDOException::$errorInfo je deklarován jako ?array a má výchozí hodnotu null, takže obranná kontrola použije jako záložní kód ovladače 0 a ponechá na prefixu SQLSTATE 08, aby rozhodl, zda se má operace opakovat.

Další informace o jednotlivých částech této konfigurace najdete tady:

Katalog Azure SQL přechodných chyb naleznete v tématu Řešení přechodných chyb připojení.

Klíčové funkce

  • Dvě API, jeden balíček ovladačů: procedurální SQLSRV pro SQL Server-first kód, nebo PDO_SQLSRV pro přenosný PDO kód.
  • Široká podpora platform: Běží na Windows, Linuxu a macOS s podporovanými verzemi PHP.
  • Šifrovaná spojení: TLS-šifrovaná spojení přes Encrypt=true, přičemž ověřování serverového certifikátu je řízeno .TrustServerCertificate
  • Autentizace Microsoft Entra ID: Bezheslová spojení s řízenou identitou, principem služby a přístupovým tokenem proudí přes základní ovladač Microsoft ODBC pro SQL Server.
  • Always Encrypted: Šifrování na straně klienta pro citlivé sloupce s volitelnými zabezpečenými enklávy pro místní operace.
  • Odolnost spojení: Vestavěné opakované pokusy o nečinné spojení s ConnectRetryCount a ConnectRetryInterval.
  • PHP streamy: Čtěte a zapisujte velké binární a znakové hodnoty jako proudy místo jejich načítání do paměti.
  • Podpora datových typů Rich SQL Server: datetimeoffset, tabulkové parametry, nvarchar a Unicode s PDO::SQLSRV_ENCODING_UTF8.

Začínáme

Článek Description
Systémové požadavky Podporoval verze PHP, operačního systému a SQL Server.
Matice podpory Podrobná kompatibilitní matice pro vydání PHP ovladačů.
Stáhněte si Microsoft ovladače pro PHP pro SQL Server Odkazy ke stažení a vydání artefaktů.
Instalační tutoriál pro Linux a macOS Nainstalujte ovladač a jeho požadavky na ODBC na Linux a macOS.
Načítání ovladačů Povolte rozšíření v php.ini.
Začínám s PHP SQL ovladačem Komplexní návod, který propojuje čtyři úvodní kroky do jednoho celku.
Přehled SQL ovladače PHP Co je v balíčku a kdy zvolit SQLSRV nebo PDO_SQLSRV.

Konfigurace a připojení

Článek Description
Připojení k serveru Otevřete připojení k instanci SQL Server z PHP.
Možnosti připojení Kompletní reference na klíčová slova spojení, výchozí nastavení a jak je nastavit.
Připojení ke službě Microsoft Azure SQL Database Připojení aplikace PHP k Azure SQL Database
Připojte se na určený port Zaměřte se na nevýchozí TCP port.
Sdružování připojení Opakovaně používejte připojení ODBC mezi požadavky PHP.
Zakázat více aktivních sad výsledků (MARS) Vypněte MARS kvůli kompatibilitě.
Podpora pro LocalDB Připojte se k instanci SQL Server LocalDB.
Podpora vysoké dostupnosti, obnova po havárii Naslouchací procesy skupin dostupnosti a převzetí služeb při selhání ve více podsítích
Odolnost nečinného spojení Automatické opětovné připojení pro přerušená nečinná spojení.

Authenticate

Článek Description
Připojte se pomocí ověřování Microsoft Entra Spravovaná identita, principál služby, přístupový token a tok hesel.
Připojte se pomocí autentizace SQL Server Použijte SQL přihlášení s uživatelským jménem a heslem.
Připojte se pomocí Windows authentication Používejte integrovanou autentizaci Windows na hostitelích připojených k doméně.

Secure

Článek Description
Aspekty zabezpečení Model hrozeb a podrobné obranné pokyny pro PHP aplikace.
Vždy šifrováno pomocí PHP ovladačů Nakonfigurujte šifrování na straně klienta pro citlivé sloupce.
Always Encrypted s využitím zabezpečených enkláv Umožňuje pokročilé operace se šifrovanými sloupci pomocí zabezpečených enkláv.

Získání a aktualizace dat

Článek Description
Programovací průvodce Průvodce programováním od začátku do konce pro oba ovladače.
Porovnání výkonných funkcí Vyberte správnou výkonovou funkci pro vaše pracovní zatížení.
Přímé a připravené provedení výroku (PDO_SQLSRV) Kdy použít přímé provedení versus připravené výroky.
Získávání dat Načítání řádků, sloupců a streamovacích hodnot.
Aktualizace dat Vkládejte, aktualizujte a mažte řádky.
Provádějte parametrizované dotazy Svažte parametry, abyste se chránili před vkládáním SQL kódu.
Odesílat data jako stream Streamujte velké binární a znakové hodnoty do SQL Server.
Provádění transakcí Seskupte výpisy do atomových transakcí.
Použijte tabulkové parametry Předejte TABLE parametr uložené procedurě.
Zadejte typ kurzoru a vyberte řádky Vyberte kurzor pouze dopředu, statický, dynamický nebo klíčový kurzor.

Datové typy

Článek Description
Převod datových typů Jak ovladač mapuje typy PHP na typy ze SQL Server.
Výchozí typy dat SQL Server Výchozí typ SQL Server pro každou hodnotu PHP.
Výchozí typy dat v PHP Výchozí PHP typ pro každý typ sloupce SQL Server.
Specifikace datových typů SQL Server (SQLSRV) Přepsat typ serveru SQL Server při svázání parametrů.
Specifikace datových typů v PHP Při načítání přepsat datový typ PHP.
Odesílání a získávání dat UTF-8 Použijte PDO::SQLSRV_ENCODING_UTF8 pro zpětné převody Unicode.
Odesílání a získávání ASCII dat na Linuxu a macOS Zpracovávejte obousměrné převody ASCII na hostitelích jiných než Windows.
Formát desetinných čísel a peněz (SQLSRV) Formátujte desetinnéa peněžní sloupce pomocí ovladače SQLSRV.
Formát desetinných čísel a peníze (PDO_SQLSRV) Formátujte sloupce typu decimal a money pomocí ovladače PDO_SQLSRV.
Nesystémová nastavení lokality Lokalizované desetinné oddělovače a další lokální aspekty.

Chyby a diagnostika

Článek Description
Chyby při manipulaci a varování Řešení chyb a varování u obou ovladačů.
Konfigurace zpracování chyb a varování (SQLSRV) Laděte způsob, jakým ovladač SQLSRV hlásí chyby a varování.
Řešení chyb a varování (SQLSRV) Kontrolujte chyby vrácené funkcemi SQLSRV.
Protokolovací činnost Povolte logování ovladačů pro diagnostický záznam.

Nasazení a provoz

Článek Description
Ladění výkonu Správa spojení, dávkování, připravené příkazy, kurzory, paměť a monitorování na straně serveru.
Troubleshooting Diagnostikujte běžné problémy s instalací, připojením, dotazem, datovým typem, transakcí a kontejnery.

Referenční obsah

Článek Description
SQLSRV driver API reference Všechny sqlsrv_* funkce, parametry a vrácené hodnoty.
Reference k ovladači PDO_SQLSRV Metody PDO a PDOStatement podporované ovladačem PDO_SQLSRV.
Konstanty Konstanty vystavené ovladači, včetně typových a kódovacích konstant.
Článek Description
Poznámky k vydání Historie pro každou verzi s novými funkcemi, opravami chyb, změnami podpory platformy a odkazy ke stažení.
O ukázkách kódu v dokumentaci Konvence používané ukázkami kódu v této sekci.
Ukázky kódu pro PHP SQL ovladač Kompletní ukázkové aplikace pro SQLSRV a PDO_SQLSRV.
Podpůrné zdroje Komunita a podpůrné kanály.

Související obsah

  • Last updated on