Risolvere i problemi 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 sezione sqlsrv o pdo_sqlsrv.
PDOException: could not find driver durante la creazione di PDO utilizzando il DSN sqlsrv:.
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
Alpine: apk add unixodbc-dev
macOS: brew install unixodbc

Poi riprova:

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv

Se pecl continua a non riuscire dopo l'installazione degli header, la toolchain di compilazione 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 di PHP ha una propria directory php.ini e 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, verificare la connettività TCP di base.

# 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 locali di SQL Server usano per impostazione predefinita solo l'autenticazione di 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 associato 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 è a quale driver è associato PDO_SQLSRV. 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 indica sempre il driver che lo ha generato, quindi il prefisso [Microsoft][ODBC Driver 17 for SQL Server] nel messaggio di errore è il modo più rapido per confermare quale driver errato è associato.

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 applica un elenco di parole chiave DSN consentite e non accetta UID o PWD nel DSN. PDO riserva il secondo e il terzo argomento del costruttore a tale scopo 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, per contro, accetta UID e PWD nell'array delle opzioni di connessione passato 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/, ManagedIdentityCredential o ClientSecretCredential) e lo passi a PDO_SQLSRV come ['AccessToken' => $token] nel quarto argomento del costruttore. 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 ignora senza segnalarlo le voci con chiave stringa, come AccessToken, quindi PDO_SQLSRV non riceve mai il token. La connessione poi torna all'autenticazione integrata di Windows, che il server rifiuta.

Correzione:

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

<?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 l'API procedurale SQLSRV, AccessToken va nell'array di informazioni sulla connessione passato a sqlsrv_connect(), che incapsula per te il JWT non elaborato in SQL_COPT_SS_ACCESS_TOKEN:

<?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. Le operazioni di failover dei gruppi di failover e i database avviati a freddo possono richiedere più tempo di quanto consentito da un breve timeout lato client. Vedi Opzioni di connessione per il riferimento delle opzioni.
Limite di riconnessione in stato inattivo troncato. Se imposti ConnectRetryCount e ConnectRetryInterval, assicurati LoginTimeout >= ConnectRetryCount * ConnectRetryInterval. Altrimenti il timeout del login interrompe il ciclo di riconnessione in anticipo. Vedi resilienza delle connessioni inattive.

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

Errori silenziosi con PDO

Sintomo:

Una chiamata a PDO::exec() o PDOStatement::execute() restituisce false ma non genera un'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 regola di confronto con distinzione tra maiuscole e minuscole trattano products e Products come oggetti distinti. 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:

In PDO_SQLSRV, il numero di segnaposto ? deve corrispondere al numero di valori passati a execute() e ogni ? associa un singolo valore scalare (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 all'associazione dei parametri, vedi Eseguire query parametrizzate.

Le prepare emulate di PDO mascherano gli errori

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. Le istruzioni preparate emulate (PDO::ATTR_EMULATE_PREPARES = true) interpolano i parametri lato client. Native prepara (false) l'invio separato della query e dei parametri al server. Il comportamento differisce per TOP (?), i parametri con 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 i dettagli su quando utilizzare ciascuna modalità, consulta PDO::prepare.

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 restituiscono testo illeggibile.

Possibili cause e soluzioni:

Il tipo di colonna è VARCHAR, non NVARCHAR. Le colonne varchar usano una tabella codici, non utilizzano 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 usare UTF-8 con SQLSRV, imposta "CharacterSet" => "UTF-8" nella connessione e passa il valore letterale 'UTF-8' a SQLSRV_PHPTYPE_STRING durante il recupero o l'associazione. Vedi Invia e recupera dati UTF-8.

Errori di conversione di data e ora

Sintomi:

SQLSTATE[22007]: Invalid character value for cast specification

Correzione:

In PDO_SQLSRV, non associare un oggetto raw DateTime. PDO converte in stringa i valori associati prima dell'associazione e l'DateTime di PHP non dispone del metodo __toString(), quindi execute([new DateTime(...)]) genera 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 ottenere le colonne datetime come oggetti DateTime anziché come stringhe in 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 compresi tra -1 e 1 non hanno uno zero iniziale, oppure i valori money e smallmoney presentano un numero imprevisto di cifre 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, utilizzare 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:

Gestisci gli errori di deadlock temporanei con la logica di ripetizione. Racchiudi l'intera transazione (non solo l'istruzione che non riesce) in modo che le istruzioni precedenti vengano rieseguite nella nuova transazione. 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 sul 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 delle connessioni inattive.
Stato di sessione non recuperabile. Parte dello stato della sessione non può essere ripristinato, tra cui le tabelle temporanee, i cursori globali e locali, il contesto della transazione, i blocchi dell'applicazione, EXECUTE AS/REVERT gli handle di automazione OLE, gli handle XML preparati e i flag di traccia. Qualsiasi di questi stati di sessione impedisce la riconnessione automatica.
LoginTimeout Troppo piccolo. Se ConnectRetryCount * ConnectRetryInterval > LoginTimeout, il driver interrompe i tentativi al raggiungimento di LoginTimeout. Aumenta LoginTimeout fino a coprire l'intero budget di tentativi.

Problemi di prestazioni

Per la diagnosi e la risoluzione di query lente, avvii a freddo, set di risultati di grandi dimensioni e inserimenti in blocco, consulta Performance tuning.

Abilita la diagnostica dei driver

Quando le chiamate error_log() a livello di applicazione non forniscono informazioni sufficienti, abilita la registrazione lato driver. 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 viene compilata e PHP si avvia, ma PDO::__construct() restituisce un errore di driver ODBC non trovato.

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-24

Risolvere i problemi 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

Errori silenziosi con PDO

Nome di oggetto non valido

Numero sbagliato di parametri

Le prepare emulate di PDO mascherano gli errori

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