Szybki start: nawiązywanie połączenia i wykonywanie zapytań za pomocą sterowników Microsoft dla PHP do programu SQL Server

Użyj tego szybkiego startu, aby zainstalować sterowniki PHP, połączyć się z Azure SQL swoją tożsamością Microsoft Entra i uruchomić parametryzowane zapytanie Transact-SQL (T-SQL) na przykładowych AdventureWorksLT danych. Wybierz proceduralne API SQLSRV lub API PDO_SQLSRV. Oba sample odczytują ustawienia połączenia ze zmiennych środowiskowych i dają ten sam wynik.

Zapytanie odczytuje dane produktowe i nie tworzy obiektów bazy danych.

Zanim zaczniesz

Utwórz lub połącz się z bazą danych zawierającą przykładowe AdventureWorksLT dane. Instrukcje dotyczące konfiguracji usługi Azure SQL Database, bazy danych SQL w usłudze Microsoft Fabric, programu SQL Server oraz kontenerów SQL Server można znaleźć w przykładowych bazach danych AdventureWorks.
Poproś administratora bazy danych o utworzenie użytkownika bazy danych dla Twojej tożsamości Microsoft Entra.
W Windows zaloguj się kontem Windows, które ma dostęp do bazy danych.
W systemie macOS lub Linux uzyskaj bilet Kerberos dla federowanego konta Microsoft Entra. Wymagania można znaleźć w artykule Używanie Microsoft Entra ID ze sterownikiem ODBC.

1. Zainstaluj PHP i sterowniki

Wybierz swój system operacyjny. Skopiuj cały blok poleceń, wklej go do wyznaczonego terminala i uruchom go.

Otwórz program PowerShell jako administrator. Skopiuj i uruchom ten blok:

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

Ostatnie trzy polecenia wyświetlają zainstalowane wersje PHP i rozszerzenia. Zamknij okno z uprawnieniami administratora po pomyślnym zakończeniu operacji.

Uruchom kolejny blok w terminalu. Prompty homebrew przed instalacją jakichkolwiek brakujących wymagań wstępnych:

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

Jeśli brew nie jest zainstalowany, zainstaluj Homebrew, otwórz nowy terminal i uruchom blok ponownie.

Uruchom następujący blok w terminalu na obsługiwanej wersji 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

W przypadku innych dystrybucji Linuksa skorzystaj z tutoriala instalacji Linuksa i macOS.

Jeśli którekolwiek z poleceń php --ri informuje, że rozszerzenie nie jest zainstalowane, przed kontynuowaniem przejdź do sekcji Rozwiązywanie problemów z instalacją.

2. Ustaw informacje o połączeniu

Zastąp <server> i <database> w bloku dla swojego systemu operacyjnego. Skopiuj i uruchom cały blok w tym samym terminalu, którego będziesz używać do uruchamiania 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"

Ważna

Oba przykłady umożliwiają szyfrowanie i walidują certyfikat serwera. Jeśli Twój serwer korzysta z certyfikatu wystawionego przez prywatny urząd certyfikacji (CA), zainstaluj w magazynie zaufanych certyfikatów systemu operacyjnego klienta certyfikaty głównego i pośredniego urzędu certyfikacji. Ustaw SQL_SERVER na nazwę znajdującą się w polu Subject Alternative Name lub Common Name certyfikatu. W przeciwnym razie ustanowienie połączenia kończy się niepowodzeniem, zanim zapytanie zostanie wykonane. Więcej informacji można znaleźć w artykule Łańcuch certyfikatów nieufny oraz Konfiguruj szyfrowanie SQL Server.

TrustServerCertificate=true Omija walidację tożsamości serwera. Używaj go tylko do diagnozowania izolowanego lokalnego środowiska testowego, a nie jako konfiguracji zaufania dla środowisk produkcyjnych czy współdzielonych.

3. Stwórz i przejdź próbkę

Wybierz jedno API PHP. Utwórz nazwany plik, używając kodu w wybranej karcie, a następnie wykonaj polecenie po kodzie.

SQLSRV
PDO_SQLSRV

Utwórz quickstart-sqlsrv.php za pomocą następującego kodu:

