Driver Microsoft di PHP per SQL Server

Download del driver PHP

I Microsoft Driver per PHP per SQL Server sono estensioni PHP che permettono di leggere e scrivere dati nel Microsoft SQL motore di database da script PHP. Il pacchetto fornisce due driver che avvolgono lo stesso driver Microsoft ODBC per SQL Server e condividono le stesse opzioni di connessione, così puoi scegliere l'API che si adatta al tuo codice base:

  • SQLSRV espone un'API procedurale (sqlsrv_*funzioni) adattata alle funzionalità di SQL Server.
  • PDO_SQLSRV implementa l'interfaccia PHP Data Objects (PDO), così il codice che già utilizza PDO per altri database può indirizzare SQL Server con modifiche minime.

Entrambi i driver si collegano a database SQL di Azure, SQL database in Microsoft Fabric, Istanza gestita di SQL di Azure e tutte le versioni e edizioni supportate di SQL Server (incluse le edizioni Express). Usano flussi PHP per spostare grandi valori binari e caratteri senza caricarli completamente in memoria.

Scegliere il punto di partenza

Obiettivo Iniziare da qui
Configura un ambiente di sviluppo PHP ed esegui la tua prima query Passo 1: Configurare l'ambiente di sviluppo, poi Passo 2: Creare un database SQL e Passo 3: Prova di concetto che si collega a SQL usando PHP.
Installa il driver su Linux o macOS Tutorial di installazione per Linux e macOS e scarica i driver Microsoft per PHP per SQL Server.
Connettiti a Azure SQL con autenticazione senza password Connettiti utilizzandole opzioni di autenticazione e connessione Microsoft Entra.
Rendi un'app esistente resiliente ai guasti temporanei Resilienza della connessione inattiva e Passo 4: Collegarsi resilientemente a SQL con PHP.
Decidi tra SQLSRV e PDO_SQLSRV Panoramica dei driver Microsoft per PHP per SQL Server e Confronto delle funzioni di esecuzione.
Diagnosticare un problema di installazione, connessione o query Risoluzione dei problemi, gestione di errori e avvisi, e attività di loging.
Rendi un'app esistente più veloce Messa a punto delle prestazioni.

Collegamento rapido

Il seguente snippet è la connessione end-to-end più breve che un'installazione PHP funzionante può eseguire su SQL Server o Azure SQL. Usalo per confermare che il driver, le dipendenze ODBC e il percorso di rete siano cablati, prima di passare alla linea di produzione nella sezione successiva.

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

Per una connessione senza password contro Azure SQL, aggiungi Authentication=ActiveDirectoryMsi (identità gestita) o un altro Authentication valore alla DSN e elimina gli $user/$password argomenti. La base di produzione che segue amplia lo stesso schema con ripetizioni, timeout e diagnostici.

Per un SQL Server locale che utilizza un certificato autofirmato, Encrypt=true la validazione non viene effettuata. Aggiungi TrustServerCertificate=true solo per lo sviluppo locale. Vedi errori di certificato TLS per le alternative di produzione.

Baseline di produzione per Azure SQL

Usa questo frammento come punto di partenza per una connessione Azure SQL orientata alla produzione con il driver PDO_SQLSRV. Legge il server e il database dalle variabili dell'ambiente (ad esempio le impostazioni dell'app di Servizio app di Azure), si autentica con un'identità gestita, abilita la Transport Layer Security (TLS) con la validazione dei certificati server, imposta un timeout di accesso che copre un failover a freddo e imposta ConnectRetryCount e ConnectRetryInterval per SQL Server la resilienza delle connessioni inattive. L'applicazione connectWithRetry a livello applicativo e queryWithRetry gli helper avvolgono sia il collegamento iniziale che ogni istruzione con un backoff esponenziale limitato, e separano gli errori di connessione transitoria (che richiedono una connessione nuova) dagli errori di query transitori (che riutilizzano la stessa connessione).

Richiede PHP 8.0 e versioni successive, l'estensione PDO_SQLSRV e Microsoft driver ODBC per SQL Server 17.3.1.1 e versioni successive per Authentication=ActiveDirectoryMsi. Per l'elenco completo dei valori supportatiAuthentication, vedi Collega usando l'autenticazione Microsoft Entra.

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

Questo frammento di codice è ottimizzato per i gruppi di failover di database SQL di Azure e Istanza gestita di SQL di Azure.

  • Driver={ODBC Driver 18 for SQL Server} perna il driver ODBC 18. Se l'host ha anche ODBC 17 installato, PDO_SQLSRV può collegarsi a ODBC 17. Le versioni più vecchie 17.x rifiutano valori più Authentication recenti; ad esempio, Authentication=ActiveDirectoryMsi richiede ODBC 17.3.1.1 o una versione successiva. Vedi Valore invalido specificato per l'attributo stringa di connessione 'Authentication'.

  • ConnectRetryCounte ConnectRetryInterval sono parole chiave ODBC per stringa di connessione che abilitano la resilienza delle connessioni inattive a SQL Server: il driver riconnette trasparentmente una connessione idle danneggiata. Questo è diverso dal livello queryWithRetryapplicativo , che riprova una istruzione che fallisce con un errore transitorio come un deadlock o un timeout della query. I due sono complementari, quindi tieni entrambi. Assicurati LoginTimeout almeno ConnectRetryCount * ConnectRetryInterval che il percorso idle-reconnect abbia il suo budget completo; il campione impiega 90 secondi per coprire 5 × 15 secondi di tentativi più headroom per il login iniziale su un failover a freddo.

  • Completa le chiamate a livello error_log() di applicazione con diagnostica lato guidatore. Per PDO_SQLSRV, imposta pdo_sqlsrv.log_severity in php.ini (settabile solo all'inizializzazione); per SQLSRV, chiama sqlsrv_configure("LogSubsystems", ...) a runtime. Per ulteriori informazioni, vedi Attività di registrazione.

    ; 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

  • Per un'identità gestita assegnata dall'utente , si passa l'ID dell'identità come argomento del PDO $username (new PDO($dsn, $identityId, null, $options)). Usa l'ID client dell'identità su Servizio app di Azure o Azure Container Instance; altrimenti, usa il suo ID di oggetto. I driver PHP ereditano questo comportamento dal driver Microsoft ODBC per SQL Server sottostante; per maggiori informazioni, consulta Utilizzo di Microsoft Entra ID con il driver ODBC. PDO_SQLSRV rifiuta UID all'interno della DSN stessa, quindi usa lo slot costruttore. Passare null per utente (come fa il campione) seleziona l'identità gestita assegnata dal sistema dell'host Azure. Per SQLSRV (procedurale), passa UID l'array delle opzioni di connessione.

  • Imposta MultiSubnetFailover=true quando ti connetti a un listener di gruppo di failover, ascoltatore di gruppo di disponibilità o endpoint di istanza di cluster di failover. Impostarlo migliora le prestazioni di connessione sia per gli ascoltatori di gruppi di disponibilità single-subnet che multi-subnet. Per ulteriori informazioni, vedi Supporto per l'Alta Disponibilità, recupero in caso di disastro.

  • Per la scala di lettura o un secondario leggibile, aggiungi ApplicationIntent=ReadOnly al Data Source Name (DSN).

  • Per i cloud sovrani in cui il certificato Subject Alternative Name (SAN) non include l'host a cui ti stai collegando, aggiungi HostNameInCertificate al DSN (ad esempio, *.database.usgovcloudapi.net per Azure per enti pubblici).

  • Il driver si basa sul driver sottostante Microsoft ODBC Driver for SQL Server per l'acquisizione dei token. Gestione dell'identità, del principale di servizio e dei flussi di access-token passano tutti attraverso ODBC. Per maggiori informazioni, vedere la sezione Usare Microsoft Entra ID con il driver ODBC.

  • Per una maggiore sicurezza e portabilità tra gli ambienti, tieni le informazioni di connessione fuori dal tuo codice. Memorizza le informazioni di connessione nel sistema di configurazione della tua applicazione e usa Azure Key Vault per valori sensibili e impostazioni di connessione gestite centralmente.

  • La connessione SQLSRV equivalente utilizza sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) e restituisce una risorsa. Il pattern di ritentazione è lo stesso: cattura un false ritorno da sqlsrv_connect, ispeziona sqlsrv_errors() per SQLSTATE e si ritira prima di riprovare. Per un esempio risolto, vedi Passo 4: Collegarsi resilientemente a SQL con PHP.

  • Gli aiutanti del ritentativo leggono $e->errorInfo[1] protetti da isset(). PDOException::$errorInfo è dichiarato come ?array e di default è null, quindi il controllo difensivo torna a un codice driver di 0 e lascia che il prefisso SQLSTATE 08 decida se riprovare.

Per altre informazioni su ogni parte di questa configurazione, vedere:

Per il catalogo degli errori temporanei di Azure SQL, vedere Risolvere gli errori di connessione temporanei.

Funzionalità principali

  • Due API, un pacchetto driver: SQLSRV procedurale per codice SQL Server-first, o PDO_SQLSRV per codice PDO portatile.
  • Supporto ampio per piattaforme: Gira su Windows, Linux e macOS con versioni PHP supportate.
  • Connessioni criptate: Connessioni criptate TLS tramite Encrypt=true, con la validazione del certificato server controllata da TrustServerCertificate.
  • Autenticazione Microsoft Entra ID: Le connessioni senza password con identità gestita, principale di servizio e access-token scorrono attraverso il driver Microsoft ODBC sottostante per SQL Server.
  • Always Encrypted: crittografia lato client per colonne sensibili, con enclave sicure facoltative per operazioni eseguite sul posto.
  • Resilienza della connessione: la connessione idle integrata ritende con ConnectRetryCount e ConnectRetryInterval.
  • Flussi PHP: leggono e scrivono grandi valori binari e caratteri come flussi invece di caricarli in memoria.
  • Supporto ai tipi di dati di Rich SQL Server: datetimeoffset, parametri a valori di tabella, nvarchar e Unicode con PDO::SQLSRV_ENCODING_UTF8.

Per iniziare

Article Description
Requisiti di sistema Supporta le versioni PHP, sistema operativo e SQL Server.
Matrice di supporto Matrice dettagliata di compatibilità per le release dei driver PHP.
Scarica i driver Microsoft per PHP per SQL Server Collegamenti per il download e rilascio degli artefatti.
Tutorial di installazione per Linux e macOS Installa il driver e i suoi prerequisiti ODBC su Linux e macOS.
Caricamento dei driver Abilita le estensioni in php.ini.
Iniziare con il driver SQL PHP Walkthrough end-to-end che collega insieme i quattro passaggi di partenza.
Panoramica del driver SQL PHP Cosa c'è nel pacchetto e quando scegliere SQLSRV o PDO_SQLSRV.

Configurazione e connessione

Article Description
Connessione al server Apri una connessione a un'istanza di SQL Server da PHP.
Opzioni di connessione Riferimento completo per parole chiave di connessione, predefiniti e come impostarli.
Connessione al database SQL di Microsoft Azure Collega un'applicazione PHP a database SQL di Azure.
Collegati a una porta specifica Mira a una porta TCP non predefinita.
Pool di connessioni Riutilizza le connessioni ODBC tra le richieste PHP.
Disabilita i Multiple Active Result Set (MARS) Disattiva MARS per compatibilità.
Supporto per LocalDB Collegati a un'istanza LocalDB di SQL Server.
Supporto per l'alta disponibilità, recupero in caso di disastri Listener del gruppo di disponibilità e failover su più subnet.
Resilienza della connessione inattiva Riconnessione automatica per connessioni inattive rotte.

Authenticate

Article Description
Connettersi con l'autenticazione di Microsoft Entra Gestione dell'identità, del principale di servizio, del token di accesso e dei flussi di password.
Connettiti usando l'autenticazione SQL Server Usa un login SQL con nome utente e password.
Connettiti usando autenticazione di Windows Usa l'autenticazione integrata di Windows sugli host uniti al dominio.

Secure

Article Description
Considerazioni relative alla sicurezza Modello di minaccia e guida approfondita sulla difesa per applicazioni PHP.
Sempre crittografato con i driver PHP Configurare la crittografia lato client per le colonne sensibili.
Always Encrypted con enclave protette Abilita operazioni ricche su colonne criptate con enclave sicure.

Recupero e aggiornamento dei dati

Article Description
Guida alla programmazione Guida di programmazione end-to-end per entrambi i driver.
Confronto delle funzioni di esecuzione Scegli la funzione di esecuzione giusta per il tuo carico di lavoro.
Esecuzione diretta e preparata delle istruzioni (PDO_SQLSRV) Quando utilizzare l'esecuzione diretta rispetto a quelle preparate.
Recupero dei dati Prendi righe, colonne e valori di streaming.
Aggiornamento dei dati Inserire, aggiornare ed eliminare righe.
Eseguire query parametrizzate Associare parametri per proteggere dall'iniezione SQL.
Invia dati come flusso Trasmetti grandi valori binari e caratteri in SQL Server.
Eseguire transazioni Gruppi di estratti conto in transazioni atomiche.
Usa parametri a valori di tabella Passa un TABLE parametro a una procedura memorizzata.
Specifica un tipo di cursore e seleziona le righe Scegli cursori solo forward, statici, dinamici o keyset.

Tipi di dati

Article Description
Conversione dei tipi di dati Come il driver mappa i tipi PHP ai tipi SQL Server.
Tipi di dati predefiniti di SQL Server Tipo predefinito di SQL Server per ogni valore PHP.
Tipi di dati PHP predefiniti Tipo di PHP predefinito per ogni tipo di colonna SQL Server.
Specificare i tipi di dati SQL Server (SQLSRV) Sovrascrivi il tipo SQL Server quando binding i parametri.
Specificare i tipi di dati PHP Sovrascrivi il tipo PHP quando lo recuperi.
Invia e recupera i dati UTF-8 Da usare PDO::SQLSRV_ENCODING_UTF8 per i viaggi Unicode andata e ritorno.
Invia e recupera dati ASCII su Linux e macOS Gestire i viaggi andata e ritorno ASCII su host non Windows.
Formata decimali e denaro (SQLSRV) Formatta le colonne decimali e monete con il driver SQLSRV.
Formato decimali e denaro (PDO_SQLSRV) Formatta le colonne decimali e monete con il driver PDO_SQLSRV.
Impostazioni di località non di sistema Separatori decimali localizzati e altre considerazioni geografiche.

Errori e diagnostiche

Article Description
Errori e avvisi di gestione Errori e avvisi di gestione con entrambi i piloti.
Configura la gestione errori e avvisi (SQLSRV) Ottimizza come il driver SQLSRV segnala errori e avvisi.
Gestire errori e avvisi (SQLSRV) Ispezionare gli errori restituiti dalle funzioni SQLSRV.
Attività forestale Abilita il logging dei driver per la cattura diagnostica.

Distribuire e gestire

Article Description
Ottimizzazione delle prestazioni Gestione delle connessioni, batching, istruzioni preparate, cursori, memoria e monitoraggio lato server.
Risoluzione dei problemi Diagnosticare problemi comuni di installazione, connessione, query, tipo di dato, transazione e container.

Reference

Article Description
Riferimento API driver SQLSRV Tutte sqlsrv_* le funzioni, parametri e valori di ritorno.
PDO_SQLSRV riferimento al pilota Metodi PDO e PDOStatement supportati dal driver PDO_SQLSRV.
Costanti Costanti esposte dai driver, inclusi il tipo e le costanti di codifica.
Article Description
Note di rilascio Cronologia per versione con nuove funzionalità, correzioni di bug, modifiche al supporto della piattaforma e link per il download.
Informazioni sugli esempi di codice nella documentazione Convenzioni utilizzate dai campioni di codice in questa sezione.
Esempi di codice per il driver SQL PHP Applicazioni end-to-end per SQLSRV e PDO_SQLSRV.
Risorse di supporto Canali di comunità e supporto.

Contenuto correlato

  • Last updated on