Panoramica dei driver Microsoft per PHP per SQL Server

Download del driver PHP

I driver Microsoft per PHP per SQL Server includono due estensioni PHP, SQLSRV e PDO_SQLSRV. PDO_SQLSRV implementa l'interfaccia PHP Data Objects (PDO). Entrambe le estensioni utilizzano il driver Microsoft ODBC per SQL Server per connettersi a Microsoft SQL. Le loro API PHP, le opzioni specifiche per driver e i tipi di PHP predefiniti differiscono. Ad esempio, SQLSRV restituisce valori di data e ora come DateTime oggetti di default, mentre PDO_SQLSRV restituisce stringhe di default. Per i requisiti di sistema, vedi Requisiti di sistema per i driver Microsoft per PHP per SQL Server.

Scegli SQLSRV o PDO_SQLSRV

Se... Utilizza
Stai iniziando un nuovo progetto senza altro codice PDO Scegli l'interfaccia che la tua applicazione userà in modo coerente. SQLSRV espone funzioni procedurali e descrittori espliciti di parametri. PDO_SQLSRV si adatta al codice organizzato attorno agli oggetti PDO e PDOStatement.
Uso già PDO con un altro database (MySQL, PostgreSQL, SQLite) PDO_SQLSRV, quindi il tuo livello di accesso ai dati rimane coerente tra i database.
Usa un framework o una libreria che si aspetti un oggetto di connessione PDO PDO_SQLSRV.
Serve un controllo manuale, blocco per blocco, su quando vengono inviati i dati del flusso SQLSRV, usando sqlsrv_send_stream_data(). PDO_SQLSRV inoltre trasmette anche valori di grandi dimensioni in streaming, legando una risorsa PHP con PDO::PARAM_LOB, ma invia l'intero flusso automaticamente durante execute() invece che in blocchi controllati dal chiamante.
Mantenere un'applicazione che già chiama funzioni sqlsrv_* SQLSRV, a meno che tu non abbia intenzione di riscrivere il suo codice di accesso ai dati per il PDO.

Installa una delle due estensioni oppure entrambe. I download di Windows contengono binari di estensione separati; su Linux e macOS, installa separatamente i pacchetti e . Puoi caricare entrambi nello stesso processo PHP. SQLSRV restituisce risorse di connessione e risorse di istruzione; PDO_SQLSRV restituisce oggetti PDO e PDOStatement. Non passare una risorsa da un'API all'altra.

L'uso di PDO non rende portabile la sintassi di Transact-SQL (T-SQL) su un altro database. PDO ti offre un'interfaccia PHP comune; le tue query, lo schema, l'autenticazione e gli attributi specifici del driver possono ancora dipendere da Microsoft SQL. Allo stesso modo, l'uso dell'estensione procedurale non richiede un'organizzazione procedurale in tutta l'applicazione: puoi chiamare SQLSRV dalle tue classi.

Confronta lo stesso risultato in entrambe le API

Esegui questi programmi prima di scegliere la rappresentazione PHP che la tua applicazione si aspetta. Selezionano lo stesso NULL integer, date e SQL, ma i valori predefiniti non sono identici. Non sono richieste tabelle o database di esempio.

Installa e carica l'estensione selezionata. Imposta SQL_SERVER, SQL_DATABASE, SQL_USER, e SQL_PASSWORD nell'ambiente di processo per un database di test SQL Server esistente. Il certificato server deve essere affidabile e corrispondere all'endpoint configurato. Per la configurazione e le alternative di Azure senza password, vedi Connessione al server.

SQLSRV

Salva questo programma completo come compare-sqlsrv.php, e esegui php compare-sqlsrv.php.

