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

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. Gli helper a livello applicativo connectWithRetry e queryWithRetry gestiscono sia la connessione iniziale sia ogni istruzione con un backoff esponenziale limitato e separano gli errori di connessione temporanei, che richiedono una nuova connessione, dagli errori temporanei di query, 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} blocca il driver ODBC alla versione 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. Ciò è distinto da queryWithRetry a livello applicativo, che esegue nuovamente un' istruzione che non riesce a causa di un errore transitorio, ad esempio un deadlock o un timeout di query. I due sono complementari, quindi tieni entrambi. Assicurati che LoginTimeout sia almeno ConnectRetryCount * ConnectRetryInterval in modo che il percorso di riconnessione dopo inattività disponga del suo budget completo; l'esempio usa 90 secondi per coprire 5 tentativi da 15 secondi più un margine per l'accesso iniziale in caso di 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 (può essere impostato solo all'inizializzazione); per SQLSRV, richiama sqlsrv_configure("LogSubsystems", ...) in fase di esecuzione. 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, passare l'ID dell'identità come argomento $username di PDO (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 nel DSN stesso, quindi usa il parametro del costruttore. Passando null come utente (come fa l'esempio) si seleziona l'identità gestita assegnata dal sistema dell'host Azure. Per SQLSRV (procedurale), passa UID nell'array delle opzioni di connessione.

  • Imposta MultiSubnetFailover=true quando ti connetti a un listener del gruppo di failover, a un listener del gruppo di disponibilità o a un endpoint dell'istanza del cluster di failover. L'impostazione di questo parametro migliora le prestazioni di connessione sia per i listener 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 scalabilità in lettura o per una replica secondaria leggibile, aggiungi ApplicationIntent=ReadOnly al nome origine dati (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.

  • Le funzioni di supporto per il nuovo tentativo leggono $e->errorInfo[1] con la protezione di 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 di driver: SQLSRV procedurale per codice pensato prima di tutto per SQL Server, oppure PDO_SQLSRV per codice PDO portabile.
  • 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: tentativi integrati di riconnessione per connessioni inattive 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 Guida completa che collega i quattro passaggi introduttivi.
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 set di risultati attivi multipli (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 delle connessioni inattive interrotte.

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.
Connettersi tramite l'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 avanzate su colonne crittografate 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 anziché le istruzioni preparate.
Recupero dei dati Recupera righe, colonne e valori in streaming.
Aggiornamento dei dati Inserire, aggiornare ed eliminare righe.
Eseguire query parametrizzate Associare parametri per proteggere dall'iniezione SQL.
Invia dati come un flusso Trasmetti grandi valori binari e caratteri in SQL Server.
Eseguire transazioni Raggruppa le istruzioni 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 i cursori a solo avanzamento, 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) Ignora il tipo di SQL Server durante l'associazione dei parametri.
Specificare i tipi di dati PHP Forza il tipo PHP in fase di recupero.
Invia e recupera i dati UTF-8 Usare PDO::SQLSRV_ENCODING_UTF8 per le conversioni Unicode di andata e ritorno.
Invia e recupera dati ASCII su Linux e macOS Gestire le conversioni di andata e ritorno ASCII su host non Windows.
Formattare i decimali e i valori monetari (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 locali non di sistema Separatori decimali localizzati e altre considerazioni geografiche.

Errori e diagnostiche

Article Description
Errori e avvisi di gestione Gestione di errori e avvisi con entrambi i driver.
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à di registrazione Abilita il logging dei driver per l'acquisizione diagnostica.

Distribuire e gestire

Article Description
Ottimizzazione delle prestazioni Gestione delle connessioni, batching, istruzioni preparate, cursori, memoria e monitoraggio lato server.
Risoluzione dei problemi Individuare problemi comuni di installazione, connessione, query, tipi di dati, transazioni e container.

Contenuto di riferimento

Article Description
Informazioni di riferimento sull'API del driver SQLSRV Tutte sqlsrv_* le funzioni, parametri e valori di ritorno.
Riferimento del driver PDO_SQLSRV 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 di esempio complete per SQLSRV e PDO_SQLSRV.
Risorse di supporto Canali di comunità e supporto.

Contenuto correlato

  • Last updated on