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

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 helpers op applicatieniveau connectWithRetry en queryWithRetry voorzien zowel de initiële verbinding als elk statement van een begrensde exponentiële backoff, en maken onderscheid tussen tijdelijke verbindingsfouten (waarvoor een nieuwe verbinding nodig is) en tijdelijke queryfouten (waarbij dezelfde verbinding wordt hergebruikt).

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} vergrendelt het ODBC-stuurprogramma 18. 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.

  • ConnectRetryCount en ConnectRetryInterval zijn trefwoorden in de ODBC-verbindingsreeks die de SQL Server-functie veerkracht bij inactieve verbindingen inschakelen: de driver herstelt transparant een verbroken inactieve verbinding. Dat verschilt van het toepassingsniveau queryWithRetry, dat een statement dat mislukt door een tijdelijke fout, zoals een deadlock of een time-out van een query, opnieuw uitvoert. De twee vullen elkaar aan, dus houd ze allebei. Zorg ervoor dat LoginTimeout ten minste ConnectRetryCount * ConnectRetryInterval is, zodat het pad voor inactieve herverbinding de volledige tijdsmarge krijgt; in het voorbeeld wordt 90 seconden gebruikt om 5 × 15 seconden aan nieuwe pogingen plus extra marge voor de eerste aanmelding bij een koude failover op te vangen.

  • Vul de aanroepen op applicatieniveau error_log() aan met diagnostiek aan de bestuurderskant. Voor PDO_SQLSRV stelt u pdo_sqlsrv.log_severity in php.ini in (alleen instelbaar bij initialisatie); voor SQLSRV roept u sqlsrv_configure("LogSubsystems", ...) aan tijdens de uitvoering. Voor meer informatie, zie Logboekactiviteit.

    ; 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 weigert UID in de DSN zelf, dus gebruik de constructorparameter. Door null als gebruiker op te geven (zoals in het voorbeeld), selecteer je de door het systeem toegewezen beheerde identiteit van de Azure-host. Voor SQLSRV (procedureel) geef je UID door in de array met verbindingsopties.

  • Stel MultiSubnetFailover=true in wanneer je verbinding maakt met een listener van een failovergroep, listener van een beschikbaarheidsgroep of eindpunt van een failoverclusterexemplaar. Door dit in te stellen verbeteren de verbindingsprestaties voor listeners van beschikbaarheidsgroepen met zowel één subnet als meerdere subnetten. 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 cloudomgevingen waarbij de host waarmee je verbinding maakt niet is opgenomen in de Subject Alternative Name (SAN) van het certificaat, voeg je HostNameInCertificate toe aan de 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-tokenstromen 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 patroon voor opnieuw proberen is hetzelfde: vang een false-retourwaarde van sqlsrv_connect op, controleer sqlsrv_errors() op SQLSTATE en wacht even voordat je het opnieuw probeert. Voor een uitgewerkt voorbeeld, zie Stap 4: Maak veerkrachtig verbinding met SQL met PHP.

  • De retry-helpers lezen $e->errorInfo[1], beveiligd door isset(). PDOException::$errorInfo is gedeclareerd als ?array en heeft standaardwaarde null, dus de defensieve controle grijpt terug op een drivercode van 0 en laat het voorvoegsel 08 van SQLSTATE bepalen of er opnieuw wordt geprobeerd.

Zie voor meer informatie over elk onderdeel van deze configuratie:

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

Artikel Description
Systeemvereisten Ondersteunde PHP-, besturingssysteem- en SQL Server-versies.
Ondersteuningsmatrix Gedetailleerde compatibiliteitsmatrix voor PHP-driverreleases.
Download de Microsoft-drivers voor PHP voor SQL Server Download links en vrijgave artefacten.
Installatiehandleiding voor Linux en macOS Installeer de driver en de ODBC-vereisten op Linux en macOS.
Stuurprogramma's laden Schakel de extensies in php.ini.
Beginnen met de PHP SQL-driver Een volledige walkthrough die de vier beginstappen met elkaar verbindt.
Overzicht van de PHP SQL-driver Wat zit er in het pakket, en wanneer je SQLSRV of PDO_SQLSRV moet kiezen.

Configureren en verbinding maken

Artikel Description
Verbinding maken met de server Open een verbinding met een SQL Server-instantie vanuit PHP.
Verbindingsopties Volledige referentie voor verbindingszoekwoorden, standaardwaarden en hoe je die instelt.
Verbinding maken met Microsoft Azure SQL Database Verbind een PHP-applicatie met Azure SQL Database.
Verbind op een gespecificeerde poort Richt je op een niet-standaard TCP-poort.
Groepsgewijze verbindingen Hergebruik ODBC-verbindingen over PHP-verzoeken heen.
Schakel meerdere actieve resultaatsets uit (MARS) Zet MARS uit voor compatibiliteit.
Ondersteuning voor LocalDB Maak verbinding met een SQL Server LocalDB-instantie.
Ondersteuning voor hoge beschikbaarheid, rampenherstel Listeners voor beschikbaarheidsgroepen en failover met meerdere subnetten.
Idle verbindingsveerkracht Automatische herverbinding bij verbroken idle verbindingen.

