Installa i driver Microsoft per PHP su Linux e macOS

Queste istruzioni installano PHP, il driver ODBC Microsoft per SQL Server e le estensioni SQLSRV e PDO_SQLSRV. Ogni scheda utilizza il pacchetto PHP fornito dal repository da cui quella scheda installa, quindi la versione nei comandi varia da una scheda all'altra. Sostituiscila con un'altra versione PHP elencata nella matrice di supporto se quel repository ne offre una diversa.

I driver SQLSRV e PDO_SQLSRV utilizzano la stessa dipendenza ODBC e possono essere installati indipendentemente. Installa entrambe le estensioni se la tua applicazione usa entrambi i driver.

Al termine della procedura, la CLI e il runtime del server web selezionato dovrebbero caricare entrambe le estensioni, entrambe le API PHP dovrebbero essere disponibili e il campione di ciascuna API dovrebbe restituire la versione del server database.

Prima di iniziare

  1. Scegli una versione PHP supportata dalla versione attuale del driver e disponibile per la release del tuo sistema operativo.

  2. Decidi quali runtime PHP ti servono:

    • CLI per script, attività pianificate o worker.
    • Modulo Apache per PHP ospitato su Apache.
    • PHP-FPM per nginx o una configurazione Apache FastCGI.

  3. Conferma l'architettura del sistema operativo. Gli archivi Linux rilasciati contengono binari x64 e quelli di macOS rilasciati contengono binari Arm64. PIE compila per l'installazione di PHP sul computer ed è il percorso principale di installazione in questo articolo.

  4. Installa il driver Microsoft ODBC e il pacchetto di sviluppo unixODBC. Il pacchetto Microsoft gestisce la comunicazione con il database. Il pacchetto unixODBC fornisce le intestazioni necessarie per costruire SQLSRV e PDO_SQLSRV.

  5. Pianifica di riavviare ogni server web, pool PHP-FPM e processo worker a lunga esecuzione dopo aver installato o modificato un'estensione.

Il gestore di pacchetti della piattaforma installa PHP e prerequisiti nativi. PIE compila e installa le estensioni PHP. La configurazione PHP determina se ogni runtime li carica. Il driver ODBC gestisce la comunicazione e la crittografia del database dopo che l'estensione è stata caricata.

Installa i driver con PIE

PIE, il PHP Installer for Extensions, è l'installer di estensione supportato per le attuali release dei driver. Sostituisce il flusso di lavoro obsoleto PHP Extension Community Library (PECL).

Completa i prerequisiti della piattaforma nelle sezioni seguenti prima di installare i driver. Poi installa PIE e ogni driver separatamente:

Installa PIE

PIE funziona con PHP 8.1 e versioni successive. Può installare un'estensione in un'altra installazione PHP quando si selezionano gli strumenti di sviluppo di quell'installazione.

Installa curl e la CLI di GitHub prima di continuare. Le sezioni della piattaforma includono curl dove un'installazione minima potrebbe non fornirla.

Scarica l'archivio PIE PHP (PHAR) e verificalo con l'interfaccia a riga di comando (CLI) di GitHub prima di installarlo o eseguirlo:

pie_tmp=$(mktemp -d)
curl -fL --output "$pie_tmp/pie.phar" https://github.com/php/pie/releases/latest/download/pie.phar
gh attestation verify --owner php "$pie_tmp/pie.phar"

Continua solo se la verifica ha successo:

sudo install -m 755 "$pie_tmp/pie.phar" /usr/local/bin/pie
rm "$pie_tmp/pie.phar"
rmdir "$pie_tmp"
unset pie_tmp

La directory temporanea è accessibile solo dal tuo account. Se il download o la verifica falliscono, non installare né far girare il PHAR. Rimuovi il file e la directory temporanei prima di riprovare.

Conferma che il PHAR installato funzioni con l'eseguibile PHP che intendi usare:

php /usr/local/bin/pie --version

Installa i driver SQLSRV e PDO_SQLSRV

Su Linux e macOS, PIE verifica il compilatore e gli strumenti di sviluppo PHP di cui ha bisogno. Installa il pacchetto di sviluppo ODBC della piattaforma e un compilatore C++ prima di eseguire PIE. Esegui PIE da un terminale interattivo. Può richiedere la tua sudo password quando ha bisogno del permesso per installare file nelle directory di sistema.

