Requisiti di sistema dei driver Microsoft per PHP per SQL Server

Download del driver PHP

Questo articolo elenca i componenti che devi installare sul tuo sistema per accedere ai dati in SQL Server o database SQL di Azure utilizzando il driver SQLSRV o PDO_SQLSRV.

Per maggiori informazioni sui cicli di vita del supporto e sui requisiti dei driver PHP, consulta la matrice di supporto. I driver SQLSRV e PDO_SQLSRV in ogni release hanno gli stessi requisiti PHP, sistema operativo, architettura, sicurezza dei thread e ODBC.

Come si incastra lo stack dei driver

Un'applicazione PHP non si collega direttamente al server del database. Ogni livello deve essere compatibile con quello accanto:

SQLSRV e PDO_SQLSRV forniscono API PHP diverse sullo stesso driver ODBC. Installale entrambe quando la tua applicazione utilizza entrambe le API. Installare un'estensione non installa automaticamente né abilita l'altra.

Le estensioni possono essere installate indipendentemente. PDO_SQLSRV richiede anche che il PDO si carichi prima di PDO_SQLSRV.

Scegli un insieme compatibile

Prima di scaricare o compilare un driver, completa questi controlli:

1. Identifica ogni runtime PHP che serve l'applicazione. Un task programmato, un worker a riga di comando, un sito IIS, un modulo Apache e un pool PHP-FPM possono utilizzare diversi eseguibili e file di configurazione PHP.

2. Esegui il seguente comando con ogni eseguibile PHP:

   php -i | findstr /I "PHP Version Architecture Thread Safety extension_dir"
   

   Su Linux o macOS, usa:

   php -i | grep -E "PHP Version|Thread Safety|extension_dir"
   file "$(php -r 'echo PHP_BINARY;')"
   

   Il file comando riporta l'architettura dell'eseguibile. Se segnala un eseguibile universale di macOS, seleziona esplicitamente l'architettura prevista, come arch -arm64 php --version o arch -x86_64 php --version. Usa la stessa selezione di architettura quando costruisci, carichi e testi le estensioni.

3. Seleziona una release di driver PHP che supporti la versione minore di PHP, il sistema operativo e il target del database.

4. Seleziona una versione supportata del driver Microsoft ODBC dalla tabella di compatibilità in questo articolo.

5. Abbina il file di estensione o la build PIE all'architettura PHP e alla modalità thread-safety. Non copiare un'estensione da un'altra installazione PHP a meno che tutti questi valori non corrispondano.

6. Configura e verifica separatamente i runtime della CLI e del server web. Un comando riuscito php -m dimostra solo che il runtime CLI ha caricato l'estensione.

PHP

Scarica i binari PHP dal sito PHP. Scegli una versione PHP elencata nel supporto per versioni PHP.

• Abilita il file driver che corrisponde alla tua versione PHP. Per i nomi dei file, vedi Versioni dei driver. Scarica i file da Scarica Microsoft Drivers per PHP per SQL Server. Per le istruzioni di configurazione, vedi Installa i driver Microsoft per PHP per SQL Server.

• Scegli un server web e un metodo di integrazione PHP supportati da PHP e dal tuo framework applicativo. Segui la documentazione di installazione di PHP e le istruzioni di distribuzione del tuo framework per configurare il web server per eseguire PHP. Verifica il caricamento delle estensioni nel runtime del server web separatamente dalla CLI.

Sicurezza dei thread e architettura

Il file di build e di estensione PHP devono concordare su entrambi i valori.

La CLI può utilizzare sia una build PHP thread-safe che non-thread-safe. Seleziona l'estensione in base al valore riportato, non assumendo che ogni build CLI sia non thread-safe.

Driver ODBC

Installa un driver Microsoft ODBC supportato per SQL Server sul computer che esegue PHP. Scarica il driver da Download ODBC Driver for SQL Server.

Se si scarica la versione di Windows del driver in una versione di Windows a 64 bit, il programma di installazione di ODBC a 64 bit installa i driver ODBC sia a 32 bit che a 64 bit. Se si usa una versione a 32 bit di Windows, usare il programma di installazione di ODBC x86. Per le piattaforme non Windows sono disponibili solo le versioni a 64 bit del driver.

La tabella include combinazioni storiche per la pianificazione degli aggiornamenti. Usa l'attuale versione del driver PHP e le versioni ODBC elencate per una nuova installazione. La compatibilità con una versione precedente non ne prolunga il ciclo di supporto. Controlla sia il ciclo di vita del driver PHP che le versioni supportate da PHP.

Una cella vuota non significa che il driver PHP rifiuti necessariamente quella versione ODBC. Le singole funzionalità possono richiedere versioni ODBC più recenti rispetto alla combinazione base.

Se si usa il driver SQLSRV, sqlsrv_client_info restituisce informazioni sulla versione di Microsoft ODBC Driver for SQL Server usata dai driver Microsoft per PHP per SQL Server. Se si usa il driver PDO_SQLSRV, è possibile usare PDO::getAttribute per determinare la versione.

SQL Server

Per le versioni supportate di SQL Server, vedi Versioni supportate del database.

Valuta separatamente il supporto target per 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. I requisiti di installazione sono requisiti lato client e non stabiliscono che ogni metodo di autenticazione, opzione di connessione, funzionalità Transact-SQL (T-SQL) o tipo di dato sia disponibile su ogni target. Usa la matrice di supporto e la documentazione del prodotto target per lo scenario che la tua applicazione utilizza.

Sistemi operativi

Per i sistemi operativi supportati, vedi Sistemi operativi supportati.

Versioni dei driver

Ogni release dei driver Microsoft per PHP per SQL Server fornisce file SQLSRV e driver PDO_SQLSRV in varianti thread-safe e non thread-safe. Su Windows, ogni variante è anche progettata per PHP a 32 e 64 bit. Abbina il file driver alla tua versione PHP, modalità thread-safety e architettura. Per abilitare un file driver dopo averlo scaricato, consulta Caricamento dei driver Microsoft per PHP per SQL Server.

Su Linux e macOS, installa i driver con PIE, il PHP Installer for Extensions, come descritto nelle istruzioni di installazione di Linux e macOS. PIE sostituisce il sistema di pacchetti PHP Extension Community Library (PECL) obsoleto e chiama l'estensione installata sqlsrv.so o pdo_sqlsrv.so. Le seguenti tabelle elencano i nomi dei file dei pacchetti binari precompilati che si scaricano manualmente dalla pagina Microsoft Drivers for PHP for SQL Server releases.

Le seguenti tabelle elencano i file nei pacchetti di rilascio 5.13. Nei nomi dei file, ts e TS significa thread-safe, e nts e NTS significa non-thread-safe.

File del driver di Windows

Il Windows_5.13.xRTW.zip pacchetto contiene questi file.

Usa un file driver non thread-safe con una build PHP non thread-safe, e un file driver thread-safe con una build PHP thread-safe. L'interfaccia a riga di comando (CLI) può utilizzare una delle due versioni. Per confermare quale build hai, esegui php -i e controlla il valore Thread Safety .

File driver Linux e macOS

I pacchetti Linux_5.13.xRTW.tar.gz e Mac_5.13.xRTW.tar.gz contengono questi file. L'archivio Linux contiene binari x64, mentre l'archivio macOS contiene binari Arm64.

I file precompilati devono anche corrispondere alle librerie native del sistema operativo. I binari Linux 5.13.3 richiedono glibc 2.38 e versioni successive e un runtime C++ che fornisce GLIBCXX_3.4.32. I binari di macOS 5.13.3 dichiarano macOS 26 come loro obiettivo minimo di distribuzione. Questi requisiti binari sono separati dal supporto del sistema operativo per le build dal codice sorgente.

Usa PIE quando l'architettura dell'archivio o i requisiti della libreria nativa non corrispondono alla tua installazione PHP. Compilazioni PIE per PHP installato e le librerie native. Non sostituire manualmente le librerie di sistema per caricare un'estensione precompilata.

Copia ogni file di cui hai bisogno nella tua directory di estensioni PHP. Puoi mantenere il nome file del pacchetto e scrivere extension=SQLSRV_8.4_NTS.so, oppure rinominare il file e scrivere la forma breve extension=sqlsrv. Applica la stessa scelta di nome a PDO_SQLSRV. Per trovare la directory di estensione, esegui php -i | grep extension_dir. Segui la procedura Caricare i driver su Linux e macOS per abilitare le estensioni nel file di configurazione corretto e caricare PHP Data Objects (PDO) prima di PDO_SQLSRV.

Rilasci precedenti

Per i file driver inclusi nelle versioni precedenti alla 5.13, scarica il pacchetto di quella versione dalla pagina Microsoft Drivers for PHP for SQL Server releases e elenca i suoi contenuti. Le versioni precedenti alla 5.12 pubblicano un pacchetto separato per ogni sistema operativo e versione PHP invece di un singolo pacchetto per piattaforma.

Verifica l'ambiente selezionato

Esegui questi controlli dopo aver installato le estensioni PHP e il driver ODBC, ma prima di configurare un server web:

php --version
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv

Gli ultimi due comandi devono mostrare sezioni separate di informazioni sul modulo. Se uno dei comandi segnala che l'estensione non è presente, completa la procedura di installazione e caricamento della piattaforma prima di testare una connessione al database.

Crea verify-php-drivers.php per controllare entrambe le API PHP senza richiedere credenziali:

<?php
$failures = [];

if (!extension_loaded('sqlsrv') || !function_exists('sqlsrv_connect')) {
    $failures[] = 'SQLSRV is not loaded.';
}

if (!extension_loaded('pdo_sqlsrv') || !in_array('sqlsrv', PDO::getAvailableDrivers(), true)) {
    $failures[] = 'PDO_SQLSRV is not loaded.';
}

echo $failures === []
    ? "SQLSRV and PDO_SQLSRV are loaded." . PHP_EOL
    : implode(PHP_EOL, $failures) . PHP_EOL;

exit($failures === [] ? 0 : 1);

Eseguilo con l'eseguibile PHP che serve l'applicazione:

php verify-php-drivers.php

Output previsto:

SQLSRV and PDO_SQLSRV are loaded.

Questo controllo verifica il caricamento delle estensioni. Non verifica la connettività ODBC, l'autenticazione, la fiducia dei certificati, l'accesso alla rete o i permessi del database.

Cancella verify-php-drivers.php dopo aver registrato il risultato.

Diagnosticare i requisiti non soddisfatti

Contenuti correlati

• Introduzione ai driver Microsoft per PHP per SQL Server
• Guida alla programmazione per i driver Microsoft per PHP per SQL Server
• Riferimento all'API del driver SQLSRV
• Guida di riferimento del driver PDO_SQLSRV