Nainstalujte Microsoft ovladače pro PHP na Linux a macOS

Tyto instrukce instalují PHP, Microsoft ODBC ovladač pro SQL Server a rozšíření SQLSRV a PDO_SQLSRV. Každá záložka používá PHP balíček poskytovaný repozitářem, ze kterého daná záložka instaluje, takže verze v příkazech se mezi jednotlivými záložkami liší. Pokud tento repozitář nabízí jinou verzi PHP uvedenou v podpůrné matici, nahraďte ji touto verzí PHP.

SQLSRV a PDO_SQLSRV ovladače používají stejnou závislost ODBC a lze je nainstalovat samostatně. Nainstalujte obě rozšíření, pokud vaše aplikace používá oba ovladače.

Na konci procedury by měly CLI a vybraný runtime webového serveru načíst obě rozšíření, obě PHP API by měla být dostupná a vzorek pro každé API by měl vrátit verzi databázového serveru.

Než začnete

  1. Vyberte si verzi PHP podporovanou aktuálním vydáním ovladače a dostupnou pro verzi vašeho operačního systému.

  2. Rozhodněte se, jaké PHP runtime prostředí potřebujete:

    • CLI pro skripty, plánované úkoly nebo workery.
    • Modul Apache pro PHP hostované na serveru Apache.
    • PHP-FPM pro nginx nebo konfiguraci Apache FastCGI.

  3. Potvrďte architekturu operačního systému. Vydané linuxové archivy obsahují x64 binární soubory a vydané macOS archivy obsahují Arm64 binární soubory. Sestavení PIE slouží k instalaci PHP na počítači a je hlavní cestou instalace v tomto článku.

  4. Nainstalujte ovladač Microsoft ODBC a vývojový balíček unixODBC. Balíček Microsoft zajišťuje komunikaci s databází. Balíček unixODBC poskytuje hlavičky potřebné pro sestavení SQLSRV a PDO_SQLSRV.

  5. Naplánujte restart každého webového serveru, PHP-FPM poolu a dlouho běžícího worker procesu po instalaci nebo změně rozšíření.

Správce balíčků platformy instaluje PHP a nativní závislosti. PIE vytváří a instaluje PHP rozšíření. Konfigurace PHP určuje, zda je načítá každé běhové prostředí. Ovladač ODBC zajišťuje komunikaci s databází a šifrování po načtení rozšíření.

Nainstalujte ovladače pomocí PIE

PIE, instalátor rozšíření pro PHP, je podporovaný instalátor rozšíření pro aktuální verze ovladačů. Nahrazuje pracovní postup označený jako zastaralý PHP Extension Community Library (PECL).

Před instalací ovladačů splňte požadavky platformy v následujících částech. Pak nainstalujte PIE a každý ovladač zvlášť:

Instalace PIE

PIE běží na verzích PHP 8.1 a později. Může nainstalovat rozšíření do jiné PHP instalace, když vyberete vývojové nástroje té instalace.

Nainstalujte curl a GitHub CLI, než budete pokračovat. Sekce platformy zahrnují curl v případech, kdy jej minimální instalace nemusí obsahovat.

Stáhněte si archiv PIE PHP (PHAR) a před instalací nebo spuštěním jej ověřte pomocí rozhraní příkazového řádku GitHubu (CLI):

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"

Pokračujte pouze v případě, že ověření uspěje:

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

Dočasný adresář patří pouze vašemu účtu. Pokud stažení nebo ověření selže, neinstalujte ani nespusťte PHAR. Odstraňte dočasný soubor a adresář před dalším pokusem.

Ověřte, že nainstalovaný PHAR běží s PHP spustitelným souborem, který chcete použít:

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

Nainstalujte SQLSRV a PDO_SQLSRV ovladače

V Linuxu a macOS PIE kontroluje přítomnost kompilátoru a potřebných vývojových nástrojů pro PHP. Před spuštěním PIE nainstalujte vývojový balíček ODBC platformy a kompilátor C++. Spusť PIE z interaktivního terminálu. Může si vyžádat vaše sudo heslo, když potřebuje povolení k instalaci souborů do systémových adresářů.