PIE si applica all'installazione PHP utilizzata per invocarlo. Per un'installazione versionata, aggiungi --with-php-config a ogni comando di installazione per selezionare gli strumenti di sviluppo relativi alla versione selezionata. Ad esempio, usa pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv quando lo strumento previsto è /usr/bin/php-config8.4. Applica la stessa opzione a microsoft/pdo_sqlsrv. Alpine utilizza nomi eseguibili versionati; segui i comandi Alpine invece dei comandi non versionati in questa sezione.

Esegui un comando per ogni estensione. Questi comandi utilizzano l'installazione PHP predefinita di PIE:

pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

PIE tenta di abilitare ogni estensione tramite gli strumenti di configurazione PHP della piattaforma o tramite una extension= voce, e avverte se non può. PHP utilizza un'interfaccia di programmazione delle applicazioni del server (SAPI) per ogni ambiente di esecuzione. Su Debian, Ubuntu e SUSE, le configurazioni a riga di comando, Apache e PHP FastCGI Process Manager (PHP-FPM) possono differire. Un'installazione da riga di comando riuscita non conferma che un server web carichi i driver.

Controlla php --ini per la riga di comando. Prima di creare una pagina temporanea phpinfo() per il server web, limita l'accesso alla pagina diagnostica. Controlla il file di configurazione caricato e i file scansionati .ini per ogni runtime. Se mancano le voci, segui Carica i driver su Linux e macOS per aggiungerli nell'ordine di caricamento corretto. Riavvia il server web o PHP-FPM dopo modifiche alla configurazione. Red Hat comunemente condivide php.ini tra i SAPI, ma verifica la configurazione attiva prima di affidarsi a una sola esecuzione PIE.

Installa sulla tua piattaforma

Seleziona il sistema operativo e la configurazione del server web. Completa i passaggi di installazione in quella scheda, poi segui Testare l'installazione.

Installa su Ubuntu

Annotazioni

I seguenti comandi utilizzano il repository PHP packages.sury.org così puoi selezionare una versione PHP supportata. Usa le istruzioni ufficiali di Microsoft per installare il driver ODBC per la tua versione Ubuntu.

Passaggio 1: Installare PHP (Ubuntu)

sudo apt-get update
sudo apt-get install ca-certificates apt-transport-https curl gnupg2 lsb-release -y
sudo install -d -m 755 /etc/apt/keyrings
sudo curl -fsSL https://packages.sury.org/php/apt.gpg -o /etc/apt/keyrings/php.gpg
sudo chmod 644 /etc/apt/keyrings/php.gpg
echo "deb [signed-by=/etc/apt/keyrings/php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
sudo apt-get update
sudo apt-get install php8.4 php8.4-dev php8.4-xml -y

Passaggio 2. Installare i prerequisiti (Ubuntu)

Segui Installare il driver Microsoft ODBC per SQL Server in Linux, poi installa gli header di sviluppo.

sudo apt-get install unixodbc-dev g++ make git -y

Passaggio 3. Installa i driver PHP per Microsoft SQL Server con PIE (Ubuntu)

Segui Installa i driver con PIE, aggiungendo --with-php-config=/usr/bin/php-config8.4 a entrambi i comandi di installazione. Controlla i file di configurazione della riga di comando con php8.4 --ini.

/usr/local/bin/pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv
/usr/local/bin/pie install --with-php-config=/usr/bin/php-config8.4 microsoft/pdo_sqlsrv

Passaggio 4. Installare Apache e configurare il caricamento dei driver (Ubuntu)

sudo apt-get install apache2 libapache2-mod-php8.4 -y
sudo a2enmod php8.4

Passaggio 5. Riavviare Apache e testare lo script di esempio (Ubuntu)

sudo systemctl restart apache2

Per testare l'installazione, vedere Test dell'installazione alla fine di questo documento.

Installazione PECL legacy

PECL è deprecato per le attuali versioni dei driver. Usa PIE per nuove installazioni e aggiornamenti. Se una distribuzione esistente è fissata su PECL, mantenere le versioni dei pacchetti allineate con il runtime PHP e pianificare un passaggio a PIE.

Verifica la tua installazione

Verifica il runtime della riga di comando. Su Alpine, sostituisci php con php84. Per un'installazione PHP versionata su un'altra distribuzione, si utilizza il corrispondente eseguibile.

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | grep -E "sqlsrv|pdo_sqlsrv"

