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

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

Konfigurera och ansluta

Authenticate

Secure

Hämta och uppdatera data

Datatyper

Fel och diagnostik

Distribuera och driva

Reference

Relaterade uppgifter

Relaterat innehåll

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