Microsoft-drivrutiner för PHP för SQL Server

Ladda ned PHP-drivrutin

Microsoft-drivrutinerna för PHP för SQL Server är PHP-tillägg som låter dig läsa och skriva data i Microsoft SQL Database Engine från PHP-skript. Paketet innehåller två drivrutiner som omsluter samma Microsoft ODBC-drivrutin för SQL Server och delar samma anslutningsalternativ, så du kan välja det API som passar din kodbas:

• SQLSRV exponerar ett prozedurmässigt API (sqlsrv_*funktioner) anpassat till SQL Server-funktioner.
• PDO_SQLSRV implementerar PHP Data Objects (PDO)-gränssnittet, så kod som redan använder PDO för andra databaser kan rikta in sig på SQL Server med minimala ändringar.

Båda drivrutinerna ansluter till Azure SQL Database, SQL-databas i Microsoft Fabric, Azure SQL Managed Instance och alla stödda versioner och utgåvor av SQL Server (inklusive Express-versioner). De använder PHP-strömmar för att flytta stora binär- och teckenvärden utan att ladda in dem helt i minnet.

Välj startpunkt

Mål	Börja här
Sätt upp en PHP-utvecklingsmiljö och kör din första fråga	Steg 1: Konfigurera utvecklingsmiljön, sedan Steg 2: Skapa en SQL-databas och Steg 3: Bevis på koncept som ansluter till SQL med PHP.
Installera drivrutinen på Linux eller macOS	Installationsguide för Linux och macOS och ladda ner Microsoft-drivrutinerna för PHP för SQL Server.
Connect to Azure SQL med lösenordslös autentisering	Koppla upp dig med Microsoft Entra-autentisering och anslutningsalternativ.
Gör en befintlig app motståndskraftig mot tillfälliga fel	Vilolägesanslutningsresiliens och steg 4: Koppla upp sig robust mot SQL med PHP.
Bestäm dig mellan SQLSRV och PDO_SQLSRV	Översikt över Microsoft-drivrutinerna för PHP för SQL Server och jämförelse av exekveringsfunktioner.
Diagnostisera ett installations-, anslutnings- eller frågeproblem	Felsökning, hanteringsfel och varningar samt loggningsaktivitet.
Gör en befintlig app snabbare	Prestandajustering.

Snabbanslutning

Följande utdrag är den kortaste end-to-end-anslutningen som en fungerande PHP-installation kan köra mot SQL Server eller Azure SQL. Använd den för att bekräfta att din drivrutin, ODBC-beroenden och nätverksbana är kopplade innan du går vidare till produktionsbaslinjen i nästa avsnitt.

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

För en lösenordslös anslutning mot Azure SQL, lägg till Authentication=ActiveDirectoryMsi (managed identity) eller ett annat Authentication värde i DSN och ta bort argumenten/$user$password. Produktionsbaslinjen som följer följer samma mönster med omförsök, timeouts och diagnostik.

För en lokal SQL Server som använder ett självsignerat certifikat Encrypt=true misslyckas valideringen. Lägg till för TrustServerCertificate=true lokal utveckling enbart. Se TLS-certifikatfel för produktionsalternativen.

Produktionsbaslinje för Azure SQL

Använd detta utdrag som utgångspunkt för en produktionsorienterad Azure SQL-koppling till den PDO_SQLSRV drivrutinen. Den läser servern och databasen från miljövariabler (till exempel Azure App Service-appinställningar), autentiserar med en hanterad identitet, aktiverar Transport Layer Security (TLS) med validering av servercertifikat, sätter en inloggningstidsgräns som täcker en kallstartsfailover, och sätter ConnectRetryCount och ConnectRetryInterval för SQL Server inaktiva anslutningsresiliens. Applikationsnivån connectWithRetry och queryWithRetry hjälpsystemen omsluter både den initiala anslutningen och varje sats med en begränsad exponentiell backoff, och separationer mellan tillfälliga anslutningsfel (som kräver en ny anslutning) och tillfälliga frågefel (som återanvänder samma anslutning).

