Microsoft-stuurprogramma's voor PHP voor SQL Server

PHP-stuurprogramma downloaden

De Microsoft Drivers voor PHP voor SQL Server zijn PHP-extensies die je kunt gebruiken om data te lezen en te schrijven in de Microsoft SQL Database Engine vanuit PHP-scripts. De twee extensies gebruiken dezelfde Microsoft ODBC-driver voor SQL Server, maar bieden verschillende PHP-API's en driver-specifieke opties:

• SQLSRV biedt een procedurele API (sqlsrv_*functies) die is afgestemd op SQL Server-functies.
• PDO_SQLSRV implementeert de PHP Data Objects (PDO) -interface. Je kunt de PDO-aanroepen in bestaande databasecode houden, maar bekijk de query's en driverspecifieke instellingen voordat je overstapt naar een andere database.

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. Beide stuurprogramma's accepteren PHP-streams als invoerparameter. SQLSRV ondersteunt het ophalen van grote binaire en tekenwaarden als streams. Ga er niet van uit dat PDO_SQLSRV hetzelfde output-streaming gedrag vertoont.

Uw beginpunt kiezen

• Om je installatie te verifiëren en een geparametriseerde query uit te voeren met SQLSRV of PDO_SQLSRV, begin je met Quickstart: Verbind en zoek op met de Microsoft Drivers voor PHP.
• Om de driver op Linux of macOS te installeren, begin je met de installatietutorial voor Linux en macOS en download je de Microsoft-drivers voor PHP voor SQL Server.
• Om verbinding te maken met Azure SQL met wachtwoordloze authenticatie, begin je met Connect via Microsoft Entra-authenticatie en Connection-opties.
• Om een bestaande app bestand te maken tegen tijdelijke storingen, kies je voor Idle connection resiliency.
• Om te kiezen tussen SQLSRV en PDO_SQLSRV, ga naar Overzicht van de Microsoft drivers voor PHP voor SQL Server en het vergelijken van uitvoeringsfuncties.
• Om een installatie-, verbindings- of queryprobleem te diagnosticeren, ga je naar Probleemoplossing, Fouten en waarschuwingen afhandelen, en Logging activiteit.
• Om een bestaande app sneller te maken, ga naar Performance tuning.

Productiebasislijn voor Azure SQL

Dit PDO_SQLSRV voorbeeld leest de server en database uit omgevingsvariabelen en maakt verbinding met een beheerde identiteit. Het bouwt een databronnaam (DSN) en maakt Transport Layer Security (TLS) mogelijk met certificaatvalidatie. Lees deze waarden uit de vertrouwde applicatieconfiguratie, niet uit webverzoekparameters. Voer het programma uit op een host met een managed identity-eindpunt nadat de identiteit toegang tot de database heeft gekregen.

De hulpfuncties maken tot drie pogingen om verbinding te maken of de alleen-lezenquery uit te voeren wanneer een vermelde fout optreedt. Ze wachten langer tussen pogingen, een herpogingspatroon dat exponentiële backoff wordt genoemd. Als een queryfout een nieuwe verbinding vereist, gooit de queryhelper de uitzondering zodat de aanroepende code deze kan afhandelen.

Gebruik een ondersteunde PHP-versie, de PDO_SQLSRV-extensie en Microsoft ODBC Driver 18 voor SQL Server. Voor ondersteunde authenticatiewaarden raadpleegt u Verbinding maken met Microsoft Entra-authenticatie. Gebruik de queryhelper niet opnieuw voor writes of multistatement-transacties zonder een applicatie-specifiek retry-beleid te ontwerpen: een fout vertelt je niet altijd of een write is committed.

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

Gebruik deze instellingen voor Azure SQL Database failover-groepen en Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} selecteert ODBC Driver 18 expliciet in plaats van te vertrouwen op driverontdekking. Installeer het voordat je het voorbeeld uitvoert.