PIE cílí na instalaci PHP použitou k jeho vyvolání. Pro instalaci konkrétní verze přidejte --with-php-config ke každému instalačnímu příkazu pro výběr vývojových nástrojů. Například použijte pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv , když je zamýšlený nástroj /usr/bin/php-config8.4. Stejnou možnost aplikujte na microsoft/pdo_sqlsrv. Alpine používá verzované názvy spustitelných souborů; v této sekci se řiďte příkazy Alpine místo neverzovaných příkazů.

Spusť jeden příkaz pro každé rozšíření. Tyto příkazy používají výchozí instalaci PHP nástroje PIE:

pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

PIE se snaží povolit každé rozšíření prostřednictvím PHP konfiguračních nástrojů platformy nebo pomocí položky extension= a varuje, pokud to nejde. PHP používá serverové aplikační programové rozhraní (SAPI) pro každé prostředí pro spouštění. Na Debianu, Ubuntu a SUSE se konfigurace příkazového řádku, Apache a PHP FastCGI Process Manager (PHP-FPM) mohou lišit. Úspěšná instalace přes příkazový řádek nepotvrzuje, že webový server načítá moduly.

Informace o příkazovém řádku najdete v php --ini. Před vytvořením dočasné phpinfo() stránky pro webový server omezte přístup k diagnostické stránce. Zkontrolujte načtený konfigurační soubor a naskenované .ini soubory pro každý runtime. Pokud chybí záznamy, postupujte podle Načtení ovladačů v Linuxu a macOS, abyste je přidali ve správném pořadí načítání. Po změně konfigurace restartujte webový server nebo PHP-FPM. Red Hat běžně sdílí php.ini mezi SAPI, ale ověřte aktivní konfiguraci dříve, než se budete spoléhat na jeden běh PIE.

Nainstalujte na své platformě

Vyberte si operační systém a konfiguraci webového serveru. Dokončete kroky instalace v této záložce a pak sledujte Testování vaší instalace.

Instalace na Ubuntu

Poznámka:

Následující příkazy využívají packages.sury.org PHP repozitář, abyste mohli vybrat podporovanou verzi PHP. Použijte oficiální Microsoft instrukce k instalaci ovladače ODBC pro vaše vydání Ubuntu.

Krok 1. Instalace 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

Krok 2. Instalace požadavků (Ubuntu)

Postupujte podle Instalace ovladače Microsoft ODBC pro SQL Server v Linuxu a poté nainstalujte vývojové hlavičky.

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

Krok 3. Nainstalujte PHP ovladače pro Microsoft SQL Server pomocí PIE (Ubuntu)

Postupujte podle Install the drivers with PIE a do obou instalačních příkazů přidejte --with-php-config=/usr/bin/php-config8.4. Zkontrolujte konfigurační soubory příkazového řádku pomocí 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

Krok 4. Instalace Apache a konfigurace načítání ovladačů (Ubuntu)

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

Krok 5. Restartování Apache a otestování ukázkového skriptu (Ubuntu)

sudo systemctl restart apache2

Pokud chcete instalaci otestovat, přečtěte si téma Testování instalace na konci tohoto dokumentu.

Starší instalace PECL

PECL je pro aktuální verze ovladačů zastaralý. Používejte PIE pro nové instalace a modernizace. Pokud je existující nasazení připnuté k PECL, udržujte verze balíčků zarovnané s runtime PHP a plánujte přechod na PIE.

Otestujte svou instalaci

Ověřte modul runtime příkazového řádku. Na Alpine nahraďte php za php84. Pro instalaci PHP s uvedenou verzí na jiné distribuci použijte její odpovídající spustitelný soubor.

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

Oba --ri příkazy by měly vytisknout informace o modulu, které obsahují ExtensionVer. Seznam modulů by měl obsahovat samostatné řádky sqlsrv a pdo_sqlsrv.

Před testováním připojení ověřte obě rozhraní PHP API pomocí 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);

Očekávaný výstup:

SQLSRV: loaded
PDO_SQLSRV: loaded

Pro PHP-FPM nebo webový server omezte přístup k diagnostické stránce před vytvořením dočasné phpinfo() stránky. Potvrďte načtený konfigurační soubor, extension_dir a obě sekce ovladačů. Po změně konfigurace nebo výměně rozšíření restartujte PHP-FPM nebo webový server. Po ověření stránku odstraňte.

