Microsoft-stuurprogramma's voor PHP voor SQL Server

PHP-stuurprogramma downloaden

De Microsoft Drivers voor PHP voor SQL Server zijn PHP-extensies waarmee je data kunt lezen en schrijven in de Microsoft SQL Database Engine vanuit PHP-scripts. Het pakket bevat twee drivers die dezelfde Microsoft ODBC Driver voor SQL Server omsluiten en dezelfde verbindingsopties delen, zodat je de API kunt kiezen die bij je codebase past:

• SQLSRV biedt een procedurele API (sqlsrv_*functies) die is afgestemd op SQL Server-functies.
• PDO_SQLSRV implementeert de PHP Data Objects (PDO)-interface, zodat code die al PDO gebruikt voor andere databases SQL Server met minimale wijzigingen kan targeten.

Beide drivers verbinden met Azure SQL Database, SQL-database in Microsoft Fabric, Azure SQL Managed Instance, en alle ondersteunde versies en edities van SQL Server (inclusief Express-edities). Ze gebruiken PHP-stromen om grote binaire en tekenwaarden te verplaatsen zonder ze volledig in het geheugen te laden.

Uw beginpunt kiezen

Snelle verbinding

Het volgende fragment is de kortste end-to-end verbinding die een werkende PHP-installatie kan uitvoeren tegen SQL Server of Azure SQL. Gebruik het om te bevestigen dat je driver, ODBC-afhankelijkheden en netwerkpad bekabeld zijn voordat je doorgaat naar de productiebaseline in de volgende sectie.

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

Voor een wachtwoordloze verbinding tegen Azure SQL, voeg (managed identity) of een andere waarde toe Authentication=ActiveDirectoryMsi aan de DSN en verwijder de $user/$password argumenten.Authentication De daaropvolgende productiebasis breidt hetzelfde patroon uit met herpogingen, time-outs en diagnostiek.

Voor een lokale SQL Server die een zelfondertekend certificaat gebruikt, Encrypt=true faalt validatie. Voeg alleen toe TrustServerCertificate=true voor lokale ontwikkeling. Zie TLS-certificaatfouten voor de productiealternatieven.

Productiebasislijn voor Azure SQL

Gebruik dit fragment als uitgangspunt voor een productiegerichte Azure SQL verbinding met de PDO_SQLSRV driver. Het leest de server en database uit omgevingsvariabelen (bijvoorbeeld Azure App Service-appinstellingen), authenticeert met een beheerde identiteit, schakelt Transport Layer Security (TLS) in met servercertificaatvalidatie, stelt een logintimeout in die een cold-start failover dekt, en stelt ConnectRetryCount een ConnectRetryInterval SQL Server idle-verbindingsveerkracht in. De applicatieniveau connectWithRetry en queryWithRetry helpers omhullen zowel de initiële verbinding als elke instructie met een begrensde exponentiële backoff, en scheiden tijdelijke verbindingsfouten (die een verse verbinding vereisen) van tijdelijke queryfouten (die dezelfde verbinding hergebruiken).

Vereist PHP 8.0 en latere versies, de PDO_SQLSRV extensie en Microsoft ODBC Driver voor SQL Server 17.3.1.1 en latere versies voor Authentication=ActiveDirectoryMsi. Voor de volledige lijst van ondersteunde Authentication waarden, zie Connect met Microsoft Entra-authenticatie.

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

Dit fragment is afgestemd op Azure SQL Database failovergroepen en Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} pinnen de ODBC 18-driver. Als de host ook ODBC 17 heeft geïnstalleerd, kan PDO_SQLSRV binden naar ODBC 17. Oudere 17.x-builds weigeren nieuwere Authentication waarden; bijvoorbeeld Authentication=ActiveDirectoryMsi vereist ODBC 17.3.1.1 of een latere versie. Zie Ongeldige waarde gespecificeerd voor het attribuut 'Authenticatie' voor verbindingsreeks.

• ConnectRetryCounten ConnectRetryInterval zijn ODBC-verbindingsreeks-trefwoorden die de veerkracht van SQL Server in idle connection mogelijk maken: de driver maakt een gebroken idle-verbinding transparant weer verbinding. Dat is anders dan het applicatieniveau queryWithRetry, dat een statement opnieuw probeert dat faalt met een tijdelijke fout zoals een deadlock of query-timeout. De twee vullen elkaar aan, dus houd ze allebei. Zorg ervoor dat LoginTimeout het ConnectRetryCount * ConnectRetryInterval idle-reconnect-pad zijn volledige budget krijgt; de sample gebruikt 90 seconden om 5 × 15 seconden herpogingen plus headroom voor de eerste login bij een koude failover te dekken.

• Vul de aanroepen op applicatieniveau error_log() aan met diagnostiek aan de bestuurderskant. Voor PDO_SQLSRV, zet pdo_sqlsrv.log_severity in php.ini (alleen instelbaar bij initialisatie); voor SQLSRV, call sqlsrv_configure("LogSubsystems", ...) tijdens runtime. Voor meer informatie, zie Logging activiteiten.

  ; 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
  