<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name before running this example.");
    }
    $config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$conn = sqlsrv_connect($config['SQL_SERVER'], [
    'Database' => $config['SQL_DATABASE'],
    'UID' => $config['SQL_USER'],
    'PWD' => $config['SQL_PASSWORD'],
    'Encrypt' => true,
    'TrustServerCertificate' => false,
    'LoginTimeout' => 30,
    'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$stmt = null;
try {
    $stmt = sqlsrv_query($conn, "SELECT CAST(42 AS int) AS CountValue, "
        . "CAST('2026-10-19' AS date) AS DayValue, CAST(NULL AS int) AS Missing");
    if ($stmt === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    $row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    if (!is_array($row) || $row['CountValue'] !== 42
        || !($row['DayValue'] instanceof DateTime)
        || $row['DayValue']->format('Y-m-d') !== '2026-10-19'
        || $row['Missing'] !== null) {
        throw new RuntimeException('Unexpected SQLSRV values or default types.');
    }
    echo get_debug_type($row['CountValue']), ', ',
        get_debug_type($row['DayValue']), ', ', get_debug_type($row['Missing']), PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

Output previsto:

int, DateTime, null

PDO_SQLSRV

Salva questo programma separato come compare-pdo.php, e esegui php compare-pdo.php. Lascia deliberatamente il recupero dei valori numerici e delle date ai rispettivi valori predefiniti di PDO_SQLSRV.

<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name before running this example.");
    }
    $config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$server = $config['SQL_SERVER'];
$database = $config['SQL_DATABASE'];
$pdo = new PDO(
    "sqlsrv:Server=$server;Database=$database;Encrypt=true;"
    . "TrustServerCertificate=false;LoginTimeout=30",
    $config['SQL_USER'],
    $config['SQL_PASSWORD'],
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
    ]
);
$stmt = null;
try {
    $stmt = $pdo->query("SELECT CAST(42 AS int) AS CountValue, "
        . "CAST('2026-10-19' AS date) AS DayValue, CAST(NULL AS int) AS Missing");
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['CountValue' => '42', 'DayValue' => '2026-10-19', 'Missing' => null]) {
        throw new RuntimeException('Unexpected PDO_SQLSRV values or default types.');
    }
    echo get_debug_type($row['CountValue']), ', ',
        get_debug_type($row['DayValue']), ', ', get_debug_type($row['Missing']), PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

Output previsto:

string, string, null

Entrambi i programmi richiedono esplicitamente chiavi di risultato nominate. Questi array PHP utilizzano nomi di colonne come CountValue, invece di indici numerici basati su zero. Un SQL NULL diventa PHP null in entrambe le API. Non è la stringa vuota o una riga di risultati mancante.

Entrambi i programmi leggono il nome effettivo del database, il nome utente e la password dall'ambiente. Eseguono l'escape di questi valori una volta per la gestione delle connessioni in stile ODBC del driver PHP. Raddoppiare le parentesi di chiusura e racchiudere il valore tra parentesi preserva i caratteri speciali; non rinomina il database né cambia la password memorizzata. Per maggiori informazioni, vedi Connessione al server.

Gli esempi si interrompono in caso di errore e rilasciano risorse in finally. SQLSRV segnala i fallimenti del database tramite false e sqlsrv_errors(); PDO_SQLSRV genera eccezioni in caso di errori di connessione e utilizza eccezioni per i fallimenti delle query con la modalità di errore configurata. In un'applicazione web, intercetta queste eccezioni nel codice che gestisce la richiesta. Registra i dettagli diagnostici in log protetti invece di restituirli a un browser.

Dopo l'esercizio, cancella compare-sqlsrv.php e compare-pdo.php se non ne hai più bisogno. Elimina le variabili di ambiente delle credenziali dal processo di test una volta terminato.

Scegli i tipi, la codifica e la gestione degli errori

Decidi quali tipi di PHP la tua applicazione si aspetta, come gestisce testo ed errori, e quando rilascia risorse del database.

Decisione SQLSRV PDO_SQLSRV Effetto sul codice applicativo
Tipi di risultato intero Interi nativi di PHP per colonne SQL int. Stringhe per impostazione predefinita; PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE richiedono il supporto per i tipi PHP numerici. I confronti rigorosi e i risultati serializzati possono differire. Non dare per scontato che ogni tipo numerico SQL corrisponda a un intero o float PHP.
Risultati di data e ora DateTime oggetti di default; ReturnDatesAsStrings seleziona le stringhe. Stringhe per impostazione predefinita; PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE seleziona oggetti. Normalizza la rappresentazione prima di serializzare o passarla al codice applicativo.
Codifica dei caratteri Impostare CharacterSet => 'UTF-8' in modo esplicito. UTF-8 è il valore predefinito; configuralo con PDO::SQLSRV_ATTR_ENCODING. Non trasferire l'opzione SQLSRV in un DSN PDO.
Gestione degli errori Controlla false e cattura immediatamente l'intera collezione di errori SQLSRV. Configurare PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION. Una riga mancante e una query fallita richiedono una gestione diversa.
Riutilizzo dei parametri Lega le variabili per riferimento nei descrittori sqlsrv_prepare(). Usa bindParam() per una variabile o bindValue() per il suo valore corrente. La riassegnazione della variabile influisce su un binding di riferimento, non su un binding di valore precedente.
Cleanup Dichiarazioni libere, poi chiudi la risorsa di connessione. Riferimenti alle dichiarazioni di rilascio, poi all'oggetto PDO. Un'istruzione può mantenere viva una connessione PDO dopo che un altro riferimento è stato impostato su null.

Se migri un'applicazione esistente, testa questi comportamenti con valori rappresentativi prima di modificare il codice del database. Includere testo non ASCII, SQL NULL, date, valori decimali esatti e parametri di output delle procedure memorizzate. Confronta anche come il tuo framework configura gli attributi PDO. Sostituire solo i nomi delle funzioni non migra la gestione degli errori, il binding di riferimento o i tipi PHP restituiti.

Per un flusso di lavoro di scrittura e lettura funzionato con entrambe le API, usa la guida alla programmazione. Per esecuzioni ripetute e input tipizzati, si usano le funzioni di esecuzione Compare query.

Sapere cosa fa ogni componente

La scelta dell'estensione modifica l'API PHP e le conversioni dei suoi tipi. Entrambe le estensioni utilizzano ODBC per comunicare con il server, criptare le connessioni e autenticarsi. Il sistema operativo fornisce certificati e servizi affidabili come autenticazione di Windows o Kerberos. Il target SQL controlla permessi, schema e istruzioni T-SQL supportate.

I programmi di confronto utilizzano l'autenticazione SQL per SQL Server. Per database SQL di Azure, Istanza gestita di SQL di Azure, Azure Synapse Analytics, SQL database in Fabric o Warehouse in Fabric, configura l'endpoint del servizio e l'autenticazione supportata prima di riutilizzare il fetch pattern. Entrambi i prodotti Fabric richiedono l'autenticazione Microsoft Entra ID; Warehouse richiede anche di disabilitare i set di risultati attivi multipli (MARS). Un confronto di tipo riuscito su SQL Server non stabilisce che un target diverso supporti ogni funzionalità elencata in questa panoramica.

Cosa offrono entrambe le estensioni

  • Autenticazione integrata, autenticazione SQL e autenticazione Microsoft Entra ID, a seconda del supporto del target. L'identità gestita non utilizza una password applicativa; ActiveDirectoryServicePrincipal utilizza un ID client e un client secret. Per maggiori informazioni, vedi Connessione al server.
  • Query parametrizzate, istruzioni preparate e parametri direzionali (input/output). Per maggiori informazioni, vedi Confronto delle funzioni di esecuzione e Utilizzo dei parametri direzionali.
  • Transazioni, parametri di input di flusso per valori di carattere e binari grandi, e parametri a valori di tabella.
  • Sempre criptato, inclusi enclave sicuri dove il driver ODBC e il target SQL Server li supportano. Per maggiori informazioni, consulta Using Always Encrypted with the Microsoft Drivers for PHP for SQL Server.
  • Connessioni a SQL Server, database SQL di Azure, Istanza gestita di SQL di Azure, Azure Synapse Analytics, database SQL in Microsoft Fabric e Warehouse in Microsoft Fabric. Le funzionalità di autenticazione e SQL variano a seconda della destinazione; vedi connessioni Azure e Fabric.

Contenuti correlati

  • Ultimo aggiornamento: