Risoluzione dei driver Microsoft per PHP per SQL Server

Download del driver PHP

Diagnostica e risolvi i problemi comuni quando usi i Microsoft Drivers for PHP for SQL Server per collegarti a SQL Server, database SQL di Azure, Istanza gestita di SQL di Azure e database SQL in Microsoft Fabric.

Per modelli generali di gestione errori e avvisi, vedi Gestione errori e avvisi. Per la cattura diagnostica lato guidatore, vedi Attività di registrazione.

Problemi di installazione

Estensione non caricata

Sintomi:

phpinfo()Non elenca una sqlsrv sezione A.pdo_sqlsrv
PDOException: could not find driver quando si costruisce una PDO con la sqlsrv: DSN.
Fatal error: Uncaught Error: Call to undefined function sqlsrv_connect().

Possibili cause e soluzioni:

L'estensione non è stata attivata in php.ini. Verifica che sia extension=sqlsrv che extension=pdo_sqlsrv non siano commentati. Su Windows, usa il nome completo del file (extension=php_sqlsrv_84_ts_x64.dll). Per dettagli, vedi Caricamento dei driver.
Costruzione sbagliata della sicurezza della filettatura. Il binario driver deve corrispondere alla sicurezza dei thread della tua build PHP (ts per thread-safe, nts per non-thread-safe). Eseguire php -i | grep "Thread Safety" per verificare. Scarica il binario corrispondente dalla pagina di download.
Driver Microsoft ODBC mancante. I driver PHP avvolgono il driver Microsoft ODBC per SQL Server. Su Linux e macOS, installa msodbcsql18 (o msodbcsql17) con il tuo gestore di pacchetti prima di caricare le estensioni. Su Windows, installa il driver ODBC dalla pagina di download.

Verifica un'installazione riuscita:

php -m | grep -i sqlsrv

Dovresti vedere entrambi pdo_sqlsrv e sqlsrv nell'output.

L'installazione di PECL fallisce su Linux o macOS

Sintomi:

error: ‘SQL_HANDLE_DBC’ undeclared (first use in this function)
fatal error: 'sql.h' file not found

Correzione:

Installa le header di sviluppo ODBC prima di eseguire pecl install:

Ubuntu e Debian: sudo apt-get install unixodbc-dev
Red Hat, Fedora e CentOS:sudo dnf install unixODBC-devel
Alpino: apk add unixodbc-dev
macOS: brew install unixodbc

Poi riprova:

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv

Se pecl continua a guastarsi dopo l'installazione dei collettori, la catena degli utensili di costruzione potrebbe essere incompleta. Installa phpize, re2c, e un compilatore C++ (build-essential su Debian e Ubuntu, gcc-c++ make su Red Hat e Fedora, su build-base Alpine).

Per il percorso completo di installazione, consulta il tutorial di installazione per Linux e macOS.

Molteplici versioni PHP installate

Sintomi:

phpinfo() nel tuo server web mostra una versione PHP, ma php -v nella riga di comando ne mostra un'altra, e il driver appare caricato solo in una di esse.

Correzione:

Ogni versione PHP ha la propria php.ini directory.ext Trova il file php --ini di configurazione corretto dall'interno dell'ambiente che manca il driver e aggiungi le extension= linee lì. Riavvia il server web (Apache, Nginx + PHP-FPM o IIS) dopo qualsiasi modifica php.ini.

Problemi di connessione

Impossibile connettersi al server

Sintomi:

SQLSTATE[08001]: [Microsoft][ODBC Driver 18 for SQL Server]TCP Provider: A connection attempt failed
SQLSTATE[HYT00]: [Microsoft][ODBC Driver 18 for SQL Server]Login timeout expired

Possibili cause e soluzioni:

Il server non è raggiungibile. Controlla che il nome del server e la porta siano corretti. Dall'host PHP, testare la connettività TCP grezza.

# Linux and macOS
nc -vz <server>.database.windows.net 1433

# Windows PowerShell
Test-NetConnection -ComputerName <server>.database.windows.net -Port 1433

