Quickstart: Connetti e consulta con i driver Microsoft per PHP per SQL Server

Usa questa guida introduttiva rapida per installare i driver PHP, connetterti ad Azure SQL usando la tua identità Microsoft Entra ed eseguire una query Transact-SQL (T-SQL) parametrizzata sui dati di esempio AdventureWorksLT. Scegli l'API procedurale SQLSRV o l'API PDO_SQLSRV. Entrambi i campioni leggono le impostazioni di connessione dalle variabili di ambiente e restituiscono lo stesso risultato.

La query legge i dati prodotto e non crea oggetti di database.

Prima di iniziare

Crea o collegati a un database che contenga i dati campione AdventureWorksLT. Per istruzioni sulla configurazione di database SQL di Azure, Database SQL in Microsoft Fabric, SQL Server e contenitori SQL Server, vedere i database di esempio AdventureWorks.
Chiedi all'amministratore del database di creare un utente database per la tua identità Microsoft Entra.
Su Windows, accedi con l'account Windows che ha accesso al database.
Su macOS o Linux, ottieni un ticket Kerberos per un account Microsoft Entra federato. Per i requisiti, vedi Utilizzo di Microsoft Entra ID con il driver ODBC.

1. Installa PHP e i driver

Seleziona il tuo sistema operativo. Copia l'intero blocco di comando, incollalo nel terminale specificato e eseguilo.

Aprire PowerShell come amministratore. Copia e esegui questo blocco:

winget install --exact --id PHP.PHP.8.5 --source winget --accept-package-agreements --accept-source-agreements
winget install --exact --id Microsoft.msodbcsql.18 --source winget --accept-package-agreements --accept-source-agreements

$env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" +
    [Environment]::GetEnvironmentVariable("Path", "User")
New-Item -ItemType Directory -Force C:\php-quickstart | Out-Null
Set-Location C:\php-quickstart

$phpDirectory = Split-Path (Get-Command php.exe -ErrorAction Stop).Source
$phpIni = Join-Path $phpDirectory "php.ini"
if (-not (Test-Path $phpIni)) {
    Copy-Item (Join-Path $phpDirectory "php.ini-development") $phpIni
}

$configuration = [System.IO.File]::ReadAllText($phpIni)
$configuration = $configuration -replace '(?m)^\s*;\s*extension_dir\s*=\s*"ext"\s*$', 'extension_dir = "ext"'
$configuration = $configuration -replace '(?m)^\s*;\s*extension\s*=\s*openssl\s*$', 'extension=openssl'
$configuration = $configuration -replace '(?m)^\s*;\s*extension\s*=\s*zip\s*$', 'extension=zip'
[System.IO.File]::WriteAllText($phpIni, $configuration)

Invoke-WebRequest https://github.com/php/pie/releases/latest/download/pie.phar -OutFile pie.phar
php .\pie.phar install microsoft/sqlsrv
php .\pie.phar install microsoft/pdo_sqlsrv

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

Gli ultimi tre comandi mostrano le versioni installate di PHP ed estensione. Chiudi la finestra dell'amministratore una volta completata l'operazione con successo.

Esegui il blocco successivo in un terminale. Homebrew chiede conferma prima di installare eventuali prerequisiti mancanti:

brew install php@8.5 git autoconf automake libtool m4 make pkg-config
brew link --force --overwrite php@8.5
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew trust microsoft/mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar
sudo mkdir -p /usr/local/bin
sudo install /tmp/pie.phar /usr/local/bin/pie
export CPPFLAGS="-I$(brew --prefix unixodbc)/include"
export LDFLAGS="-L$(brew --prefix unixodbc)/lib"
pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

mkdir -p ~/php-quickstart
cd ~/php-quickstart
php --version
php --ri sqlsrv
php --ri pdo_sqlsrv

Se brew non è installato, installa Homebrew, apri un nuovo terminale ed esegui di nuovo il blocco.

Esegui il seguente blocco in un terminale su una versione supportata di Ubuntu:

sudo apt-get update
sudo apt-get install -y php-cli php-dev php-xml php-zip curl git autoconf automake libtool m4 make gcc g++ pkg-config unixodbc-dev