Kräver PHP 8.0 och senare versioner, PDO_SQLSRV-tillägget och Microsoft ODBC-drivrutin för SQL Server 17.3.1.1 och senare versioner för Authentication=ActiveDirectoryMsi. För hela listan över stödda Authentication värden, se Connect using Microsoft Entra authentication.

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

Det här kodfragmentet är justerat för Azure SQL Database redundansgrupper och Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} pinnar ODBC 18-drivern. Om värden också har ODBC 17 installerad kan PDO_SQLSRV binda till ODBC 17. Äldre 17.x-versioner avvisar nyare Authentication värden; till exempel Authentication=ActiveDirectoryMsi kräver ODBC 17.3.1.1 eller en senare version. Se Ogiltigt värde angivet för attributet 'Authentication i reťazec pripojenia.

• ConnectRetryCountoch ConnectRetryInterval är ODBC-reťazec pripojenia-nyckelord som möjliggör SQL Server inaktiva anslutningsresiliens: drivrutinen återansluter transparent en trasig vilo-anslutning. Det skiljer sig från applikationsnivå queryWithRetry, som försöker om en sats som misslyckas med ett tillfälligt fel, såsom deadlock eller frågetidsavbrott. De två kompletterar varandra, så behåll båda. Se till LoginTimeout att åtminstone ConnectRetryCount * ConnectRetryInterval den inaktiva återanslutningsvägen får sin fulla budget; provet använder 90 sekunder för att täcka 5 × 15 sekunder av omprövningar plus utrymme för den initiala inloggningen vid kall failover.

• Komplettera applikationsnivåanropen error_log() med diagnostik på förarsidan. För PDO_SQLSRV, sätt pdo_sqlsrv.log_severity i php.ini (kan endast ställas vid initialisering); för SQLSRV, anropa sqlsrv_configure("LogSubsystems", ...) vid körning. För mer information, se Loggningsaktivitet.

  ; 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
  

• För en användartilldelad hanterad identitet, skicka identitetens ID som PDO:s $username argument (new PDO($dsn, $identityId, null, $options)). Använd identitetens klient-ID på Azure App Service eller Azure Container Instance; annars använd dess objekt-ID. PHP-drivrutinerna ärver detta beteende från den underliggande Microsoft ODBC-drivrutinen för SQL Server; för mer information, se Användning av Microsoft Entra ID med ODBC-drivrutinen. PDO_SQLSRV avvisar UID inuti DSN:n, så använd konstruktörplatsen. Att passera null som användaren (som exemplet gör) väljer den systemtilldelade hanterade identiteten för Azure-värden. För SQLSRV (procedurur), skicka UID in anslutningsoptionsmatrisen.

• Ställ in MultiSubnetFailover=true när du ansluter till en failover-grupplyssnare, tillgänglighetsgrupplyssnare eller failoverkluster-instansändpunkt. Att ställa in den förbättrar anslutningsprestandan för både single-subnet- och multi-subnet tillgänglighetsgrupplyssnare. För mer information, se Support for High Availability, katastrofåterställning.

• För läst skalning eller läsbar sekundär, lägg till ApplicationIntent=ReadOnly i Data Source Name (DSN).

• För suveräna moln där certifikatets Subject Alternative Name (SAN) inte inkluderar värden du ansluter till, lägg till HostNameInCertificate i DSN (till exempel *.database.usgovcloudapi.net för Azure Government).

• Drivrutinen förlitar sig på den underliggande Microsoft ODBC-drivrutinen för SQL Server för tokeninsamling. Managed identity-, service principal- och access-token-flöden går alla via ODBC. Mer information finns i Använda Microsoft Entra-ID med ODBC-drivrutinen.

• För högre säkerhet och portabilitet mellan miljöer, håll anslutningsinformationen utanför din kod. Lagra anslutningsinformation i applikationens konfigurationssystem och använd Azure Key Vault för känsliga värden och centralt hanterade anslutningsinställningar.

• Den motsvarande SQLSRV-anslutningen använder sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) och returnerar en resurs. Återförsöksmönstret är detsamma: fånga en false retur från sqlsrv_connect, inspektera sqlsrv_errors() för SQLSTATE och backa innan du försöker igen. För ett genomarbetat exempel, se steg 4: Anslut robust till SQL med PHP.

