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

Goal	Začněte tady
Nastavte si PHP vývojové prostředí a spusť první dotaz	Krok 1: Nakonfigurujte vývojové prostředí, poté Krok 2: Vytvořte SQL databázi a krok 3: Ověření konceptu připojení ke SQL pomocí PHP.
Nainstalujte ovladač na Linux nebo macOS	Instalační tutoriál pro Linux a macOS a stažení Microsoft ovladačů pro PHP pro SQL Server.
Připojit se k Azure SQL s autentizací bez hesla	Připojte se pomocí Microsoft Entra autentizace a možností připojení.
Udělejte stávající aplikaci odolnou vůči přechodným selháním	Odolnost nečinnosti připojení a krok 4: Odolné připojení k SQL pomocí PHP.
Rozhodněte se mezi SQLSRV a PDO_SQLSRV	Přehled Microsoft ovladačů pro PHP pro SQL Server a porovnávání výkonných funkcí.
Diagnostikujte problém s instalací, připojením nebo dotazem	Řešení problémů, řešení chyb a varování a zaznamenávání aktivit.
Zrychlete existující aplikaci	Ladění výkonu.

Rychlé připojení

Následující úryvek je nejkratší end-to-end připojení, které může funkční instalace PHP spustit proti SQL Server nebo Azure SQL. Použijte ho k ověření, že máte zapojený ovladač, závislosti ODBC a síťovou cestu, než přejdete k produkční základně v další sekci.

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

Pro bezheslové připojení proti Azure SQL přidejte Authentication=ActiveDirectoryMsi (managed identity) nebo jinou Authentication hodnotu do DSN a argumenty $user/$password vynechať. Následující výrobní úroveň rozšiřuje stejný vzorec s opakovanými testy, timeouty a diagnostikou.

U lokálního SQL Server, který používá samopodepsaný certifikátEncrypt=true, validace selže. Přidávky TrustServerCertificate=true jsou určeny pouze pro místní rozvoj. Viz chyby TLS certifikátu pro produkční alternativy.

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. Čte server a databázi z proměnných prostředí (například nastavení aplikace Azure App Service), autentizuje se spravovanou identitou, aktivuje Transport Layer Security (TLS) s ověřováním serverového certifikátu, nastavuje timeout přihlášení pokrývajícího failover při studeném startu a nastavuje ConnectRetryCountConnectRetryInterval odolnost nečinnosti SQL Server vůči nečinnosti. Aplikační a connectWithRetryqueryWithRetry pomocné moduly obalují jak počáteční spojení, tak každý příkaz omezeným exponenciálním zpětným odstupem a oddělují přechodné chyby spojení (které vyžadují nové připojení) od přechodných chyb dotazů (které znovu používají stejné spojení).

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'.

• ConnectRetryCounta ConnectRetryInterval jsou klíčová slova ODBC připojovací řetězec, která umožňují odolnost SQL Server v idle spojení: ovladač transparentně znovu připojí přerušené nečinné spojení. To se liší od aplikačního , queryWithRetrykterý znovu zkouší příkaz selžící s přechodnou chybou, jako je zablokování nebo časový limit dotazu. Oba jsou vzájemně doplňující, takže si nechte obojí. Ujistěte se LoginTimeout , že je alespoň ConnectRetryCount * ConnectRetryInterval tak, aby cesta k nečinnému a opětovnému připojení dosáhla plného rozpočtu; vzorek využívá 90 sekund na pokrytí 5 × 15 sekund opakovaných pokusů plus rezerva pro počáteční přihlášení při studeném failoveru.

• 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 settable 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 uživatelem přiřazenou spravovanou identitu předejte ID identity jako argument PDO $username (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 se odmítá UID přímo v DSN, proto použijte slot 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 pole možností připojení.

• Nastavte MultiSubnetFailover=true při připojení k failover-group listeneru, availability-group listeneru nebo failover cluster instance instance. Nastavení zlepšuje výkon připojení jak pro posluchače dostupnosti v jedné podsíti, tak u více podsítí. 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é identity, principal služby a přístupové tokeny všechny procházejí 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. Vzor opakování je stejný: chyť false návrat z , sqlsrv_connectkontrolovat sqlsrv_errors() SQLSTATE a stáhnout se před opětovným pokusem. Pro praktický příklad viz Krok 4: Odolné připojení k SQL pomocí PHP.

• Pomocníci pro opakované pokusy jsou chráněni $e->errorInfo[1]isset(). PDOException::$errorInfo je deklarován jako a ?array výchozí na null, takže obranná kontrola se vrací k ovladači a 0 nechává prefix SQLSTATE 08 rozhodnout, zda to zkusit znovu.

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

• Možnosti připojení
• Připojte se pomocí ověřování Microsoft Entra
• Odolnost nečinného spojení
• Připojení ke službě Microsoft Azure SQL Database
• Podpora vysoké dostupnosti, obnova po havárii

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.
Nakládání řidičů	Povolte rozšíření v php.ini.
Začínám s PHP SQL ovladačem	Průchod od začátku do konce, který spojuje čtyři kroky od začátku dohromady.
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	Connect a PHP application to Azure SQL Database.
Připojte se na určený port	Zaměřte se na nevýchozí TCP port.
Sdružování připojení	Znovu použijte ODBC spojení napříč PHP požadavky.
Vypnout 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í při přerušení nečinnosti v klidu.

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žnit bohaté operace na šifrovaných sloupcích s bezpečnými enklávami.

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	Připojte parametry k ochraně proti SQL injection.
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řepisujte typ SQL Server při vázání parametrů.
Specifikace datových typů v PHP	Při načítání přepisujte PHP typ.
Odesílání a získávání dat UTF-8	Použití PDO::SQLSRV_ENCODING_UTF8 pro Unicode zpáteční cesty.
Odesílání a získávání ASCII dat na Linuxu a macOS	Zvládejte ASCII opětní cesty na hostitelích mimo 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 desetinnéa peněžní sloupce s PDO_SQLSRV ovladačem.
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.
Těžební č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.

Reference

Článek	Description
SQLSRV driver API reference	Všechny sqlsrv_* funkce, parametry a vrácené hodnoty.
PDO_SQLSRV řidičský odkaz	PDO a metody PDOStatement podporované PDO_SQLSRV ovladačem.
Konstanty	Konstanty vystavené ovladači, včetně typových a kódovacích konstant.

Související úkoly

Č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č	End-to-end příkladové aplikace pro SQLSRV a PDO_SQLSRV.
Podpůrné zdroje	Komunita a podpůrné kanály.

Související obsah

• Microsoft ovladače pro PHP pro SQL Server na GitHub
• Ovladač Microsoft ODBC pro SQL Server
• ovladače SQL Serveru