Il firewall blocca l'uscita di 1433. I firewall aziendali e i cloud NSG spesso bloccano la porta in uscita 1433. Aggiungi un'eccezione, oppure consenti agli intervalli IP di database SQL di Azure per la tua regione.
Azure SQL server firewall. Aggiungi l'IP pubblico del tuo client alle regole firewall a livello di server nel portale Azure.
Istanza nominata. Per un'istanza nominata, verifica che il servizio SQL Server Browser sia in esecuzione sul server e che UDP 1434 sia aperto. Oppure, collegati per porta invece che per nome dell'istanza.

Sintomi:

SQLSTATE[28000]: [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Login failed for user '<user_id>'.

Possibili cause e soluzioni:

Modalità autenticazione SQL disabilitata. Le istanze di SQL Server locale sono predefinite solo con l'autenticazione Windows. Abilita l'autenticazione in modalità mista in SQL Server Management Studio sotto proprietà>Server Sicurezza, e poi riavvia il servizio SQL Server.
Azure SQL credentials format. Azure SQL richiede il nome utente completamente qualificato (user@servername) quando si connette da strumenti che non lo aggiungono automaticamente.
Utente non mappato al database. Verifica che l'accesso abbia una mappatura utente nel database target e che l'utente abbia i permessi richiesti.
Preferisci Microsoft Entra ID. Per Azure SQL, Istanza gestita di SQL di Azure e database SQL in Fabric, si utilizza l'autenticazione Microsoft Entra (Authentication=ActiveDirectoryMsi, Authentication=ActiveDirectoryServicePrincipal, o un token di accesso) invece degli accessi SQL. Vedere Connettersi con l'autenticazione di Microsoft Entra.

Valore non valido specificato per l'attributo stringa di connessione 'Authentication'

Sintomi:

SQLSTATE[08001]: [Microsoft][ODBC Driver 17 for SQL Server]Invalid value specified for connection string attribute 'Authentication'

Causa:

Il driver ODBC segnala l'errore, ma il vero problema è quale driver PDO_SQLSRV vincolato. Se il DSN non include una Driver= parola chiave e l'host ha sia ODBC 17 che ODBC 18 installati, PDO_SQLSRV può associarsi alla versione precedente. Le versioni ODBC 17.x più vecchie non conoscono valori più Authentication recenti come ActiveDirectoryServicePrincipal o ActiveDirectoryDefault, e richiedono persino ActiveDirectoryMsi ODBC 17.3.1.1 o una versione successiva.

Correzione:

Fissa il driver nel DSN:

<?php
$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$db;" .
       "Encrypt=true;Authentication=ActiveDirectoryMsi";
$conn = new PDO($dsn, null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);

La forma tra parentesi ({ODBC Driver 18 for SQL Server}) esce dagli spazi nel nome del driver. Il messaggio di errore stesso nomina sempre il driver che lo ha segnalato, quindi il prefisso [Microsoft][ODBC Driver 17 for SQL Server] nell'errore è il modo più veloce per confermare il driver sbagliato assegnato.

La parola chiave non valida 'UID' è stata specificata nella stringa DSN

Sintomi:

SQLSTATE[IMSSP]: An invalid keyword 'UID' was specified in the DSN string.

Causa:

PDO_SQLSRV impone una lista di permessi di parole chiave DSN e non accetta UID nulla PWD nella DSN. PDO riserva il secondo e il terzo argomento del costruttore per questi argomenti e PDO_SQLSRV li traduce internamente in ODBC UID/PWD .

Correzione:

Sposta il nome utente (e la password, per l'autenticazione SQL) nel costruttore PDO:

<?php
// SQL authentication.
$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$db;Encrypt=true";
$conn = new PDO($dsn, $user, $password);

// User-assigned managed identity. Pass the identity's client ID as $username.
$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$db;" .
       "Encrypt=true;Authentication=ActiveDirectoryMsi";
$conn = new PDO($dsn, $clientId, null);

Il driver procedurale SQLSRV, al contrario, accetta UID e PWD nell'array delle opzioni di connessione passa a sqlsrv_connect().

PDO_SQLSRV ignora silenziosamente AccessToken nell'array delle opzioni

Sintomo:

Hai un token di accesso Microsoft Entra (ad esempio, da az account get-access-token --resource https://database.windows.net/, , o ClientSecretCredential), e lo passi a PDO_SQLSRV come ['AccessToken' => $token] nel quarto argomento del ManagedIdentityCredentialcostruttore. Il tentativo di connessione fallisce con un errore confuso come Windows logins are not supported in this version of SQL Server o Login failed for user '', come se non fossero state fornite credenziali.

Causa:

Il quarto argomento costruttore di PDO è riservato alle costanti specifiche degli attributi del driver (chiavi intere come PDO::ATTR_ERRMODE). PDO lascia silenziosamente cadere voci con stringa come AccessToken, così PDO_SQLSRV non vede mai il token. La connessione poi torna all'autenticazione integrata di Windows, che il server rifiuta.

Correzione:

Passa AccessToken alla stringa DSN. Riserva l'array delle opzioni per PDO::ATTR_* le costanti.

<?php
$server = '<server>.database.windows.net';
$token  = getenv('SQL_ACCESS_TOKEN');   // raw JWT, no "Bearer " prefix

$dsn = "sqlsrv:Server=$server;Database=<database>;Encrypt=true;AccessToken=$token";
$conn = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Per ulteriori esempi di autenticazione Microsoft Entra, incluso il modulo DSN per PDO_SQLSRV, vedi Collega usando Microsoft Entra autenticazione.

Per il procedurale SQLSRV, AccessToken appartiene all'array connection-info passato a sqlsrv_connect(), che avvolge il JWT grezzo in SQL_COPT_SS_ACCESS_TOKEN per u:

<?php
$server = '<server>.database.windows.net';
$token  = getenv('SQL_ACCESS_TOKEN');   // raw JWT, no "Bearer " prefix

$connectionInfo = [
    'Database'               => '<database>',
    'AccessToken'            => $token,
    'Encrypt'                => true,
    'TrustServerCertificate' => false,
    'Driver'                 => '{ODBC Driver 18 for SQL Server}',
];

$conn = sqlsrv_connect($server, $connectionInfo);
if ($conn === false) {
    print_r(sqlsrv_errors());
    exit(1);
}

Errori del certificato TLS

Sintomi:

SQLSTATE[08001]: SSL Provider: The certificate chain was issued by an authority that is not trusted
SQLSTATE[08001]: SSL Provider: The target principal name is incorrect

Soluzioni:

Preferisci un certificato affidabile. Usalo TrustServerCertificate=true solo per lo sviluppo locale su un server che controlli.

Per lo sviluppo rispetto a un certificato autofirmato:

<?php
$server   = 'localhost';
$database = '<database>';
$user     = '<user_id>';
$password = '<password>';

$dsn = "sqlsrv:Server=$server;Database=$database;Encrypt=true;TrustServerCertificate=true";
$conn = new PDO($dsn, $user, $password, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Caution

TrustServerCertificate=true Disabilita la validazione del certificato server. Non portare mai quell'ambientazione in produzione, in scena o ambienti condivisi.

Per un nome host di produzione che non corrisponde al Nome Comune del certificato (ad esempio, quando si collega tramite un listener), specifica l'oggetto effettivo del certificato:

<?php
$dsn = "sqlsrv:Server=<listener>;Database=<database>;Encrypt=true;HostNameInCertificate=*.database.windows.net;Authentication=ActiveDirectoryMsi";
$conn = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Timeout della connessione

Sintomi:

SQLSTATE[HYT00]: Login timeout expired

Possibili cause e soluzioni:

LoginTimeout Non impostato o impostato troppo basso per il failover a freddo. Imposta un messaggio esplicito LoginTimeout (in pochi secondi) nel DSN quando ti connetti ad Azure SQL. I failover dei gruppi di failover e i database a freddo possono richiedere più tempo di quanto consenta un breve timeout lato client. Vedi Opzioni di connessione per il riferimento delle opzioni.
Riconnessione inattiva budget troncato. Se imposti ConnectRetryCount e ConnectRetryInterval, assicurati LoginTimeout >= ConnectRetryCount * ConnectRetryInterval. Altrimenti il timeout del login interrompe il ciclo di riconnessione in anticipo. Vedi resilienza alla connessione idle.

<?php
$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=<server>.database.windows.net;Database=<database>;" .
       "Encrypt=true;LoginTimeout=90;ConnectRetryCount=5;ConnectRetryInterval=15;" .
       "Authentication=ActiveDirectoryMsi";
$conn = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Problemi di esecuzione delle query

Guasti silenziosi con PDO

Sintomo:

Una PDO::exec() chiamata o PDOStatement::execute() o risposta false ritorna ma non fa eccezione.

Correzione:

Con PHP 8.0 e versioni successive, la modalità di errore PDO predefinita è PDO::ERRMODE_EXCEPTION. Se una chiamata restituisce false senza essere lanciata, l'applicazione cambia la modalità in PDO::ERRMODE_SILENT o PDO::ERRMODE_WARNING. Riimpostalo in modalità eccezione così che i guasti generino eccezioni:

<?php
$conn = new PDO($dsn, $user, $password, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

Se non puoi cambiare la modalità globalmente, controlla $conn->errorInfo() (o $stmt->errorInfo()) dopo ogni chiamata. L'array contiene [SQLSTATE, driver code, driver message].

Nome di oggetto non valido

Sintomi:

SQLSTATE[42S02]: [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Invalid object name 'Products'.

Possibili cause e soluzioni:

Contesto sbagliato del database. Verifica con una domanda veloce:

<?php
$stmt = $conn->query("SELECT DB_NAME()");
echo $stmt->fetchColumn();

Manca il qualificatore dello schema. Usa nomi completamente qualificati per evitare di dipendere dallo schema predefinito del chiamante:
```
SELECT * FROM dbo.Products;
```
Distinzione maiuscole/minuscole. I database creati con una collazione a secca e caso trattano products e Products come oggetti diversi. Corrispondi esattamente al caso nella definizione della tabella.

Numero sbagliato di parametri

Sintomi:

SQLSTATE[HY093]: Invalid parameter number
SQLSTATE[07002]: COUNT field incorrect or syntax error

Correzione:

Per PDO_SQLSRV, il numero di ? segnaposto deve corrispondere al numero di valori che passi a execute(), e ciascuno ? lega un singolo scalar (non un array). Per i parametri nominati, ogni :name elemento in SQL deve apparire nell'array e viceversa.

<?php
$stmt = $conn->prepare(
    "SELECT * FROM dbo.Products WHERE CategoryID = ? AND ListPrice > ?"
);
$stmt->execute([1, 50.0]);
foreach ($stmt as $row) {
    // ...
}

Per SQLSRV, passa l'array di parametri a sqlsrv_query() o sqlsrv_prepare():

<?php
$stmt = sqlsrv_query(
    $conn,
    "SELECT * FROM dbo.Products WHERE CategoryID = ? AND ListPrice > ?",
    [1, 50.0]
);
if ($stmt === false) {
    die(print_r(sqlsrv_errors(), true));
}

Per un'introduzione più ampia al lego dei parametri, vedi Eseguire query parametrizzate.

PDO emulato prepara errori di maschera

Sintomi:

Un'istruzione viene eseguita con successo su una connessione ma genera un errore di sintassi su un'altra connessione che utilizza lo stesso testo di interrogazione.

Causa:

PDO_SQLSRV supporta sia dichiarazioni preparate emulate che native. I prepara emulati (PDO::ATTR_EMULATE_PREPARES = true) interpolano i parametri lato client. I preparati nativi (false) inviano la query e i parametri separatamente al server. Il comportamento differisce per TOP (?), parametri a valori di tabella e alcuni casi limite nella coercizione di tipo.

Correzione:

Preferisco i preparati nativi in produzione. Imposta PDO::ATTR_EMULATE_PREPARES => false al tempo della connessione in modo che il comportamento sia coerente tra gli ambienti:

<?php
$conn = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE          => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_EMULATE_PREPARES => false,
]);

Per dettagli su quando utilizzare ogni modalità, vedi PDO::p repare.

Problemi con i tipi di dati

I caratteri Unicode appaiono come `?` o distorti

Sintomi:

Le righe che PHP scrive contengono punti interrogativi o caratteri sostitutivi invece dei caratteri originali non ASCII. Le letture rispondono a testo confuso.

Possibili cause e soluzioni:

Il tipo di colonna è VARCHAR, non NVARCHAR. le colonne varchar usano una code page, non Unicode. Usa nvarchar per il testo internazionalizzato.

Manca un suggerimento di codifica UTF-8 su PDO_SQLSRV. Quando la colonna SQL Server è nvarchar e i dati PHP sono UTF-8, indica al driver di convertire tra UTF-8 (client) e UTF-16 (server):

<?php
$conn = new PDO(
    "sqlsrv:Server=<server>;Database=<database>;Encrypt=true",
    $user,
    $password,
    [
        PDO::ATTR_ERRMODE                    => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING            => PDO::SQLSRV_ENCODING_UTF8,
    ]
);

Driver SQLSRV: richiedi esplicitamente UTF-8. SQLSRV_ENC_CHAR è la pagina di codice di sistema predefinita a 8 bit, non UTF-8. Per UTF-8 con SQLSRV, imposta "CharacterSet" => "UTF-8" la connessione e passa il letterale 'UTF-8' a SQLSRV_PHPTYPE_STRING on fetch o bind. Vedi Invia e recupera dati UTF-8.

Errori di conversione di data e ora

Sintomi:

SQLSTATE[22007]: Invalid character value for cast specification

Correzione:

A PDO_SQLSRV, non legare un oggetto grezzo DateTime . PDO stringifica i valori vincolati prima del vincolare, e quello di DateTime PHP non __toString() ha metodo, quindi execute([new DateTime(...)]) aumenta Object of class DateTime could not be converted to string. Formatta prima il valore, oppure passa una stringa ISO 8601 (YYYY-MM-DD HH:MM:SS[.fff]), non una stringa formattata localmente.

<?php
$stmt = $conn->prepare("INSERT INTO dbo.Events (EventDate) VALUES (?)");
$stmt->execute([(new DateTime("2026-03-15 10:00:00"))->format("Y-m-d H:i:s.u")]);

Per recuperare le colonne datatime come DateTime oggetti invece che stringhe su PDO_SQLSRV, imposta l'attributo dell'istruzione:

<?php
$stmt = $conn->prepare("SELECT EventDate FROM dbo.Events");
$stmt->setAttribute(PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE, true);
$stmt->execute();

Per dettagli, vedi Recupera oggetti datatime (PDO_SQLSRV).

Problemi di formattazione decimale

Sintomi:

I valori tra -1 e 1 mancano uno zero all'inizio, oppure i valori di denaro e moneta piccola mostrano un numero inaspettato di decimali.

Correzione:

PDO_SQLSRV recupera sempre i valori decimali e numerici come stringhe con la loro precisione e scala esatte. Imposta PDO::SQLSRV_ATTR_FORMAT_DECIMALS per aggiungere uno zero all'inizio ai valori compresi tra -1 e 1:

<?php
$conn->setAttribute(PDO::SQLSRV_ATTR_FORMAT_DECIMALS, true);

PDO::SQLSRV_ATTR_DECIMAL_PLACES Si applica solo ai valori del denaro e dei piccoli soldi . Imposta la scala visualizzata da 0 a 4 e può arrotondare il valore visualizzato. Non influisce sui valori decimali o numerici .

Per dettagli, vedi Formatare decimali e denaro (PDO_SQLSRV) oppure Formatare decimali e denaro (SQLSRV).

Problemi di transazione

I cambiamenti nei dati non persistono

Sintomi:

Le righe che inserisci o aggiorni in PHP non appaiono quando fai query da un'altra sessione.

Causa:

PDO::beginTransaction() apre una transazione esplicita che richiede un esplicito commit(). Se lo script PHP termina senza chiamare commit(), PDO annulla la transazione durante la pulizia della connessione.

Correzione:

Abbina beginTransaction() sempre a commit(), e usa try/catch per tornare indietro in caso di errore:

<?php
try {
    $conn->beginTransaction();
    $conn->exec("INSERT INTO dbo.Orders (CustomerID, Total) VALUES (1, 100)");
    $conn->exec("UPDATE dbo.Inventory SET Stock = Stock - 1 WHERE ProductID = 5");
    $conn->commit();
} catch (PDOException $e) {
    $conn->rollBack();
    throw $e;
}

Per SQLSRV, si usano sqlsrv_begin_transaction, sqlsrv_commit, e sqlsrv_rollback.

Errori di deadlock

Sintomi:

SQLSTATE[40001]: [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Transaction (Process ID 62) was deadlocked

Correzione:

Gestire gli errori di deadlock transitori con la logica di ritento. Incapsula l'intera transazione (non solo l'estratto in fallimento) così che gli estratti precedenti si riproducano sulla transazione nuova. Per un pattern di ritentazione orientato alla produzione, consulta l'esempio nella pagina di destinazione del driver PHP.

Blocchi ricorrenti indicano un problema di progettazione. Cattura il grafico di deadlock e analizza quali istruzioni e tipi di lock sono coinvolti. Le correzioni comuni includono operazioni di riordino affinché le transazioni concorrenti acquisiscano lock nella stessa sequenza, la riduzione dell'ambito delle transazioni e l'aggiunta di indici per ridurre la durata dei lock. Per una guida completa, consulta la guida Deadlocks.

Problemi di resilienza delle connessioni

La riconnessione non avviene

Sintomi:

Una connessione idle rimane interrotta dopo un failover database SQL di Azure, anche se hai impostato ConnectRetryCount e ConnectRetryInterval.

Possibili cause e soluzioni:

Cursore attivo lato server. La resilienza delle connessioni inattive riconnette solo le connessioni inattive . Un cursore aperto lato server o una transazione in sospeso mantiene attiva la connessione. Liberare cursori lato server usando sqlsrv_free_stmt() o $stmt = null; (PDO) prima della finestra di failover, oppure passare a un cursore bufferizzato lato client. Vedi resilienza alla connessione idle.
Stato di sessione non recuperabile. Alcuni stati della sessione non possono essere ristabiliti, inclusi tabelle temporanee, cursori globali e locali, contesto delle transazioni, blocchi applicazioni, EXECUTE AS/REVERThandle di automazione OLE, handle XML preparati e flag di tracciamento. Qualsiasi di questi stati di sessione impedisce la riconnessione automatica.
LoginTimeout Troppo piccolo. Se ConnectRetryCount * ConnectRetryInterval > LoginTimeout, il driver smette di riprovare quando LoginTimeout viene raggiunto. Aumenta LoginTimeout per coprire l'intero budget dei ripetiti.

Problemi di prestazioni

Per la diagnosi e la risoluzione di query lente, partenze a freddo, grandi set di risultati e inserti in massa, vedi Performance tuning.

Abilita la diagnostica dei driver

Quando le chiamate a livello error_log() di applicazione non forniscono informazioni sufficienti, attiva il logging lato guidatore. Segnala ogni chiamata ODBC fatta dal conducente.

PDO_SQLSRV

Imposta pdo_sqlsrv.log_severityphp.ini e riavvia il server web. Questa impostazione è leggibile solo all'inizializzazione:

[pdo_sqlsrv]
pdo_sqlsrv.log_severity = 1

I valori sono 0 (off, il predefinito), -1 (errori, avvisi e avvisi), 1 (errori), 2 (avvisi) e 4 (avvisi).

SQLSRV

Abilita la registrazione in tempo reale con sqlsrv_configure():

<?php
sqlsrv_configure("LogSubsystems", SQLSRV_LOG_SYSTEM_CONN | SQLSRV_LOG_SYSTEM_STMT);
sqlsrv_configure("LogSeverity", SQLSRV_LOG_SEVERITY_ERROR | SQLSRV_LOG_SEVERITY_WARNING);

Le voci di log vanno al file configurato da error_log in php.ini. Per l'elenco completo dei sottosistemi e delle gravità, vedi Attività di registrazione.

Problemi di container e CI

Librerie di sistema mancanti su Linux

Sintomi:

error while loading shared libraries: libodbc.so.2: cannot open shared object file
error while loading shared libraries: libssl.so.1.1: cannot open shared object file

Correzione:

Installa le dipendenze di runtime prima di installare il driver PHP:

Distribution	Installa comando
Ubuntu e Nebian	`sudo apt-get install unixodbc libgssapi-krb5-2`
Red Hat e Fedora	`sudo dnf install unixODBC krb5-libs`
Alpine	`apk add unixodbc gcompat`

Poi installa msodbcsql18 dal repository di pacchetti Microsoft. Per repository e versioni di pacchetti specifici per distribuzione, consulta la guida all'installazione dei driver ODBC.

Le build di immagini Docker hanno successo ma le connessioni falliscono a runtime

Sintomi:

L'immagine si compila e PHP si avvia, ma PDO::__construct() mostra un errore ODBC driver-in-found.

Correzione:

Verifica che il driver ODBC sia installato nell'immagine di runtime, non solo nella fase di compilazione. Installa msodbcsql18 e unixodbc-dev nella stessa fase in cui viene spedito in produzione. In una costruzione a più stadi, installali nella fase finale. Un'installazione basata su Debian a singolo stadio appare così:

# Pin to a specific PHP minor version in production, for example php:8.4.11-cli.
FROM php:8.4-cli
RUN apt-get update && apt-get install -y --no-install-recommends \
        curl gnupg2 apt-transport-https ca-certificates \
    && curl -sSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > /usr/share/keyrings/microsoft.gpg \
    && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/microsoft.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" > /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update \
    && ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 unixodbc-dev \
    # $PHPIZE_DEPS ships in the official php image and includes gcc, make, autoconf, and re2c.
    && apt-get install -y --no-install-recommends $PHPIZE_DEPS \
    && pecl install sqlsrv pdo_sqlsrv \
    && docker-php-ext-enable sqlsrv pdo_sqlsrv \
    && apt-get purge -y --auto-remove $PHPIZE_DEPS \
    && rm -rf /var/lib/apt/lists/*

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-08-13

Risoluzione dei driver Microsoft per PHP per SQL Server

Problemi di installazione

Estensione non caricata

L'installazione di PECL fallisce su Linux o macOS

Molteplici versioni PHP installate

Problemi di connessione

Impossibile connettersi al server

Accesso non riuscito

Valore non valido specificato per l'attributo stringa di connessione 'Authentication'

La parola chiave non valida 'UID' è stata specificata nella stringa DSN

PDO_SQLSRV ignora silenziosamente AccessToken nell'array delle opzioni

Errori del certificato TLS

Timeout della connessione

Problemi di esecuzione delle query

Guasti silenziosi con PDO

Nome di oggetto non valido

Numero sbagliato di parametri

PDO emulato prepara errori di maschera

Problemi con i tipi di dati

I caratteri Unicode appaiono come ? o distorti

Errori di conversione di data e ora

Problemi di formattazione decimale

Problemi di transazione

I cambiamenti nei dati non persistono

Errori di deadlock

Problemi di resilienza delle connessioni

La riconnessione non avviene

Problemi di prestazioni

Abilita la diagnostica dei driver

PDO_SQLSRV

SQLSRV

Problemi di container e CI

Librerie di sistema mancanti su Linux

Le build di immagini Docker hanno successo ma le connessioni falliscono a runtime

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive

I caratteri Unicode appaiono come `?` o distorti