• Hjälparna till återförsök läser $e->errorInfo[1] bevakade av isset(). PDOException::$errorInfo deklareras som ?array och går som standard till null, så den defensiva kontrollen faller tillbaka på en drivrutinskod av 0 och låter SQLSTATE-prefixet 08 avgöra om det ska försöka igen.

Mer information om varje del av den här konfigurationen finns i:

• Anslutningsalternativ
• Ansluta med Microsoft Entra-autentisering
• Vilolägesanslutningsresiliens
• Ansluta till Microsoft Azure SQL Database
• Stöd för hög tillgänglighet, katastrofåterställning

Katalogen med Azure SQL tillfälliga fel finns i Felsöka tillfälliga anslutningsfel.

Viktiga funktioner

• Två API:er, ett drivrutinspaket: Procedural SQLSRV för SQL Server-först-kod, eller PDO_SQLSRV för portabel PDO-kod.
• Brett plattformsstöd: Körs på Windows, Linux och macOS med stödda PHP-versioner.
• Krypterade anslutningar: TLS-krypterade anslutningar via Encrypt=true, med validering av servercertifikat kontrollerad av TrustServerCertificate.
• Microsoft Entra ID-autentisering: Lösenordslösa anslutningar med hanterad identitet, tjänsteprincip och åtkomsttoken flödar genom den underliggande Microsoft ODBC-drivrutinen för SQL Server.
• Always Encrypted: Kryptering på klientsidan för känsliga kolumner, med valfria säkra enklaver för åtgärder på plats.
• Anslutningsresiliens: Inbyggda inaktiva anslutningsförsök med ConnectRetryCount och ConnectRetryInterval.
• PHP-strömmar: Läs och skriv stora binär- och teckenvärden som strömmar istället för att ladda in dem i minnet.
• Stöd för datatyper i Rich SQL Server: datetimeoffset, tabellvärda parametrar, nvarchar och Unicode med PDO::SQLSRV_ENCODING_UTF8.

Get started

Artikel	Description
Systemkrav	Stödde PHP, operativsystem och SQL Server-versioner.
Supportmatris	Detaljerad kompatibilitetsmatris för PHP-drivrutinsreleaser.
Ladda ner Microsoft-drivrutinerna för PHP för SQL Server	Ladda ner länkar och släpp artefakter.
Installationsguide för Linux och macOS	Installera drivrutinen och dess ODBC-förkunskaper på Linux och macOS.
Laddar drivrutinerna	Aktivera tilläggen i php.ini.
Att komma igång med PHP SQL-drivrutinen	Genomgång från början till slut som binder ihop de fyra startstegen.
Översikt av PHP SQL-drivrutinen	Vad som finns i paketet, och när man ska välja SQLSRV eller PDO_SQLSRV.

Konfigurera och ansluta

Artikel	Description
Anslutning till servern	Öppna en anslutning till en SQL Server-instans från PHP.
Anslutningsalternativ	Fullständig referens för anslutningsnyckelord, standardinställningar och hur man sätter dem.
Ansluta till Microsoft Azure SQL Database	Koppla en PHP-applikation till Azure SQL Database.
Koppla upp på en angiven port	Rikta in dig på en icke-standard TCP-port.
Anslutningspoolning	Återanvänd ODBC-anslutningar över PHP-förfrågningar.
Inaktivera flera aktiva resultatuppsättningar (MARS)	Stäng av MARS för kompatibilitet.
Stöd för LocalDB	Anslut dig till en SQL Server LocalDB-instans.
Stöd för hög tillgänglighet, katastrofåterställning	Tillgänglighetsgrupplyssnare och redundans för flera undernät.
Vilolägesanslutningsresiliens	Automatisk återanslutning vid trasiga viloförbindelser.

Authenticate

Artikel	Description
Ansluta med Microsoft Entra-autentisering	Flöden för hanterad identitet, tjänstehuvudansvarig, åtkomsttoken och lösenord.
Koppla upp med SQL Server-autentisering	Använd en SQL-inloggning med användarnamn och lösenord.
Koppla upp dig med Windows authentication	Använd Windows integrerad autentisering på domänanslutna värdar.

Secure

