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

Ladda ned PHP-drivrutin

Microsoft-drivrutiner för PHP för SQL Server är PHP-tillägg som du kan använda för att läsa och skriva data i Microsoft SQL Database Engine med PHP-skript. De två tilläggen använder samma Microsoft ODBC-drivrutin för SQL Server, men de erbjuder olika PHP-API:er och drivrutinsspecifika alternativ:

• SQLSRV exponerar ett prozedurmässigt API (sqlsrv_*funktioner) anpassat till SQL Server-funktioner.
• PDO_SQLSRV implementerar PHP Data Objects (PDO) -gränssnittet. Du kan behålla PDO-anropen i befintlig databaskod, men granska dess frågesatser och drivrutinsspecifika inställningar innan du byter databas.

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. Båda drivrutinerna accepterar PHP-strömmar som indataparametrar. SQLSRV stödjer att hämta stora binära värden och teckenvärden som strömmar. Anta inte att PDO_SQLSRV uppvisar samma output-streamingbeteende.

Välj startpunkt

• För att verifiera din installation och köra en parameteriserad fråga med SQLSRV eller PDO_SQLSRV, börja med Quickstart: Koppla upp och fråga med Microsoft drivrutiner för PHP.
• För att installera drivrutinen på Linux eller macOS, börja med installationsguiden för Linux och macOS och ladda ner Microsoft-drivrutinerna för PHP för SQL Server.
• För att ansluta till Azure SQL med lösenordslös autentisering, börja med Connect med Microsoft Entra-autentisering och anslutningsalternativ.
• För att göra en befintlig app motståndskraftig mot tillfälliga fel går du till Motståndskraft för inaktiv anslutning.
• För att välja mellan SQLSRV och PDO_SQLSRV, gå till Översikt över Microsoft drivrutiner för PHP för SQL Server och Jämförande exekveringsfunktioner.
• För att diagnostisera ett installations-, anslutnings- eller frågeproblem, gå till Felsökning, Hantering av fel och varningar samt Loggning av aktivitet.
• För att göra en befintlig app snabbare, gå till Performance tuning.

Produktionsbaslinje för Azure SQL

Detta PDO_SQLSRV-exempel läser servern och databasen från miljövariabler och ansluter med hjälp av en hanterad identitet. Den bygger ett datakällnamn (DSN) och möjliggör Transport Layer Security (TLS) med certifikatvalidering. Läs dessa värden från betrodd programkonfiguration, inte parametrar för webbförfrågningar. Kör programmet på en värd med en hanterad identitetsändpunkt efter att identiteten har beviljats åtkomst till databasen.

Hjälpfunktionerna gör upp till tre försök att ansluta eller köra en skrivskyddad fråga när ett fel i listan uppstår. De väntar längre mellan försöken, ett återförsöksmönster som kallas exponentiell backoff. Om ett frågefel kräver en ny anslutning kastar frågehjälpfunktionen undantaget så att den anropande koden kan hantera det.

Använd en stödd PHP-version, PDO_SQLSRV-tillägget och Microsoft ODBC Driver 18 för SQL Server. För stödda autentiseringsvärden, se Ansluta med Microsoft Entra-autentisering. Återanvänd inte frågehjälparen för skrivningar eller multistatement-transaktioner utan att designa en applikationsspecifik återförsökspolicy: ett fel berättar inte alltid om en skrivning är committad.

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

Använd dessa inställningar för Azure SQL Database failover-grupper och Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} väljer ODBC Driver 18 uttryckligen istället för att förlita sig på drivrutinsupptäckt. Installera det innan du kör exemplet.

• Ställ SQL_DATABASE in på det faktiska databasnamnet. Programmet dubblerar avslutande klammerparenteser och omsluter namnet med klammerparenteser innan det placeras i DSN. Att använda escape-tecken hindrar specialtecken i namnet från att ändra hur drivrutinen läser anslutningsinställningar.

• ConnectRetryCount och ConnectRetryInterval styr ODBC:s återhämtning för inaktiva anslutningar. Satsens frågetimeout begränsar återhämtningen under exekveringen. Med provets 30-sekunders frågetimeout kan ODBC sluta innan alla fem återanslutningsförsök är uttömda. LoginTimeout=90 styr anslutningsetablering, inte den återhämtningsbudgeten. Hjälparen på applikationsnivå försöker igen vid valda serverfel; den försöker inte igen vid en frågetimeout eller upprepar delvis hämtade resultat.

• Aktivera drivrutinsloggning tillsammans med programmets error_log() anrop. För PDO_SQLSRV, ställ in pdo_sqlsrv.log_severity i php.ini eller med ini_set() vid körning. För SQLSRV, konfigurera LogSeverity och LogSubsystems med sqlsrv_configure(). 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. Använd PDO-konstruktorns användarnamnargument istället för att bädda in användarnamnet i DSN. 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, lägg till ApplicationIntent=ReadOnly i DSN-strängen.

• Använd den endpoint som tillhandahålls av din SQL-tjänst, inklusive dess molnspecifika domän. Undersök felmatchningar mellan certifikatnamn i stället för att inaktivera certifikatvalidering. Använd HostNameInCertificate endast när du vet det förväntade certifikatnamnet för den endpointen.

• ODBC hämtar tokens för autentisering med hanterad identitet och tjänstens huvudnamn. Med AccessToken, förvärvar din applikation token och skickar den till föraren; ODBC skaffar den inte åt dig. Mer information finns i Använda Microsoft Entra-ID med ODBC-drivrutinen.

• Håll anslutningsinformationen utanför din kod. Lagra det i applikationens konfigurationssystem och använd Azure Key Vault för hemligheter.

• Med SQLSRV skickades anslutningsalternativen i arrayen till sqlsrv_connect(). Kontrollera om du har ett false returvärde och inspektera sqlsrv_errors() innan du bestämmer dig för om du ska försöka igen. Ställ in timeouts separat med QueryTimeout. Vilolägesanslutningsresiliens visar på ODBC-återanslutning, inte en applikationsnivå-omprövningsloop.

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

• 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å PHP-API:er: SQLSRV tillhandahåller procedurfunktioner. PDO_SQLSRV implementerar PDO. Installera antingen en förlängning eller båda.
• 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: Hanterad identitet, tjänsteprincip och externt förvärvade åtkomsttokens via den underliggande Microsoft ODBC-drivrutinen för SQL Server. Managed Identity är lösenordslös; ActiveDirectoryServicePrincipal använder en klienthemlighet.
• Always Encrypted: Kryptera känsliga kolumner på klienten, med säkra enklaver för stödda operationer på krypterade data.
• Anslutningstålighet: Inbyggda återförsök för inaktiva anslutningar med ConnectRetryCount och ConnectRetryInterval.
• PHP-strömmar: Skicka stora binära och teckenvärden från strömparametrar med något av API:erna. Använd SQLSRV för strömmande hämtning.
• 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

Referensinnehåll

Relaterade uppgifter

Begär en funktion

För att begära en funktion, öppna ett problem i Microsoft Drivers for PHP för SQL Server GitHub repository.

Relaterat innehåll

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