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

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. Hjälpfunktionerna connectWithRetry och queryWithRetry på applikationsnivå omger både den inledande anslutningen och varje sats med en begränsad exponentiell återfördröjning, och skiljer 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} fäster 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 angavs för anslutningssträngsattributet 'Authentication'.

  • ConnectRetryCount och ConnectRetryInterval är nyckelord i ODBC-anslutningssträngar som aktiverar SQL Servers funktion för återhämtning av inaktiva anslutningar: drivrutinen återansluter transparent en bruten inaktiv anslutning. Det skiljer sig från queryWithRetry på applikationsnivå, som försöker köra en SQL-instruktion igen som misslyckas på grund av ett tillfälligt fel, till exempel en deadlock eller timeout för en fråga. De två kompletterar varandra, så behåll båda. Se till att LoginTimeout är minst ConnectRetryCount * ConnectRetryInterval så att sökvägen för återanslutning vid inaktivitet får hela sitt tidsutrymme; exemplet använder 90 sekunder för att täcka 5 × 15 sekunder av återförsök plus marginal 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 ange null som användare (som i exemplet) väljer den systemtilldelade hanterade identiteten för Azure-värden. För SQLSRV (procedurmässig), ange UID i matrisen med anslutningsalternativ.

  • 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 lyssnare för tillgänglighetsgrupper med enkelsubnät och med flerasubnät. Mer information finns i stöd för hög tillgänglighet, katastrofåterställning.

  • För utskalning för läsning eller en läsbar sekundär replik lägger du till ApplicationIntent=ReadOnly i namnet på datakällan (DSN).

  • För suveräna moln där certifikatets Subject Alternative Name (SAN) inte innehåller värdnamnet som du ansluter till lägger du till HostNameInCertificate i anslutningssträngen (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. Flöden för managed identity, service principal och åtkomsttoken går samtliga 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 praktiskt exempel, se Steg 4: Anslut till SQL på ett feltåligt sätt med PHP.

  • Hjälpfunktionerna för återförsök läser $e->errorInfo[1], skyddade av isset(). PDOException::$errorInfo deklareras som ?array och har standardvärdet null, så den defensiva kontrollen använder en drivrutinskod på 0 som reserv och låter SQLSTATE-prefixet 08 avgöra om ett nytt försök ska göras.

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

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.
  • Anslutningstålighet: Inbyggda återförsök för inaktiva anslutningar 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.
Inläsning av drivrutiner 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 fler funktioner för 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 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) Åsidosätt SQL Server-typen vid bindning av parametrar.
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 returkonverteringar.
Skicka och hämta ASCII-data på Linux och macOS Hantera ASCII-tur- och returkonverteringar på värddatorer som inte kör Windows.
Formatera decimaler och pengar (SQLSRV) Formatera decimal - och penningkolumner med SQLSRV-drivrutinen.
Formatera decimaler och valuta (PDO_SQLSRV) Formatera kolumner av typen decimal och money med drivrutinen PDO_SQLSRV.
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.
Loggningsaktivitet 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.

Referensinnehåll

Artikel Description
API-referens för SQLSRV-drivrutinen 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.
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

  • Last updated on