• Stel SQL_DATABASE in op de daadwerkelijke databasenaam. Het programma verdubbelt sluitaccolades en plaatst de naam tussen accolades voordat deze in de DSN wordt geplaatst. Escaping voorkomt dat speciale tekens in de naam van invloed zijn op hoe de driver de verbindingsinstellingen leest.

• ConnectRetryCount en ConnectRetryInterval regelen de tolerantie van inactieve ODBC-verbindingen voor storingen. De querytime-out van de instructie begrenst herstel tijdens de uitvoering. Met de 30 seconden durende query-time-out van het voorbeeld kan ODBC stoppen voordat alle vijf herverbindingspogingen zijn uitgeput. LoginTimeout=90 regelt het tot stand brengen van de verbinding, niet het herstelbudget. De helper op applicatieniveau probeert geselecteerde serverfouten opnieuw; hij probeert een querytimeout niet opnieuw en verwerkt gedeeltelijk opgehaalde resultaten niet opnieuw.

• Schakel driverlogging in samen met de aanroepen error_log() van het programma. Voor PDO_SQLSRV stel pdo_sqlsrv.log_severity in in php.ini of met ini_set() tijdens runtime. Voor SQLSRV configureer LogSeverity en LogSubsystems met sqlsrv_configure(). 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. Gebruik het gebruikersnaamargument van de PDO-constructor in plaats van de gebruikersnaam in het DSN in te bedden. 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 versie, voeg ApplicationIntent=ReadOnly toe aan de DSN.

• Gebruik het endpoint dat door je SQL-service wordt geleverd, inclusief het cloud-specifieke domein. Onderzoek afwijkingen tussen certificaatnamen in plaats van certificaatvalidatie uit te schakelen. Gebruik HostNameInCertificate alleen wanneer je de verwachte certificaatnaam voor dat eindpunt kent.

• ODBC verwerft tokens voor beheerde identiteit en service principal-authenticatie. Met AccessToken verkrijgt uw applicatie het token en geeft dit door aan het stuurprogramma; ODBC verkrijgt het niet voor u. Zie Microsoft Entra-id gebruiken met het ODBC-stuurprogrammavoor meer informatie.

• Houd de verbindingsinformatie buiten je code. Sla het op in het configuratiesysteem van je applicatie en gebruik Azure Key Vault voor geheimen.

• Met SQLSRV stel je verbindingsopties in de array die aan sqlsrv_connect()wordt doorgegeven. Controleer of je een retourwaarde van false hebt en inspecteer sqlsrv_errors() voordat je beslist of je het opnieuw probeert. Stel statement-time-outs afzonderlijk in met QueryTimeout. Veerkracht van inactieve verbindingen demonstreert ODBC-herverbinding, niet een retrylus op applicatieniveau.

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

• 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 PHP-API's: SQLSRV biedt procedurele functies. PDO_SQLSRV implementeert PDO. Installeer één extensie of beide.
• 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: Beheerde identiteit, service principal en extern verkregen toegangstokens via de onderliggende Microsoft ODBC-driver voor SQL Server. Managed Identity is wachtwoordloos; ActiveDirectoryServicePrincipal gebruikt een client secret.
• Always Encrypted: Versleutel gevoelige kolommen op de client, met veilige enclaves voor ondersteunde bewerkingen op versleutelde data.
• Verbindingsveerkracht: Ingebouwde idle verbindingen proberen opnieuw met ConnectRetryCount en ConnectRetryInterval.
• PHP-stromen: Stuur grote binaire en tekenwaarden van stroomparameters met een van beide API's. Gebruik SQLSRV voor gestreamde retrieval.
• 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

Referentiemateriaal

Gerelateerde taken

Verzoeken om een functie toe te voegen

Om een functie aan te vragen, open je een issue in de Microsoft Drivers for PHP voor SQL Server GitHub repository.

Verwante inhoud

• Microsoft-drivers voor PHP voor SQL Server op GitHub
• Microsoft ODBC-stuurprogramma voor SQL Server
• Microsoft SQL-stuurprogramma’s en frameworks