Entrambi --ri i comandi dovrebbero stampare informazioni del modulo che includano ExtensionVer. L'elenco dei moduli dovrebbe contenere righe separate sqlsrv e pdo_sqlsrv.

Prima di testare una connessione, verificare entrambe le interfacce API PHP con verify-php-drivers.php:

<?php
$checks = [
    'SQLSRV' => extension_loaded('sqlsrv') && function_exists('sqlsrv_connect'),
    'PDO_SQLSRV' => extension_loaded('pdo_sqlsrv')
        && in_array('sqlsrv', PDO::getAvailableDrivers(), true),
];

$failed = false;
foreach ($checks as $name => $loaded) {
    echo "$name: " . ($loaded ? 'loaded' : 'missing') . PHP_EOL;
    $failed = $failed || !$loaded;
}

exit($failed ? 1 : 0);

Output previsto:

SQLSRV: loaded
PDO_SQLSRV: loaded

Per PHP-FPM o un server web, limita l'accesso alla pagina diagnostica prima di creare una pagina temporanea phpinfo() . Conferma il file di configurazione caricato, la extension_dir e entrambe le sezioni del driver. Riavvia PHP-FPM o il server web dopo aver cambiato configurazione o sostituito un'estensione. Rimuovi la pagina dopo la verifica.

Per testare una connessione reale, crea un file chiamato testsql.php nel document root del tuo sistema. Questo percorso si trova su /var/www/html in Ubuntu, Debian e Red Hat, su /srv/www/htdocs in SUSE, su /var/www/localhost/htdocs in Alpine o su $(brew --prefix)/var/www in macOS. Imposta le variabili di ambiente SQL_SERVER_NAME, SQL_DATABASE, SQL_UID e SQL_PWD per il processo PHP prima di eseguire lo script. Non hardcodare le credenziali in un file sotto la radice del documento.

Per un test da riga di comando, usa i prompt interattivi per impostare le variabili di ambiente senza inserire una password nella cronologia della shell.

Per un test di modulo Apache, tieni le credenziali fuori dal file di configurazione generalmente leggibile del sito:

  1. Crea un file privato al di fuori della DocumentRoot. Usa un nome di file inutilizzato nella directory di configurazione di Apache. Su Linux:

    sudo install -o root -g root -m 600 /dev/null /etc/apache2/php-sql-driver-test.conf

    Su Red Hat, sostituisci /etc/apache2 con /etc/httpd. Su macOS, crea il file con l'account che avvia Apache di Homebrew:

    install -m 600 /dev/null "$(brew --prefix)/etc/httpd/php-sql-driver-test.conf"

    Solo il proprietario del file e root possono leggere queste impostazioni. L'account che avvia Apache deve essere in grado di leggere il file.

  2. Modifica il file privato in un editor di testo e aggiungi queste voci:

    SetEnv SQL_SERVER_NAME "tcp:<server>,1433"
SetEnv SQL_DATABASE "<database>"
SetEnv SQL_UID "<user_id>"
SetEnv SQL_PWD "<password>"

    All'interno degli argomenti racchiusi tra doppi apici, scrivi \\ per ogni backslash letterale e \" per ogni doppia virgoletta letterale. Conserva gli spazi iniziali e finali all'interno delle virgolette. Apache sostituisce anche i riferimenti ${NAME}. Se un valore contiene quella sequenza o una interruzione di linea, si utilizza invece il test in linea di comando. Per ulteriori informazioni, vedi virgolette ed escaping nella configurazione di Apache.

  3. All'interno dell'host virtuale del sito, aggiungi un Files blocco che includa il file privato solo per testsql.php. Se non è configurato un host virtuale, posizionare il blocco nella configurazione principale del server. Sostituisci il segnaposto con il percorso assoluto del file privato:

    <Files "testsql.php">
    Include "<absolute-path-to-private-file>"
</Files>

  4. Riavvia Apache. Dopo il test, rimuovi il Files blocco che hai aggiunto, elimina il file privato e riavvia Apache. Mantieni impostazioni del sito non correlate.

PHP-FPM cancella di default le variabili dell'ambiente ereditate e nginx non passa il suo ambiente a PHP-FPM. Usa la seguente procedura Ubuntu o Red Hat solo con un servizio e un pool di test PHP-FPM isolato. Non aggiungere credenziali di test a un servizio o pool che esegue altre applicazioni: ogni script in quel pool può leggerle. Se usi l'hosting condiviso, usa invece il test a riga di comando.

  1. Crea un file di proprietà della root al di fuori della radice del documento, come /etc/php-sql-driver-test.env, e limita l'accesso:

    sudo touch /etc/php-sql-driver-test.env