Authenticate

Artikel Description
Verbinding maken door gebruik te maken van Microsoft Entra-verificatie Beheerde identiteit, dienstprincipal, toegangstoken en wachtwoordstromen.
Verbind met SQL Server-authenticatie Gebruik een SQL-login met een gebruikersnaam en wachtwoord.
Maak verbinding met Windows authentication Gebruik Windows-geïntegreerde authenticatie op domein-gekoppelde hosts.

Secure

Artikel Description
Beveiligingsoverwegingen Richtlijnen voor het dreigingsmodel en gelaagde verdediging voor PHP-toepassingen.
Altijd versleuteld met de PHP-drivers Configureer versleuteling aan de clientzijde voor gevoelige kolommen.
Always Encrypted met beveiligde enclaves Maak uitgebreide bewerkingen op versleutelde kolommen mogelijk met veilige enclaves.

Gegevens ophalen en bijwerken

Artikel Description
Programmeergids Volledige programmeerhandleiding voor beide stuurprogramma's.
Uitvoeringsfuncties vergelijken Kies de juiste uitvoeringsfunctie voor jouw werkdruk.
Directe en voorbereide instructie-uitvoering (PDO_SQLSRV) Wanneer gebruik je directe uitvoering in plaats van prepared statements.
Data ophalen Haal rijen, kolommen en streamingwaarden op.
Gegevens bijwerken Rijen invoegen, updaten en verwijderen.
Voer geparametriseerde queries uit Bind parameters om SQL-injectie te voorkomen.
Gegevens verzenden als gegevensstroom Grote binaire en tekenreekswaarden streamen naar SQL Server.
Transacties uitvoeren Groepeer instructies in atomaire transacties.
Gebruik tabelwaardenparameters Geef een TABLE parameter door aan een opgeslagen procedure.
Specificeer een cursortype en selecteer rijen Kies alleen vooruit-, statische, dynamische of keyset-cursors.

Gegevenstypen

Artikel Description
Omzetten van datatypen Hoe de driver PHP-types koppelt aan SQL Server-types.
Standaard SQL Server datatypes Standaard SQL Server-type voor elke PHP-waarde.
Standaard PHP-datatypes Standaard PHP-type voor elk kolomtype van SQL Server.
Specificeer SQL Server-datatypes (SQLSRV) Overschrijven van het SQL Server-type bij het koppelen van parameters.
Specificeer PHP-datatypes Overschrijf het PHP-type bij het ophalen.
Verzenden en ophalen UTF-8 gegevens Gebruik PDO::SQLSRV_ENCODING_UTF8 voor Unicode-roundtrips.
ASCII-gegevens verzenden en ophalen op Linux en macOS Verwerk ASCII-retourconversies op hosts die geen Windows gebruiken.
Formateer decimalen en geld (SQLSRV) Decimal- en moneykolommen opmaken met de SQLSRV-driver.
Decimale getallen en geld opmaken (PDO_SQLSRV) Formateer kolommen van het type decimal en money met de PDO_SQLSRV-driver.
Niet-systeemlocatie-instellingen Gelokaliseerde decimale scheiders en andere lokale overwegingen.

Fouten en diagnostieken

Artikel Description
Afhandelingsfouten en waarschuwingen Fout- en waarschuwingsverwerking met beide stuurprogramma's.
Configuratie van fout- en waarschuwingsbehandeling (SQLSRV) Stel af hoe de SQLSRV-driver fouten en waarschuwingen rapporteert.
Omgaan met fouten en waarschuwingen (SQLSRV) Inspecteer fouten die door SQLSRV-functies worden teruggegeven.
Registratieactiviteit Schakel logboekregistratie van het stuurprogramma in om diagnostische gegevens vast te leggen.

Implementeren en gebruiken

Artikel Description
Performance-optimalisatie Verbindingsbeheer, batching, voorbereide instructies, cursors, geheugen en server-side monitoring.
Troubleshooting Diagnoseer veelvoorkomende problemen met installaties, verbindingen, querys, datatypes, transacties en containers.

Referentiemateriaal

Artikel Description
SQLSRV-driver API-referentie Alle sqlsrv_* functies, parameters en retourwaarden.
Naslagwerk voor het PDO_SQLSRV-stuurprogramma PDO- en PDOStatement-methoden die worden ondersteund door de PDO_SQLSRV driver.
Constanten Constanten die door de drivers worden blootgelegd, inclusief type- en coderingsconstanten.
Artikel Description
Opmerkingen bij de release Per-versiegeschiedenis met nieuwe functies, bugfixes, wijzigingen in platformondersteuning en downloadlinks.
Over codevoorbeelden in de documentatie Conventies die in de codevoorbeelden in deze sectie worden gebruikt.
Codevoorbeelden voor de PHP SQL-driver End-to-end voorbeeldapplicaties voor SQLSRV en PDO_SQLSRV.
Ondersteunende bronnen Community en ondersteuningskanalen.

Verwante inhoud

  • Last updated on