Artikel	Description
Säkerhetsöverväganden	Hotmodell och defensiv djupgående vägledning för PHP-applikationer.
Alltid krypterat med PHP-drivrutinerna	Konfigurera kryptering på klientsidan för känsliga kolumner.
Always Encrypted med säkra enklaver	Möjliggör rika operationer på krypterade kolumner med säkra enklaver.

Hämta och uppdatera data

Artikel	Description
Programguide	En änd-till-änd programmeringsguide för båda drivrutinerna.
Jämförelse av exekveringsfunktioner	Välj rätt exekveringsfunktion för din arbetsbelastning.
Direkt och förberedd satsexekvering (PDO_SQLSRV)	När man ska använda direkt exekvering kontra förberedda satser.
Hämta data	Hämta rader, kolumner och strömningsvärden.
Uppdatering av data	Lägg in, uppdatera och ta bort rader.
Utför parameteriserade frågor	Bind parametrar för att skydda mot SQL-injektion.
Skicka data som en ström	Strömma stora binära och teckenvärden till SQL Server.
Genomföra transaktioner	Gruppera uttalanden i atomära transaktioner.
Använd tabellvärda parametrar	Skicka en TABLE parameter till en lagrad procedur.
Ange en markörtyp och markera rader	Välj framåtriktade, statisk, dynamisk eller keyset-markörer.

Datatyper

Artikel	Description
Konvertering av datatyper	Hur drivrutinen mappar PHP-typer till SQL Server-typer.
Standardtyper av SQL Server-data	Standard SQL Server-typ för varje PHP-värde.
Standard PHP-datatyper	Standard PHP-typ för varje SQL Server-kolumntyp.
Specificera SQL Server-datatyper (SQLSRV)	Överskriv SQL Server-typen när parametrar binds.
Specificera PHP-datatyper	Åsidosätt PHP-typen när du hämtar.
Skicka och hämta UTF-8-data	Använd PDO::SQLSRV_ENCODING_UTF8 för Unicode-tur-och-retur-resor.
Skicka och hämta ASCII-data på Linux och macOS	Hantera ASCII-rundresor på icke-Windows-värdar.
Formatera decimaler och pengar (SQLSRV)	Formatera decimal - och penningkolumner med SQLSRV-drivrutinen.
Formatdecimal och pengar (PDO_SQLSRV)	Formatera decimal - och penningkolumner med PDO_SQLSRV driver.
Icke-systembaserade platsinställningar	Lokaliserade decimalseparatorer och andra lokala överväganden.

Fel och diagnostik

Artikel	Description
Hantering av fel och varningar	Fel- och varningshantering med båda drivrutinerna.
Konfigurera fel- och varningshantering (SQLSRV)	Justera hur SQLSRV-drivrutinen rapporterar fel och varningar.
Hantera fel och varningar (SQLSRV)	Inspektera fel som returneras av SQLSRV-funktioner.
Skogsverksamhet	Aktivera drivrutinsloggning för diagnostikfångst.

Distribuera och driva

Artikel	Description
Prestandaoptimering	Anslutningshantering, batching, förberedda satser, markörer, minne och serverövervakning.
Felsökning	Diagnostisera vanliga problem med installationer, anslutningar, förfrågningar, datatyp, transaktioner och container.

Reference

Artikel	Description
SQLSRV-drivrutins-API-referens	Alla sqlsrv_* funktioner, parametrar och returvärden.
PDO_SQLSRV förarreferens	PDO- och PDOStatement-metoder stöds av den PDO_SQLSRV drivrutinen.
Konstanter	Konstanter som exponeras av drivrutinerna, inklusive typ- och kodningskonstanter.

Relaterade uppgifter

Artikel	Description
Viktig information	Per-versionshistorik med nya funktioner, buggfixar, plattformsstödändringar och nedladdningslänkar.
Om kodexempel i dokumentationen	Konventioner som används av kodexemplen i detta avsnitt.
Kodexempel för PHP SQL-drivrutinen	End-to-end-exempelapplikationer för SQLSRV och PDO_SQLSRV.
Stödresurser	Gemenskap och stödkanaler.

Relaterat innehåll

• Microsoft-drivrutiner för PHP för SQL Server på GitHub
• Microsoft ODBC-drivrutin för SQL Server
• SQL Server-drivrutiner