<?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']);
}

Uruchom przykład:

php quickstart-sqlsrv.php

Utwórz quickstart-pdo.php za pomocą następującego kodu:

<?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']);
}

Uruchom przykład:

php quickstart-pdo.php

4. Zweryfikować wynik

Wiersze produktów mogą się różnić w zależności od wersji AdventureWorksLT. Obie próbki dają wynik przypominający ten przykład:

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

Każda próbka sprawdza, czy zapytanie zwraca pięć produktów o niepustych nazwach i rosnących identyfikatorach produktów, zanim wydrukuje wiersze. Następnie zwolni oświadczenie i zamyka połączenie. Zapytanie nie pozostawia żadnych obiektów ani danych do usunięcia w bazie danych.

Użyj innej metody uwierzytelniania

Przykłady obsługują także uwierzytelnianie za pomocą tożsamości zarządzanej oraz uwierzytelnianie SQL Server bez konieczności zmiany plików PHP.

Tożsamość zarządzana

W przypadku aplikacji hostowanej w Azure włącz zarządzaną tożsamość i stwórz jej użytkownika bazy danych. Ustaw serwer, bazę danych i tryb uwierzytelniania w konfiguracji aplikacji:

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

Nie ustawiaj SQL_USER ani SQL_PASSWORD.

W przypadku bazy danych SQL w Microsoft Fabric nadaj tożsamości uprawnienie do elementu Read za pomocą mechanizmów kontroli dostępu w usłudze Fabric. Użyj punktu końcowego połączenia SQL z elementu bazy danych, a nie punktu analityki SQL. Baza danych SQL w Fabric nie obsługuje uwierzytelniania SQL.

Uwierzytelnianie programu SQL Server

Używaj uwierzytelniania SQL Server tylko dla instancji SQL Server, którą kontrolujesz, na przykład izolowanego lokalnego kontenera deweloperskiego. Przechowywać dane uwierzytelniające w konfiguracji aplikacji lub w tajnym magazynie. Nie dodawaj ich do systemu kontroli wersji.

$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>"

Inne metody uwierzytelniania Microsoft Entra można znaleźć w artykule Connect using Microsoft Entra authentication.

Rozwiązywanie problemów przy instalacji

Użyj tych kontroli, jeśli blok instalacji zatrzyma się lub polecenie weryfikacji zakończy się niepowodzeniem.

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

Jeśli Get-Command nie może znaleźć php.exe, zamknij wszystkie terminale, otwórz nowe okno programu PowerShell i uruchom kontrole ponownie. Jeśli polecenie php --ri zgłasza Brak rozszerzenia, wykonaj ponownie polecenia instalacji PIE z 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"

Jeśli command -v nie znajdzie PHP, uruchom brew link --force --overwrite php@8.5, otwórz nowy terminal i ponownie przeprowadź kontrole.

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

Jeśli polecenie php --ri zwraca komunikat brak rozszerzenia, ponownie wykonaj polecenia instalacyjne PIE. Użyj ścieżki z php --ini, aby potwierdzić, że środowisko uruchomieniowe wiersza polecenia wczytuje konfigurację zaktualizowaną przez PIE.

Jeśli połączenie zgłasza FA001 i wskazuje, że opcji Authentication nie można używać z Integrated Security, potwierdź, że SQL_AUTHENTICATION ma dokładnie wartość ActiveDirectoryIntegrated. Uruchom php --ri sqlsrv lub php --ri pdo_sqlsrv sprawdź wersję sterownika PHP i zaktualizuj sterownik, jeśli jest starszy niż 5.10.1.

Czyszczenie

Próbki publikują swoje oświadczenia i zamykają swoje kontakty. Nie tworzą obiektów bazy danych ani nie utrzymują danych.

Ustawienia połączenia dotyczą bieżącej sesji terminala. Zamknij terminal, gdy skończysz.

Do ustawień ponawiania w środowisku produkcyjnym, limitu czasu, rejestrowania i mechanizmu przełączania awaryjnego użyj konfiguracji bazowej dla środowiska produkcyjnego zamiast rozszerzać ten przykład na pierwsze uruchomienie.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-09-25