sudo chmod 600 /etc/php-sql-driver-test.env

    Aggiungi le impostazioni di connessione al file:

    SQL_SERVER_NAME="tcp:<server>,1433"
SQL_DATABASE="<database>"
SQL_UID="<user_id>"
SQL_PWD="<password>"

    Mantieni ogni impostazione su una sola riga. All'interno delle virgolette doppie, scrivi \\ per ogni barra rovesciata letterale e \" per ogni doppia virgoletta letterale. I segni del dollaro e i backtick non vengono valutati come espressioni della shell. Modifica il file direttamente invece di eseguirlo o farne il source in una shell. Per maggiori informazioni, vedi la sintassi systemd EnvironmentFile.

  2. Esegui sudo systemctl edit php8.4-fpm su Ubuntu o sudo systemctl edit php-fpm su Red Hat. Aggiungi questo override di systemd:

    [Service]
EnvironmentFile=/etc/php-sql-driver-test.env

  3. Aggiungi queste voci alla configurazione del pool di PHP-FPM attivo. I percorsi più comuni sono /etc/php/8.4/fpm/pool.d/www.conf su Ubuntu e /etc/php-fpm.d/www.conf su Red Hat:

    env[SQL_SERVER_NAME] = $SQL_SERVER_NAME
env[SQL_DATABASE] = $SQL_DATABASE
env[SQL_UID] = $SQL_UID
env[SQL_PWD] = $SQL_PWD

  4. Ricarica systemd e riavvia il servizio PHP-FPM applicabile:

    sudo systemctl daemon-reload
sudo systemctl restart php8.4-fpm

    Su Red Hat, sostituisci php8.4-fpm con php-fpm.

Dopo i test, rimuovi il file temporaneo dell'ambiente, la EnvironmentFile= voce che hai aggiunto, le voci del pool di test e testsql.php. Elimina il file di override del servizio solo se l'hai creato per questo test e non contiene altre impostazioni. Conserva tutti gli override e le impostazioni del pool preesistenti. Ricarica il systemd e riavvia PHP-FPM dopo aver rimosso la configurazione di test.

Esempio di SQLSRV

Mantieni invariati i valori dell'ambiente. Ogni esempio verifica che le impostazioni non siano mancanti o vuote prima di connettersi. Ogni esempio poi raddoppia le parentesi di chiusura e aggiunge le parentesi esterne prima di passare il nome del database, il nome utente e la password al driver. Questa codifica preserva le parentesi graffe letterali e impedisce ai punti e virgola di separare le opzioni di connessione.

<?php
$serverName = getenv('SQL_SERVER_NAME');
$databaseName = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $databaseName === false || $databaseName === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    handle_failure("Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD.");
}

$databaseName = '{' . str_replace('}', '}}', $databaseName) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';
$connectionOptions = array(
    "Database" => $databaseName,
    "UID" => $uid,
    "PWD" => $pwd,
    "Encrypt" => 1,
    "TrustServerCertificate" => 0
);

function handle_failure($message) {
    error_log($message);
    http_response_code(500);
    echo "<h1>Failure</h1>";
    echo "An error occurred. Check the server error log for details.";
    exit(1);
}

function format_errors($errors) {
    $lines = [];
    foreach ($errors as $error) {
        $lines[] = "SQLSTATE: {$error['SQLSTATE']}, code: {$error['code']}, message: {$error['message']}";
    }
    return implode(PHP_EOL, $lines);
}

$conn = sqlsrv_connect($serverName, $connectionOptions);
if ($conn === false) {
    handle_failure(format_errors(sqlsrv_errors()));
}

$tsql = "SELECT @@Version AS SQL_VERSION";

$stmt = sqlsrv_query($conn, $tsql);
if ($stmt === false) {
    handle_failure(format_errors(sqlsrv_errors()));
}

$row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
if ($row === null || $row === false) {
    handle_failure("Query returned no rows.");
}

echo "<h1>Success</h1>";
echo htmlspecialchars($row['SQL_VERSION']);

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);
?>

Esempio di PDO_SQLSRV