source /etc/os-release
curl -fsSLO "https://packages.microsoft.com/config/ubuntu/$VERSION_ID/packages-microsoft-prod.deb"
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar
sudo install /tmp/pie.phar /usr/local/bin/pie
pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

mkdir -p ~/php-quickstart
cd ~/php-quickstart
php --version
php --ri sqlsrv
php --ri pdo_sqlsrv

Per altre distribuzioni Linux, segui il tutorial di installazione di Linux e macOS.

Se uno dei comandi php --ri segnala che l'estensione non è presente, vai a Risoluzione dei problemi di installazione prima di continuare.

2. Impostare le informazioni di connessione

Sostituisci <server> e <database> nel blocco per il tuo sistema operativo. Copia e fai girare l'intero blocco nello stesso terminale che userai per eseguire PHP.

Set-Location C:\php-quickstart
$env:SQL_SERVER = "tcp:<server>.database.windows.net,1433"
$env:SQL_DATABASE = "<database>"
$env:SQL_AUTHENTICATION = "ActiveDirectoryIntegrated"

export SQL_SERVER="tcp:<server>.database.windows.net,1433"
export SQL_DATABASE="<database>"
export SQL_AUTHENTICATION="ActiveDirectoryIntegrated"

export SQL_SERVER="tcp:<server>.database.windows.net,1433"
export SQL_DATABASE="<database>"
export SQL_AUTHENTICATION="ActiveDirectoryIntegrated"

Importante

Entrambi i campioni consentono la crittografia e convalidano il certificato server. Se il tuo server utilizza un certificato di un'autorità di certificazione privata (CA), installa i certificati root e intermediari della CA emessa nel trust store del sistema operativo client. Imposta SQL_SERVER su un nome presente nel Nome alternativo soggetto o nel Nome comune del certificato. Altrimenti, la connessione fallisce prima che la query venga eseguita. Per ulteriori informazioni, consulta Catena di certificati non affidabile e Configura crittografia SQL Server.

TrustServerCertificate=true ignora la convalida dell'identità del server. Usalo solo per diagnosticare un ambiente di test locale isolato, non come configurazione di trust per ambienti di produzione o condivisi.

3. Creare ed eseguire un esempio

Seleziona un'API PHP. Crea il file con nome usando il codice nella scheda selezionata, e poi esegui il comando dopo il codice.

SQLSRV
PDO_SQLSRV

Creare quickstart-sqlsrv.php con il codice seguente:

<?php
declare(strict_types=1);

$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;
$authentication = getenv('SQL_AUTHENTICATION') ?: null;

if ($server === null || $database === null || $authentication === null) {
    throw new RuntimeException('Set SQL_SERVER, SQL_DATABASE, and SQL_AUTHENTICATION.');
}
if (!in_array($authentication, ['SqlPassword', 'ActiveDirectoryIntegrated', 'ActiveDirectoryMsi'], true)) {
    throw new RuntimeException(
        'Set SQL_AUTHENTICATION to SqlPassword, ActiveDirectoryIntegrated, or ActiveDirectoryMsi.'
    );
}

$user = null;
$password = null;
if ($authentication === 'SqlPassword') {
    $user = getenv('SQL_USER') ?: null;
    $password = getenv('SQL_PASSWORD') ?: null;
    if ($user === null || $password === null) {
        throw new RuntimeException('Set SQL_USER and SQL_PASSWORD for SqlPassword authentication.');
    }
}

$options = [
    'Database' => $database,
    'Authentication' => $authentication,
    'Driver' => 'ODBC Driver 18 for SQL Server',
    'Encrypt' => true,
    'TrustServerCertificate' => false,
];
if ($authentication === 'SqlPassword') {
    $options['UID'] = $user;
    $options['PWD'] = $password;
}

$connection = sqlsrv_connect($server, $options);
if ($connection === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}

