Ovladače Microsoftu pro PHP pro SQL Server

Stáhnout ovladač PHP

Microsoft Drivers for PHP for SQL Server jsou rozšíření PHP, která můžete použít ke čtení a zápisu dat v Microsoft SQL Database Engine pomocí skriptů PHP. Obě rozšíření používají stejný Microsoft ODBC ovladač pro SQL Server, ale nabízejí odlišná PHP API a specifické možnosti pro ovladače:

• SQLSRV nabízí procedurální API (sqlsrv_*funkce) přizpůsobené funkcím SQL Server.
• PDO_SQLSRV implementuje rozhraní PHP Data Objects (PDO). PDO volání můžete ponechat v existujícím databázovém kódu, ale před změnou databáze si zkontrolujte dotazy a nastavení specifická pro ovladač.

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. Oba ovladače přijímají PHP streamy jako vstupní parametry. SQLSRV podporuje získávání velkých binárních a znakových hodnot jako streamů. Nepředpokládejte PDO_SQLSRV že má stejné chování při výstupním streamování.

Výběr výchozího bodu

• Pro ověření instalace a spuštění parametrizovaného dotazu pomocí SQLSRV nebo PDO_SQLSRV začněte s Quickstart: Connect a dotazujte pomocí Microsoft ovladačů pro PHP.
• Pro instalaci ovladače na Linux nebo macOS začněte instalačním tutoriálem pro Linux a macOS a stáhněte si Microsoft ovladače pro PHP pro SQL Server.
• Pro připojení k Azure SQL s autentizací bez hesla začněte s Connect pomocí autentizace Microsoft Entra a možností připojení.
• Chcete-li udělat stávající aplikaci odolnou vůči přechodným selháním, přejděte na odolnost připojení v režimu nečinnosti.
• Pro rozhodnutí mezi SQLSRV a PDO_SQLSRV přejděte do Přehledu Microsoft ovladačů pro PHP pro SQL Server a Porovnání výkonových funkcí.
• Pro diagnostiku problému s instalací, připojením nebo dotazem přejděte do Řešení problémů, Zpracování chyb a varování a Logování aktivity.
• Chcete-li zrychlit existující aplikaci, přejděte do Performance tuning.

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

Tento příklad PDO_SQLSRV čte server a databázi z proměnných prostředí a připojuje se pomocí spravované identity. Vytváří název datového zdroje (DSN) a povoluje protokol Transport Layer Security (TLS) s ověřováním certifikátů. Čtěte tyto hodnoty z důvěryhodné konfigurace aplikace, ne z parametrů webových požadavků. Spusť program na hostiteli s endpointem spravované identity po udělení identity přístupu k databázi.

Pomocné funkce provedou až tři pokusy o připojení nebo spuštění dotazu pouze pro čtení, když nastane uvedená chyba. Mezi pokusy čekají déle, což je vzorec zvaný exponenciální ústup. Pokud chyba dotazu vyžaduje nové spojení, pomocník dotazu vyhodí výjimku, kterou má volající kód zpracovat.

Použijte podporovanou PHP verzi, rozšíření PDO_SQLSRV a Microsoft ODBC Driver 18 pro SQL Server. Pro podporované autentizační hodnoty viz Připojení pomocí ověřování Microsoft Entra. Nepoužívejte pomocníka dotazů pro zápisy nebo vícenásobné transakce bez navržení aplikační politiky opakovaných pokusů: chyba vám nemusí vždy říct, zda zápis byl potvrzen.

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

Použijte tato nastavení pro skupiny pro failover v Azure SQL Database a Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} explicitně vybírá ODBC ovladač 18, místo aby se spoléhal na objevování ovladačů. Nainstalujte ho před spuštěním příkladu.

• Nastavte SQL_DATABASE na skutečný název databáze. Program zdvojí uzavírací závorky a uzavírá jméno do závorek před jeho vložením do DSN. Escapování zabraňuje tomu, aby speciální znaky v názvu měnily způsob, jakým ovladač čte nastavení připojení.