<?php
$serverName = getenv('SQL_SERVER_NAME');
$databaseName = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $databaseName === false || $databaseName === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    handle_failure(new RuntimeException("Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD."));
}

$databaseName = '{' . str_replace('}', '}}', $databaseName) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';

function handle_failure($exception) {
    error_log($exception->getMessage());
    http_response_code(500);
    echo "<h1>Failure</h1>";
    echo "An error occurred. Check the server error log for details.";
    exit(1);
}

try {
    $conn = new PDO(
        "sqlsrv:server=$serverName;Database=$databaseName;Encrypt=1;TrustServerCertificate=0",
        $uid,
        $pwd
    );
    $conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    $tsql = "SELECT @@Version AS SQL_VERSION";

    $stmt = $conn->query($tsql);
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException("Query returned no rows.");
    }

    echo "<h1>Success</h1>";
    echo htmlspecialchars($row['SQL_VERSION']);
} catch (Throwable $exception) {
    handle_failure($exception);
}

unset($stmt);
unset($conn);
?>

Puntare il browser a http://localhost/testsql.php (http://localhost:8080/testsql.php in macOS). Una connessione riuscita mostra la stringa versione del server di database. Entrambi gli esempi scrivono i dettagli degli errori nel registro errore PHP. Se la pagina mostra un errore, controlla quel registro.

Per confrontare il comportamento della riga di comando e del server web, imposta le stesse variabili di ambiente per il terminale ed esegui:

php testsql.php

Se l'esecuzione dalla riga di comando riesce ma non appare nulla nel browser, controlla i file di log Apache. Per ulteriori aiuti, consulta le risorse di supporto per il driver SQL PHP.

Valuta separatamente i programmi di connessione 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. Il metodo di autenticazione selezionato, le opzioni di connessione e la query devono essere supportati dal target. L'installazione avviene lato client. Un controllo di estensione riuscito non dimostra che un target accetta le credenziali, si fida del client o supporta tutte le funzionalità del database.

Risoluzione dei problemi di installazione

Sintomo Layer proprietario Azione correttiva
PIE non riesce a trovare phpize, php-config, né header Pacchetti di sviluppo PHP Installa il pacchetto di sviluppo per la versione PHP di destinazione e passa l'opzione corrispondente --with-php-config
La compilazione fallisce perché manca un compilatore C++ Strumenti di compilazione del sistema operativo Installa il pacchetto compilatore C++ della piattaforma, come g++ o gcc-c++
La compilation non riesce a trovare sql.h Percorsi del pacchetto di sviluppo ODBC o del compilatore Installa unixodbc-dev oppure unixODBC-devel; su Apple silicon, imposta i flag di include e di libreria di Homebrew
php --ri dice che l'estensione non è presente Configurazione PHP Ispeziona l'elemento caricato php.ini e la directory di scansione, aggiungi la voce corretta e riavvia il processo
Report PDO could not find driver Caricamento di PDO_SQLSRV o ordine di caricamento di PDO Verificare che PDO venga caricato per primo e che PDO_SQLSRV utilizzi un file di configurazione scansionato successivamente
CLI funziona ma Apache, nginx o PHP-FPM falliscono Configurazione specifica per SAPI Confronta l'output CLI con phpinfo(), configura il web SAPI e riavvialo
Il browser restituisce HTTP 502 tramite nginx instradamento da nginx a PHP-FPM Controlla il fastcgi_pass socket rispetto alla versione PHP-FPM installata e conferma che il servizio è in funzione
L'esempio del browser segnala valori di ambiente mancanti Server web o ambiente PHP-FPM Configura le variabili per il runtime web selezionato, poi riavvialo
Le estensioni si caricano ma una connessione fallisce ODBC, rete, certificato, autenticazione o prodotto SQL Leggi l'errore SQLSTATE e nativo dal log del server; non ricostruire l'estensione a meno che l'errore non identifichi il caricamento o la compatibilità binaria

Rimuovere la configurazione temporanea di test

Dopo la verifica:

  1. Elimina testsql.php, verify-php-drivers.php, e qualsiasi pagina temporanea phpinfo() dalla radice del documento.

  2. Rimuovere credenziali temporanee e voci di inoltro dell'ambiente.

  3. Ricarica il service manager quando cambi un override di systemd, poi riavvia PHP-FPM o il server web.

  4. Conserva le voci di estensione e i pacchetti installati che l'applicazione richiede.

Contenuti correlati

  • Ultimo aggiornamento: