Driver Microsoft di PHP per SQL Server

Download del driver PHP

I Microsoft Driver per PHP per SQL Server sono estensioni PHP che puoi usare per leggere e scrivere dati nel Microsoft SQL motore di database da script PHP. Le due estensioni utilizzano lo stesso driver Microsoft ODBC per SQL Server, ma offrono API PHP diverse e opzioni specifiche per driver:

SQLSRV espone un'API procedurale (sqlsrv_*funzioni) adattata alle funzionalità di SQL Server.
PDO_SQLSRV implementa l'interfaccia PHP Data Objects (PDO). Puoi mantenere le chiamate PDO nel codice del database esistente, ma rivedi le sue query e le impostazioni specifiche del driver prima di cambiare database.

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. Entrambi i driver accettano i flussi PHP come parametri di input. SQLSRV consente il recupero di grandi valori binari e di testo come flussi. Non dare per scontato PDO_SQLSRV abbia lo stesso comportamento di streaming di output.

Scegliere il punto di partenza

Per verificare la tua installazione ed eseguire una query parametrizzata usando SQLSRV o PDO_SQLSRV, inizia con Quickstart: Connetti e consulta con i driver Microsoft per PHP.
Per installare il driver su Linux o macOS, inizia con il tutorial di installazione per Linux e macOS e scarica i driver Microsoft per PHP per SQL Server.
Per connettersi ad Azure SQL con autenticazione senza password, inizia con Connect usando le opzioni di autenticazione Microsoft Entra e Connection.
Per rendere un'app esistente resiliente ai guasti transitori, vai su Resilienza della connessione inattiva.
Per decidere tra SQLSRV e PDO_SQLSRV, vai a Panoramica dei Microsoft driver per PHP per SQL Server e Confronto delle funzioni di esecuzione.
Per diagnosticare un problema di installazione, connessione o interrogazione, vai su Risoluzione problemi, Gestione errori e avvisi, e Attività di loging.
Per rendere un'app esistente più veloce, vai su Performance tuning.

Baseline di produzione per Azure SQL

Questo PDO_SQLSRV esempio legge il server e il database dalle variabili dell'ambiente e si collega con un'identità gestita. Costruisce un nome di sorgente dati (DSN) e abilita la Transport Layer Security (TLS) con la validazione dei certificati. Leggi questi valori dalla configurazione dell'applicazione attendibile, non dai parametri delle richieste web. Esegui il programma su un host con un endpoint di identità gestita dopo aver concesso all'identità l'accesso al database.

Le funzioni helper effettuano fino a tre tentativi di connessione o esecuzione della query di sola lettura quando si verifica un errore elencato. Aspettano più a lungo tra un tentativo e l'altro, un pattern di ritentazione chiamato backoff esponenziale. Se un errore di query richiede una nuova connessione, l'helper della query lancia l'eccezione affinché il codice chiamante la gestisca.

Usa una versione supportata di PHP, l'estensione PDO_SQLSRV e Microsoft driver ODBC 18 per SQL Server. Per i valori di autenticazione supportati, vedere Connettersi tramite l'autenticazione di Microsoft Entra. Non riutilizzare l'aiutante per query per scritture o transazioni multistatement senza progettare una policy di ritenti specifica per l'applicazione: un errore non sempre ti dice se una scrittura è stata commessa.

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

Usa queste impostazioni per i gruppi di failover di database SQL di Azure e Istanza gestita di SQL di Azure.

Driver={ODBC Driver 18 for SQL Server} seleziona esplicitamente ODBC Driver 18 invece di affidarsi alla scoperta del driver. Installalo prima di eseguire l'esempio.
Imposta SQL_DATABASE sul nome effettivo del database. Il programma raddoppia le parentesi di chiusura e racchiude il nome tra parentesi prima di inserirlo nella DSN. L'escape impedisce ai caratteri speciali nel nome di cambiare il modo in cui il driver legge le impostazioni di connessione.
ConnectRetryCount e ConnectRetryInterval controllano la resilienza della connessione inattiva ODBC. Il timeout della query dell'istruzione limita il recupero durante l'esecuzione. Con il timeout di 30 secondi della query del campione, ODBC potrebbe fermarsi prima di aver esaurito tutti e cinque i tentativi di riconnessione. LoginTimeout=90 Controlla l'istituzione della connessione, non il budget di ripristino. L'aiutante a livello applicativo riprova alcuni errori server selezionati; non ritenta uno timeout della query né riproduce risultati parzialmente recuperati.
Abilita il logging dei driver insieme alle chiamate error_log() del programma. Per PDO_SQLSRV, imposta pdo_sqlsrv.log_severity in php.ini o con ini_set() in fase di esecuzione. Per SQLSRV, configurare LogSeverity e LogSubsystems con sqlsrv_configure(). 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. Usa l'argomento del nome utente del costruttore PDO invece di incorporare l'identità nel DSN. 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 una scala di lettura o un secondario leggibile, aggiungi ApplicationIntent=ReadOnly al DSN.
Usa l'endpoint fornito dal tuo servizio SQL, incluso il suo dominio specifico per il cloud. Indagare sulle discrezioni tra nome certificato invece di disabilitare la validazione dei certificati. Usa HostNameInCertificate solo quando conosci il nome atteso del certificato per quell'endpoint.
ODBC acquisisce token per l'identità gestita e l'autenticazione dell'entità servizio. Con AccessToken, la tua applicazione acquisisce il token e lo passa al driver; ODBC non lo acquisisce per te. Per maggiori informazioni, vedere la sezione Usare Microsoft Entra ID con il driver ODBC.
Tieni le informazioni di connessione al di fuori del tuo codice. Memorizzalo nel sistema di configurazione della tua applicazione e usa Azure Key Vault per i segreti.
Con SQLSRV, impostare le opzioni di connessione nell'array passava a sqlsrv_connect(). Controlla se è stato restituito false e ispeziona sqlsrv_errors() prima di decidere se riprovare. Imposta i timeout degli istruzioni separatamente con QueryTimeout. La resilienza delle connessioni inattive dimostra la riconnessione ODBC, non un ciclo di ritenti a livello applicativo.
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 PHP: SQLSRV fornisce funzioni procedurali. PDO_SQLSRV implementa PDO. Installa una delle due estensioni o entrambe.
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: Identità gestita, service principal e token di accesso acquisiti esternamente tramite il driver Microsoft ODBC per SQL Server sottostante. L'identità gestita è senza password; ActiveDirectoryServicePrincipal utilizza un client secret.
Always Encrypted: Criptare le colonne sensibili sul client, con enclave sicure per operazioni supportate su dati criptati.
Resilienza della connessione: tentativi integrati di riconnessione per connessioni inattive con ConnectRetryCount e ConnectRetryInterval.
Flussi PHP: invia grandi valori binari e valori di carattere dai parametri del flusso con una delle due API. Usa SQLSRV per il recupero in streaming.
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`.
Avvio rapido: connettersi ed eseguire query con i driver Microsoft per PHP	Verifica le estensioni, configura una connessione ed esegui la stessa query parametrizzata con SQLSRV o PDO_SQLSRV.
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 su Windows o Kerberos su Linux e macOS.

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	Trova compiti di programmazione per entrambi i conducenti.
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	Fai commit o annulla un gruppo di istruzioni insieme.
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	Imposta l'opzione `CharacterSet` di SQLSRV o l'attributo `PDO::SQLSRV_ATTR_ENCODING` di PDO_SQLSRV.
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.

Richiedere una funzionalità

Per richiedere una funzionalità, apri un problema nel Microsoft Driver for PHP per SQL Server GitHub repository.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-10-28