Pro testování živého připojení vytvořte soubor s názvem testsql.php v kořenovém adresáři dokumentů vašeho systému. Tato cesta je /var/www/html na Ubuntu, Debianu a Red Hatu, /srv/www/htdocs v SUSE, /var/www/localhost/htdocs v Alpine nebo $(brew --prefix)/var/www v macOS. Před spuštěním skriptu nastavte pro proces PHP proměnné prostředí SQL_SERVER_NAME, SQL_DATABASE, SQL_UID a SQL_PWD. Neukládejte přihlašovací údaje napevno do souboru pod kořenem dokumentu.

Pro test příkazové řádky použijte interaktivní výzvy k nastavení proměnných prostředí bez zadávání hesla do historie shellu.

Při testování modulu Apache nechte přihlašovací údaje mimo obecně čitelný konfigurační soubor webu:

  1. Vytvořte soukromý soubor mimo kořen dokumentu. Použijte nepoužité jméno souboru v konfiguračním adresáři Apache. V systému Linux:

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

    V systému Red Hat nahraďte /etc/apache2 prvkem /etc/httpd. Na macOS vytvořte soubor pod účtem, který spouští Homebrew Apache:

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

    Pouze vlastník souboru a root mohou tato nastavení číst. Účet, který spouští Apache, musí být schopen soubor přečíst.

  2. Upravte soukromý soubor v textovém editoru a přidejte tyto položky:

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

    V argumentech s dvojitou uvozovkou napište \\ pro každé doslovné zpětné lomítko a \" pro každou doslovnou dvojitou uvozovku. Udržujte úvodní a zadní mezery uvnitř uvozovek. Apache také nahrazuje reference ${NAME}. Pokud hodnota obsahuje tuto sekvenci nebo zalomení řádku, použijte místo toho test z příkazového řádku. Pro více informací viz uvozování a escapování v konfiguraci Apache.

  3. Uvnitř virtuálního hostitele webu přidejte blok Files, který obsahuje direktivu private file pouze pro testsql.php. Pokud není nakonfigurován žádný virtuální hostitel, umístěte blok do konfigurace hlavního serveru. Nahraďte zástupný symbol absolutní cestou soukromého souboru:

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

  4. Restartujte Apache. Po testování odstraňte přidaný Files blok, smažte soukromý soubor a znovu spusťte Apache. Zachovat nesouvisející nastavení webu.

PHP-FPM ve výchozím nastavení maže zděděné proměnné prostředí a nginx nepředává své prostředí do PHP-FPM. Následující postup pro Ubuntu nebo Red Hat používejte pouze s izolovanou testovací službou a fondem PHP-FPM. Nepřidávejte testovací přihlašovací údaje do služby nebo poolu, který spouště jiné aplikace: každý skript v tomto poolu je může číst. Pokud používáte sdílený hosting, použijte místo toho test z příkazového řádku.

  1. Vytvořte soubor vlastněný kořenem mimo kořen dokumentu, například /etc/php-sql-driver-test.env, a omezte k němu přístup:

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

    Přidejte nastavení připojení do souboru:

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

    Každé nastavení držte na jednom řádku. Do dvojitých uvozovek napište \\ pro každé doslovné zpětné lomítko a \" pro každou doslovnou dvojitou uvozovku. Znak dolaru a obrácené apostrofy nejsou vyhodnocovány jako výrazy shellu. Upravujte soubor přímo, místo abyste ho spouštěli nebo načítali pomocí `source` v shellu. Pro více informací viz syntaxe systemd EnvironmentFile.

  2. Spusť sudo systemctl edit php8.4-fpm na Ubuntu nebo sudo systemctl edit php-fpm na Red Hatu. Přidejte toto přepsání pro systemd:

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

  3. Přidejte tyto položky do konfigurace aktivního PHP-FPM poolu. Běžná místa jsou /etc/php/8.4/fpm/pool.d/www.conf na Ubuntu a /etc/php-fpm.d/www.conf na Red Hatu:

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

  4. Znovu načíst systemd a znovu spustit příslušnou PHP-FPM službu:

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

    Na Red Hat nahraďte php8.4-fpm za php-fpm.

Po testování odstraňte dočasný soubor prostředí, EnvironmentFile= přidaný záznam, záznamy z testovacího poolu a testsql.php. Soubor s přepsáním služby smažte pouze pokud jste ho vytvořili pro tento test a neobsahuje žádná další nastavení. Uchovejte všechna předchozí přepsání a nastavení poolu. Znovu načtěte systemd a znovu restartujte PHP-FPM po odstranění testovací konfigurace.