• Voor een door de gebruiker toegewezen beheerde identiteit geef je de ID van de identiteit door als het $username argument van PDO (new PDO($dsn, $identityId, null, $options)). Gebruik de client ID van de identiteit op Azure App Service of Azure Container Instance; anders gebruik je de object-ID. De PHP-drivers erven dit gedrag van de onderliggende Microsoft ODBC Driver for SQL Server; voor meer informatie, zie Gebruik van Microsoft Entra ID met de ODBC Driver. PDO_SQLSRV wordt in de DSN zelf afgekeurd UID , dus gebruik de constructorslot. Door als gebruiker te passeren null (zoals in het voorbeeld) selecteert je de door het systeem toegewezen beheerde identiteit van de Azure-host. Voor SQLSRV (procedureel) geef je de verbindingsopties-array door.UID

• Stel in MultiSubnetFailover=true wanneer je verbinding maakt met een failover-groep luisteraar, beschikbaarheidsgroep-luisteraar of failover-cluster instantie-eindpunt. Het instellen ervan verbetert de verbindingsprestaties voor zowel single-subnet als multi-subnet beschikbaarheidsgroepluisteraars. Voor meer informatie, zie Support for High Availability, disaster recovery.

• Voor read scale-out of een leesbare secundaire documentatie, voeg toe ApplicationIntent=ReadOnly aan de Data Source Name (DSN).

• Voor soevereine clouds waarbij het certificaat Subject Alternative Name (SAN) de host waarmee je verbinding maakt niet bevat, voeg HostNameInCertificate je toe aan het DSN (bijvoorbeeld *.database.usgovcloudapi.net voor Azure Government).

• De driver is afhankelijk van de onderliggende Microsoft ODBC Driver voor SQL Server voor tokenverwerving. Beheerde identiteit, service principal en access-token stromen gaan allemaal via ODBC. Zie Microsoft Entra-id gebruiken met het ODBC-stuurprogrammavoor meer informatie.

• Voor hogere beveiliging en draagbaarheid tussen omgevingen, houd de verbindingsinformatie buiten je code. Sla verbindingsinformatie op in het configuratiesysteem van je applicatie en gebruik Azure Key Vault voor gevoelige waarden en centraal beheerde verbindingsinstellingen.

• De equivalente SQLSRV-verbinding gebruikt sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) en levert een resource terug. Het herkansingpatroon is hetzelfde: vang een false return van sqlsrv_connect, inspecteer sqlsrv_errors() voor SQLSTATE, en trek je terug voordat je opnieuw probeert. Voor een uitgewerkt voorbeeld, zie Stap 4: Maak veerkrachtig verbinding met SQL met PHP.

• De helpers lezen $e->errorInfo[1] bewaakt door isset(). PDOException::$errorInfo wordt gedeclareerd als ?array en standaard op null, dus de defensieve controle valt terug op een drivercode van 0 en laat het SQLSTATE-prefix 08 beslissen of het opnieuw probeert.

Zie voor meer informatie over elk onderdeel van deze configuratie:

• Verbindingsopties
• Verbinding maken door gebruik te maken van Microsoft Entra-verificatie
• Idle verbindingsveerkracht
• Verbinding maken met Microsoft Azure SQL Database
• Ondersteuning voor hoge beschikbaarheid, rampenherstel

Zie Tijdelijke verbindingsfouten oplossen voor de catalogus met Azure SQL tijdelijke fouten.

Belangrijkste kenmerken

• Twee API's, één driverpakket: Procedural SQLSRV voor SQL Server-eerste code, of PDO_SQLSRV voor draagbare PDO-code.
• Ondersteuning voor brede platforms: Draait op Windows, Linux en macOS met ondersteunde PHP-versies.
• Versleutelde verbindingen: TLS-versleutelde verbindingen via Encrypt=true, waarbij de validatie van servercertificaten wordt gecontroleerd door TrustServerCertificate.
• Microsoft Entra ID-authenticatie: Wachtwoordloze verbindingen met beheerde identiteit, serviceprincipal en access-token lopen via de onderliggende Microsoft ODBC-driver voor SQL Server.
• Always Encrypted: Versleuteling aan de clientzijde voor gevoelige kolommen, met optionele beveiligde enclaves voor in-place bewerkingen.
• Verbindingsveerkracht: Ingebouwde idle verbindingen proberen opnieuw met ConnectRetryCount en ConnectRetryInterval.
• PHP-stromen: Lees en schrijf grote binaire en tekenwaarden als stromen in plaats van ze in het geheugen te laden.
• Ondersteuning voor Rich SQL Server datatypes: datetimeoffset, tabelwaardige parameters, nvarchar en Unicode met PDO::SQLSRV_ENCODING_UTF8.

Get started

Configureren en verbinding maken

Authenticate

Secure

Gegevens ophalen en bijwerken

Gegevenstypen

Fouten en diagnostieken

Implementeren en gebruiken

Reference

Gerelateerde taken

Verwante inhoud

• Microsoft-drivers voor PHP voor SQL Server op GitHub
• Microsoft ODBC-stuurprogramma voor SQL Server
• SQL Server-stuurprogramma's