$sql = <<<'SQL'
SELECT TOP (5) ProductID, Name
FROM SalesLT.Product
WHERE ProductID > ?
ORDER BY ProductID;
SQL;
$parameters = [0];
$statement = sqlsrv_query($connection, $sql, $parameters);
if ($statement === false) {
    $errors = sqlsrv_errors();
    sqlsrv_close($connection);
    throw new RuntimeException(print_r($errors, true));
}

$rows = [];
while (($row = sqlsrv_fetch_array($statement, SQLSRV_FETCH_ASSOC)) !== null) {
    if ($row === false) {
        $errors = sqlsrv_errors();
        sqlsrv_free_stmt($statement);
        sqlsrv_close($connection);
        throw new RuntimeException(print_r($errors, true));
    }
    $rows[] = $row;
}
sqlsrv_free_stmt($statement);
sqlsrv_close($connection);

if (count($rows) !== 5) {
    throw new RuntimeException('Unexpected query result.');
}
$previousProductId = 0;
foreach ($rows as $row) {
    if ($row['ProductID'] <= $previousProductId || $row['Name'] === '') {
        throw new RuntimeException('Unexpected query result.');
    }
    $previousProductId = $row['ProductID'];
}
printf("%-12s%s\n", 'Product ID', 'Name');
printf("%-12s%s\n", '----------', '----');
foreach ($rows as $row) {
    printf("%-12d%s\n", $row['ProductID'], $row['Name']);
}

Esegui l'esempio:

php quickstart-sqlsrv.php

Creare quickstart-pdo.php con il codice seguente:

<?php
declare(strict_types=1);

$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;
$authentication = getenv('SQL_AUTHENTICATION') ?: null;

if ($server === null || $database === null || $authentication === null) {
    throw new RuntimeException('Set SQL_SERVER, SQL_DATABASE, and SQL_AUTHENTICATION.');
}
if (!in_array($authentication, ['SqlPassword', 'ActiveDirectoryIntegrated', 'ActiveDirectoryMsi'], true)) {
    throw new RuntimeException(
        'Set SQL_AUTHENTICATION to SqlPassword, ActiveDirectoryIntegrated, or ActiveDirectoryMsi.'
    );
}

$user = null;
$password = null;
if ($authentication === 'SqlPassword') {
    $user = getenv('SQL_USER') ?: null;
    $password = getenv('SQL_PASSWORD') ?: null;
    if ($user === null || $password === null) {
        throw new RuntimeException('Set SQL_USER and SQL_PASSWORD for SqlPassword authentication.');
    }
}

$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};"
    . "Server=$server;Database=$database;Authentication=$authentication;"
    . "Encrypt=true;TrustServerCertificate=false";
$connection = new PDO(
    $dsn,
    $user,
    $password,
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        PDO::ATTR_EMULATE_PREPARES => false,
    ]
);

$sql = <<<'SQL'
SELECT TOP (5) ProductID, Name
FROM SalesLT.Product
WHERE ProductID > ?
ORDER BY ProductID;
SQL;
$statement = $connection->prepare($sql);
$statement->execute([0]);
$rows = $statement->fetchAll();
$statement->closeCursor();
$connection = null;

if (count($rows) !== 5) {
    throw new RuntimeException('Unexpected query result.');
}
$previousProductId = 0;
foreach ($rows as $row) {
    if ($row['ProductID'] <= $previousProductId || $row['Name'] === '') {
        throw new RuntimeException('Unexpected query result.');
    }
    $previousProductId = $row['ProductID'];
}
printf("%-12s%s\n", 'Product ID', 'Name');
printf("%-12s%s\n", '----------', '----');
foreach ($rows as $row) {
    printf("%-12d%s\n", $row['ProductID'], $row['Name']);
}

Esegui l'esempio:

php quickstart-pdo.php

4. Verifica il risultato

Le righe di prodotto possono variare a seconda della versione di AdventureWorksLT. Entrambi i campioni restituiscono un'uscita che ricorda questo esempio:

Product ID  Name
----------  ----
680         HL Road Frame - Black, 58
706         HL Road Frame - Red, 58
707         Sport-100 Helmet, Red
708         Sport-100 Helmet, Black
709         Mountain Bike Socks, M