Příklad SQLSRV

Ponechte hodnoty prostředí beze změny. Každý příklad před připojením zkontroluje, zda nastavení nechybí ani není prázdné. Každý příklad pak zdvojnásobí uzavírací složené závorky a přidává vnější závorky před předáním názvu databáze, uživatelského jména a hesla ovladači. Toto kódování zachovává složené závorky a zabraňuje tomu, aby středníky oddělovaly možnosti připojení.

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

příklad 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);
?>

Nasměrujte prohlížeč na http://localhost/testsql.php (http://localhost:8080/testsql.php v systému macOS). Po úspěšném připojení se zobrazí verzní řetězec databázového serveru. Oba příklady zapisují detaily chyb do PHP error logu. Pokud stránka ukazuje selhání, zkontrolujte ten log.

Pro porovnání chování příkazové řádky a webového serveru nastavte stejné proměnné prostředí pro váš terminál a spusťte:

php testsql.php

Pokud spuštění z příkazové řádky proběhne úspěšně, ale v prohlížeči se nic neobjeví, zkontrolujte protokoly Apache. Další nápovědu najdete v části Zdroje podpory pro ovladač PHP SQL.

Vyhodnoťte programy pro připojení zvlášť pro SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, SQL databázi v Microsoft Fabric a Warehouse v Microsoft Fabric. Vybraná autentizační metoda, možnosti připojení a dotaz musí být podporovány cílovým systémem. Instalace probíhá na straně klienta. Úspěšná kontrola rozšíření neprokáže, že cílový server přijímá přihlašovací údaje, důvěřuje klientovi nebo podporuje všechny funkce databáze.

Řešení potíží s instalací

Symptom Nadřazená vrstva Nápravná akce
PIE nemůže najít phpize, php-config, ani hlavičky Vývojové balíčky PHP Nainstalujte vývojový balíček pro cílovou verzi PHP a zadejte odpovídající volbu --with-php-config
Kompilace selže, protože chybí kompilátor C++ Nástroje pro sestavení operačního systému Nainstalujte balíček kompilátoru C++ pro danou platformu, například g++ nebo gcc-c++
Kompilace nemůže najít sql.h Vývojový balíček ODBC nebo cesty ke kompilátoru Nainstalujte unixodbc-dev nebo unixODBC-devel; na Apple silikonu nastavte příznaky Homebrew include a knihovny
php --ri Říká, že rozšíření není přítomné Konfigurace PHP Prohlédněte si načtený php.ini a adresář pro skenování, přidejte správný záznam a restartujte proces
Sestavy PDO could not find driver Načítání PDO_SQLSRV nebo pořadí načítání PDO Potvrďte, že se PDO načítá jako první a že PDO_SQLSRV používá později načtený konfigurační soubor
CLI funguje, ale Apache, nginx nebo PHP-FPM selhávají Konfigurace specifická pro SAPI Porovnejte výstup CLI s phpinfo(), konfigurujte web SAPI a restartujte ho
Prohlížeč vrací HTTP 502 v nginx Směrování nginx do PHP-FPM Zkontrolujte fastcgi_pass socket vůči nainstalované verzi PHP-FPM a potvrďte, že služba běží
Ukázka v prohlížeči hlásí chybějící hodnoty prostředí Prostředí webového serveru nebo PHP-FPM Nakonfigurujte proměnné pro vybrané webové běhové prostředí a pak ho restartujte
Rozšíření se načtou, ale připojení selže ODBC, síť, certifikát, ověřování nebo SQL produkt Přečtěte si SQLSTATE a nativní chybu ze serverového logu; nepřestavujte rozšíření, pokud chyba identifikuje načítání nebo binární kompatibilitu

Odstraňte dočasnou testovací konfiguraci

Po ověření:

  1. Smažte testsql.php, verify-php-drivers.php, a jakoukoli dočasnou phpinfo() stránku z kořene dokumentu.

  2. Odstraňte dočasné ověřovací údaje a položky předávání proměnných prostředí.

  3. Když změníte override systemd, znovu načtěte správce služeb a pak restartujte PHP-FPM nebo webový server.

  4. Uchovejte si záznamy rozšíření a nainstalované balíčky, které aplikace vyžaduje.

Související obsah

  • Poslední aktualizace v