• ConnectRetryCount a ConnectRetryInterval řídí ODBC odolnost nečinných připojení. Časový limit dotazu ve výkazu omezuje obnovu během vykonání. S 30sekundovým časovým limitem dotazu vzorku může ODBC zastavit dřív, než vyčerpá všech pět pokusů o opětovné připojení. LoginTimeout=90 Řídí navázání spojení, nikoli tento rozpočet na obnovu. Pomocník na úrovni aplikace znovu zkouší vybrané chyby serveru; nezkouší znovu časový limit dotazu ani nepřehrává částečně načítané výsledky.

• Povolte protokolování ovladače spolu s voláními error_log() programu. Pro PDO_SQLSRV nastavte pdo_sqlsrv.log_severity v php.ini nebo s ini_set() během běhu. Pro SQLSRV nakonfigurujte LogSeverity a LogSubsystems pomocí sqlsrv_configure(). 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. Použijte argument uživatelského jména konstruktora PDO místo vkládání identity do DSN. 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í složku přidejte ApplicationIntent=ReadOnly do DSN.

• Používejte endpoint poskytovaný vaší SQL službou, včetně její domény specifické pro cloud. Místo deaktivace ověřování certifikátů je třeba prozkoumat nesoulad mezi názvy certifikátů. Používejte HostNameInCertificate pouze tehdy, když znáte očekávaný název certifikátu pro daný koncový bod.

• ODBC získává tokeny pro autentizaci spravované identity a instančního objektu služby. S AccessToken, vaše aplikace získá token a předá ho ovladači; ODBC jej za vás nezíská. Další informace naleznete v tématu Použití rozhraní Microsoft Entra ID s ovladačem ODBC.

• Udržujte informace o připojení mimo svůj kód. Uložte ho do konfiguračního systému vaší aplikace a používejte Azure Key Vault pro tajné údaje.

• U SQLSRV nastavte možnosti spojení v poli předaném do sqlsrv_connect(). Zkontrolujte návratovou hodnotu false a zkontrolujte sqlsrv_errors() předtím, než se rozhodnete, zda akci zopakovat. Nastavte časové limity příkazů zvlášť s QueryTimeout. Odolnost nečinného spojení ukazuje rekonekci ODBC, nikoli smyčku opakovaných pokusů na úrovni aplikace.

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

• 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ě PHP API: SQLSRV poskytuje procedurální funkce. PDO_SQLSRV implementuje PDO. Nainstalujte buď jedno z těchto rozšíření, nebo oba.
• Š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: Spravovaná identita, principál služby a externě získané přístupové tokeny prostřednictvím základního ovladače Microsoft ODBC pro SQL Server. Spravovaná identita je bez hesla; ActiveDirectoryServicePrincipal používá tajný klíč klienta.
• Always Encrypted: Šifrujte citlivé sloupce na klientovi, s bezpečnými enklávami pro podporované operace se šifrovanými daty.
• Odolnost spojení: Vestavěné opakované pokusy o nečinné spojení s ConnectRetryCount a ConnectRetryInterval.
• PHP streamy: Posílejte velké binární a znakové hodnoty z parametrů streamu s kterýmkoli API. Používejte SQLSRV pro streamované načítání dat.
• 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.
Rychlý začátek: Připojte se a dotazujte pomocí Microsoft ovladačů pro PHP	Ověřte rozšíření, nakonfigurujte připojení a spusť stejný parametrizovaný dotaz pomocí SQLSRV nebo PDO_SQLSRV.
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 na Windows nebo Kerberos na Linuxu a macOS.

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	Najděte programovací úkoly pro oba řidič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í	Commit nebo roll back skupinu příkazů dohromady.
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	Nastavte možnost CharacterSet ovladače SQLSRV nebo atribut PDO::SQLSRV_ATTR_ENCODING ovladače PDO_SQLSRV.
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.

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č	Kompletní ukázkové aplikace pro SQLSRV a PDO_SQLSRV.
Podpůrné zdroje	Komunita a podpůrné kanály.

Žádost o funkci

Chcete-li požádat o novou funkci, založte issue v repozitáři GitHubu Microsoft Drivers for PHP for SQL Server.

Související obsah

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