Ogni campione verifica che la query abbia restituito cinque prodotti con nomi non vuoti e ID prodotto ascendenti prima di stampare le righe. Poi rilascia la dichiarazione e chiude la connessione. La query non lascia oggetti o dati del database da rimuovere.

Usa un altro metodo di autenticazione

I campioni accettano anche identità gestita e autenticazione SQL Server senza modificare i file PHP.

Identità gestita

Per un'applicazione ospitata in Azure, abilita un'identità gestita e crea il suo utente database. Imposta server, database e modalità di autenticazione nella configurazione dell'applicazione:

SQL_SERVER=tcp:<server>.database.windows.net,1433
SQL_DATABASE=<database>
SQL_AUTHENTICATION=ActiveDirectoryMsi

Non impostare SQL_USER o SQL_PASSWORD.

Per il database SQL di Microsoft Fabric, concedere all'identità l'autorizzazione per l'elemento Read tramite Fabric access controls. Usa l'endpoint di connessione SQL della voce del database, non quello di analisi SQL. Il database SQL in Fabric non supporta l'autenticazione SQL.

Autenticazione di SQL Server

Usa l'autenticazione SQL Server solo per un'istanza SQL Server che controlli, come un container di sviluppo locale isolato. Conserva le credenziali nella configurazione dell'applicazione o in un archivio segreto. Non inserirli nel sistema di controllo della versione.

$env:SQL_SERVER = "tcp:<server>,1433"
$env:SQL_DATABASE = "<database>"
$env:SQL_AUTHENTICATION = "SqlPassword"
$env:SQL_USER = "<user_id>"
$env:SQL_PASSWORD = "<password>"

export SQL_SERVER="tcp:<server>,1433"
export SQL_DATABASE="<database>"
export SQL_AUTHENTICATION="SqlPassword"
export SQL_USER="<user_id>"
export SQL_PASSWORD="<password>"

export SQL_SERVER="tcp:<server>,1433"
export SQL_DATABASE="<database>"
export SQL_AUTHENTICATION="SqlPassword"
export SQL_USER="<user_id>"
export SQL_PASSWORD="<password>"

Per altri metodi di autenticazione Microsoft Entra, vedi Connect using Microsoft Entra authentication.

Risoluzione dei problemi dell'installazione

Usa questi controlli se il blocco di installazione si ferma o se un comando di verifica fallisce.

Get-Command php.exe
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv
Get-OdbcDriver -Name "ODBC Driver 18 for SQL Server"

Se Get-Command non riesci a trovare php.exe, chiudi tutti i terminali, apri una nuova finestra PowerShell e rifai i controlli. Se un php --ri comando segnala l'assenza di Extension, rieseguire i comandi di installazione PIE da C:\php-quickstart.

command -v php
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv
odbcinst -q -d | grep "ODBC Driver 18 for SQL Server"

Se command -v non trova PHP, esegui brew link --force --overwrite php@8.5, apri un nuovo terminale ed esegui di nuovo i controlli.

command -v php
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv
odbcinst -q -d | grep "ODBC Driver 18 for SQL Server"

Se un php --ri comando segnala l'assenza di un'estensione, rieseguire i comandi di installazione PIE. Usa il percorso da php --ini in poi per confermare che il runtime della riga di comando carica la configurazione aggiornata da PIE.

Se una connessione segnala FA001 e dice che l'opzione Autenticazione non può essere usata con Integrated Security, conferma che SQL_AUTHENTICATION sia esattamente ActiveDirectoryIntegrated. Esegui php --ri sqlsrv o php --ri pdo_sqlsrv per controllare la versione del driver PHP e aggiorna il driver se è precedente alla versione 5.10.1.

Pulizia

I campioni rilasciano le loro dichiarazioni e chiudono i loro contatti. Non creano oggetti di database né persistono dati.

Le impostazioni di connessione si applicano alla sessione terminale corrente. Chiudi il terminale quando hai finito.

Per le impostazioni di produzione relative a nuovi tentativi, timeout, registrazione e failover, utilizza la configurazione di base per la produzione invece di estendere questo esempio iniziale.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-09-25