Installeer de Microsoft-drivers voor PHP op Linux en macOS

Deze instructies installeren PHP, de Microsoft ODBC-driver voor SQL Server, en de extensies SQLSRV en PDO_SQLSRV. Elke tab gebruikt het PHP-pakket dat door de repository wordt geleverd waaruit dat tabblad wordt geïnstalleerd, dus de versie in de commando's verschilt van tabblad tot tabblad. Vervang het door een andere PHP-versie die in de ondersteuningsmatrix staat als die repository een andere biedt.

De SQLSRV- en PDO_SQLSRV-drivers gebruiken dezelfde ODBC-afhankelijkheid en kunnen onafhankelijk worden geïnstalleerd. Installeer beide extensies als je applicatie beide drivers gebruikt.

Aan het einde van de procedure zouden de CLI en de geselecteerde webserver-runtime beide extensies moeten laden, beide PHP-API's beschikbaar moeten zijn, en het voorbeeld voor elke API zou de databaseserverversie moeten teruggeven.

Voordat u begint

  1. Kies een PHP-versie die wordt ondersteund door de huidige driverrelease en beschikbaar is voor je besturingssysteemrelease.

  2. Bepaal welke PHP-runtimes je nodig hebt:

    • CLI voor scripts, geplande taken of workers.
    • Apache-module voor door Apache gehoste PHP.
    • PHP-FPM voor nginx of een Apache FastCGI-configuratie.

  3. Bevestig de besturingssysteemarchitectuur. Uitgebrachte Linux-archieven bevatten x64-binaries en uitgebrachte macOS-archieven bevatten Arm64-binairen. PIE compileert voor de PHP-installatie op de computer en is het primaire installatiepad in dit artikel.

  4. Installeer de Microsoft ODBC-driver en het unixODBC-ontwikkelpakket. Het Microsoft-pakket verzorgt de databasecommunicatie. Het unixODBC-pakket levert headers die nodig zijn om SQLSRV en PDO_SQLSRV te bouwen.

  5. Plan om elke webserver, PHP-FPM pool en langlopende worker opnieuw te starten na het installeren of wijzigen van een extensie.

De platformpakketbeheerder installeert PHP en native vereisten. PIE bouwt en installeert de PHP-extensies. PHP-configuratie bepaalt of elke runtime ze laadt. De ODBC-driver verzorgt de databasecommunicatie en encryptie nadat de extensie is geladen.

Installeer de drivers met PIE

PIE, de PHP Installer for Extensions, is het ondersteunde extensie-installatieprogramma voor de huidige driverversies. Het vervangt de verouderde PHP Extension Community Library (PECL) workflow.

Voltooi de platformvereisten in de volgende secties voordat je de drivers installeert. Installeer vervolgens PIE en elke driver apart:

Installeer PIE

PIE draait op PHP 8.1 en latere versies. Het kan een extensie installeren in een andere PHP-installatie wanneer je de ontwikkeltools van die installatie selecteert.

Installeer curl en de GitHub CLI voordat je verder gaat. De platformsecties bevatten curl, dat mogelijk niet in een minimale installatie is opgenomen.

Download het PIE PHP-archief (PHAR) en verifieer het met de GitHub-commandoregelinterface (CLI) voordat je het installeert of uitvoert:

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"

Ga alleen door als de verificatie slaagt:

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

De tijdelijke directory is privé voor je account. Als download of verificatie faalt, installeer of start dan de PHAR niet. Verwijder het tijdelijke bestand en de map voordat je het opnieuw probeert.

Bevestig dat de geïnstalleerde PHAR draait met het PHP-uitvoerbare bestand dat je wilt gebruiken:

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

Installeer de SQLSRV- en PDO_SQLSRV-stuurprogramma's

Op Linux en macOS controleert PIE of de compiler en PHP-ontwikkeltools aanwezig zijn die het nodig heeft. Installeer het platform ODBC-ontwikkelingspakket en een C++-compiler voordat je PIE uitvoert. Voer PIE uit vanaf een interactieve terminal. Het kan je sudo wachtwoord opvragen wanneer het toestemming nodig heeft om bestanden in systeemmappen te installeren.

PIE gebruikt de PHP-installatie waarmee het wordt aangeroepen. Voor een installatie met versie voeg je aan elk installatiecommando --with-php-config toe om de ontwikkeltools te selecteren. Gebruik bijvoorbeeld pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv wanneer het bedoelde gereedschap /usr/bin/php-config8.4 is. Pas dezelfde optie toe op microsoft/pdo_sqlsrv. Alpine gebruikt versiegebonden uitvoerbare namen; volg de Alpine-commando's in plaats van de niet-geversioneerde commando's in deze sectie.

Voer één commando uit voor elke extensie. Deze commando's gebruiken de standaard PHP-installatie van PIE:

pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

PIE probeert elke extensie in te schakelen via de PHP-configuratietools van het platform of een extension= invoer, en waarschuwt als dat niet lukt. PHP gebruikt een serverapplicatie-programmeerinterface (SAPI) voor elke uitvoeringsomgeving. Op Debian, Ubuntu en SUSE kunnen de configuraties van de commandoregel, Apache en PHP FastCGI Process Manager (PHP-FPM) verschillen. Een succesvolle installatie via de opdrachtregel bevestigt niet dat een webserver de drivers laadt.

Controleer php --ini voor de commandoregel. Beperk voordat je een tijdelijke phpinfo() pagina voor de webserver aanmaakt, de toegang tot diagnostische pagina's. Controleer het geladen configuratiebestand en de gescande .ini bestanden voor elke runtime. Als de vermeldingen ontbreken, volg dan de stuurprogramma's laden op Linux en macOS om ze in de juiste laadvolgorde toe te voegen. Herstart de webserver of PHP-FPM na configuratiewijzigingen. Red Hat deelt php.ini vaak tussen SAPI's, maar verifieer de actieve configuratie voordat men vertrouwt op één PIE-run.

Installeer op je platform

Selecteer je besturingssysteem en webserverconfiguratie. Voltooi de installatiestappen in dat tabblad en volg dan Testen van je installatie.

Installeren op Ubuntu

Opmerking

De volgende commando's gebruiken de packages.sury.org PHP-repository zodat je een ondersteunde PHP-versie kunt selecteren. Gebruik de officiële Microsoft-instructies om de ODBC-driver voor je Ubuntu-release te installeren.

Stap 1. PHP (Ubuntu) installeren

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

Stap 2. Vereisten installeren (Ubuntu)

Volg Installeer de Microsoft ODBC-driver voor SQL Server op Linux en installeer vervolgens de ontwikkelheaders.

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

Stap 3. Installeer de PHP-drivers voor Microsoft SQL Server met PIE (Ubuntu)

Volg Install the drivers with PIE en voeg --with-php-config=/usr/bin/php-config8.4 toe aan beide installatiecommando's. Controleer de configuratiebestanden voor de opdrachtregel met 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

Stap 4. Apache installeren en stuurprogramma laden configureren (Ubuntu)

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

Stap 5. Start Apache opnieuw en test het voorbeeldscript (Ubuntu)

sudo systemctl restart apache2

Zie Uw installatie testen aan het einde van dit document als u de installatie wilt testen.

Legacy PECL-installatie

PECL is verouderd voor de huidige driverversies. Gebruik PIE voor nieuwe installaties en upgrades. Als een bestaande deployment aan PECL is vastgepind, houd dan de pakketversies uitgelijnd met de PHP-runtime en plan een overstap naar PIE.

Test je installatie

Controleer de opdrachtregelruntime. Op Alpine vervang je php door php84. Voor een PHP-installatie met versie op een andere distributie, gebruik het bijbehorende uitvoerbare bestand.

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

Beide --ri commando's moeten module-informatie afdrukken waarin ook ExtensionVer is opgenomen. De lijst met modules moet aparte sqlsrv en pdo_sqlsrv regels bevatten.

Controleer voordat je een verbinding test beide PHP API-interfaces met behulp van 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);

Verwachte uitvoer:

SQLSRV: loaded
PDO_SQLSRV: loaded

Voor PHP-FPM of een webserver, beperk de toegang tot diagnostische pagina's voordat je een tijdelijke phpinfo() pagina aanmaakt. Bevestig het geladen configuratiebestand, extension_dir en beide driversecties. Herstart PHP-FPM of de webserver na het wijzigen van de configuratie of het vervangen van een extensie. Verwijder de pagina na verificatie.

Om een liveverbinding te testen, maak je een bestand met de naam testsql.php in de documentwortel van je systeem. Dit pad bevindt zich /var/www/html op Ubuntu, Debian en Red Hat, /srv/www/htdocs op SUSE, /var/www/localhost/htdocs op Alpine of $(brew --prefix)/var/www in macOS. Stel de SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, en SQL_PWD omgevingsvariabelen in voor het PHP-proces voordat je het script uitvoert. Hardcode inloggegevens niet in een bestand onder de documentroot.

Voor een commandoregeltest gebruik je de interactieve prompts om de omgevingsvariabelen in te stellen zonder een wachtwoord in de shellgeschiedenis in te voeren.

Voor een Apache-moduletest moet je inloggegevens buiten het algemeen leesbare configuratiebestand van de site houden:

  1. Maak een privébestand aan buiten de documentroot. Gebruik een ongebruikte bestandsnaam in de configuratiemap van Apache. Op Linux:

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

    Vervang op Red Hat /etc/apache2 door /etc/httpd. Op macOS maak je het bestand aan als het account dat Homebrew's Apache start:

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

    Alleen de bestandseigenaar en root kunnen deze instellingen lezen. Het account dat Apache start, moet het bestand kunnen lezen.

  2. Bewerk het privébestand in een teksteditor en voeg deze vermeldingen toe:

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

    Binnen de argumenten tussen dubbele aanhalingstekens schrijf je \\ voor elke letterlijke backslash en \" voor elke letterlijke dubbele quote. Behoud de voor- en achterliggende spaties binnen de aanhalingstekens. Apache vervangt ook ${NAME}-verwijzingen. Als een waarde die reeks of regelafbreking bevat, gebruik dan in plaats daarvan de commandoregeltest. Voor meer informatie, zie Apache-configuratie citeren en escapen.

  3. Voeg binnen de virtuele host van de site een Files-blok toe dat het privébestand alleen voor testsql.php insluit. Als er geen virtuele host is geconfigureerd, plaats het blok dan in de hoofdserverconfiguratie. Vervang de ადგილიaanduiding door het absolute pad van het privébestand:

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

  4. Herstart Apache. Na het testen verwijder je het Files blok dat je hebt toegevoegd, verwijder je het privébestand en start je Apache opnieuw. Houd de instellingen voor niet-gerelateerde sites.

PHP-FPM verwijdert standaard geërfde omgevingsvariabelen, en nginx geeft zijn omgeving niet door aan PHP-FPM. Gebruik de volgende Ubuntu- of Red Hat-procedure alleen met een geïsoleerde test PHP-FPM service en pool. Voeg geen testgegevens toe aan een service of pool die andere applicaties draait: elk script in die pool kan ze lezen. Als je shared hosting gebruikt, gebruik dan in plaats daarvan de commandoregeltest.

  1. Maak een root-owned bestand aan buiten de documentwortel, zoals /etc/php-sql-driver-test.env, en beperk de toegang ertoe:

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

    Voeg de verbindingsinstellingen toe aan het bestand:

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

    Houd elke instelling op één regel. Schrijf binnen de dubbele aanhalingstekens \\ voor elke letterlijke backslash en \" voor elke letterlijke dubbele quote. Dollartekens en backticks worden niet geëvalueerd als shell-expressies. Bewerk het bestand direct in plaats van het in een shell te draaien of te sourcen. Zie systemd EnvironmentFile-syntaxis voor meer informatie.

  2. Voer sudo systemctl edit php8.4-fpm uit op Ubuntu of sudo systemctl edit php-fpm op Red Hat. Voeg deze systemd override toe:

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

  3. Voeg deze vermeldingen toe aan de configuratie van de actieve PHP-FPM pool. Algemene locaties zijn /etc/php/8.4/fpm/pool.d/www.conf op Ubuntu en /etc/php-fpm.d/www.conf op Red Hat:

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

  4. Herlaad systemd en herstart de toepasselijke PHP-FPM-service:

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

    Vervang op Red Hat php8.4-fpm door php-fpm.

Na het testen verwijder je het tijdelijke omgevingsbestand, de EnvironmentFile= invoer die je hebt toegevoegd, de testpool-vermeldingen en testsql.php. Verwijder het service override-bestand alleen als je het voor deze test hebt aangemaakt en het bevat geen andere instellingen. Houd alle bestaande overrides en poolinstellingen. Herlaad systemd en start PHP-FPM opnieuw na het verwijderen van de testconfiguratie.

SQLSRV-voorbeeld

Houd de omgevingswaarden ongewijzigd. Elk voorbeeld wijst ontbrekende of lege instellingen af voordat er verbinding wordt gemaakt. Elk voorbeeld verdubbelt vervolgens sluitende beugels en voegt buitenste beugels toe voordat de databasenaam, gebruikersnaam en wachtwoord aan het stuurprogramma worden doorgegeven. Deze codering behoudt letterlijke accolades en voorkomt dat puntkomma's verbindingsopties scheiden.

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

PDO_SQLSRV voorbeeld

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

Wijs uw browser aan http://localhost/testsql.php (http://localhost:8080/testsql.php in macOS). Een succesvolle verbinding toont de versiestring van de databaseserver. Beide voorbeelden schrijven foutdetails in het PHP-foutlogboek. Als de pagina een fout vertoont, controleer dan dat logboek.

Om het gedrag van de commandoregel en webserver te vergelijken, stel je dezelfde omgevingsvariabelen in voor je terminal en voer je het volgende uit:

php testsql.php

Als het uitvoeren via de opdrachtregel lukt maar er niets in je browser verschijnt, controleer dan de Apache-logbestanden. Voor meer hulp, zie Supportbronnen voor de PHP SQL-driver.

Evalueer de verbindingsprogramma’s afzonderlijk voor SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, SQL database in Microsoft Fabric en Warehouse in Microsoft Fabric. De geselecteerde authenticatiemethode, verbindingsopties en query moeten door het doel worden ondersteund. De installatie is client-side. Een succesvolle extensiecontrole bewijst niet dat een doelsysteem de inloggegevens accepteert, de client vertrouwt of elke databasefunctie ondersteunt.

Problemen met de installatie oplossen

Symptom Eigenaarslaag Corrigerende actie
PIE kan php-config, phpize of headers niet vinden PHP-ontwikkelingspakketten Installeer het ontwikkelpakket voor de doelversie van PHP en geef de matching-optie --with-php-config door
Compilatie faalt omdat er een C++-compiler ontbreekt Buildtools voor besturingssystemen Installeer het platform C++ compilerpakket, zoals g++ of gcc-c++
Compilatie kan sql.h niet vinden ODBC-ontwikkelingspakket- of compilerpaden Installeer unixodbc-dev of unixODBC-devel; op Apple Silicon, stel de Homebrew include- en bibliotheekvlaggen in
php --ri zegt dat de extensie niet aanwezig is PHP-configuratie Controleer de geladen php.ini en scanmap, voeg de juiste invoer toe en herstart het proces
PDO meldt could not find driver PDO_SQLSRV laden of de laadvolgorde van PDO Bevestig dat PDO eerst laadt en PDO_SQLSRV een later gescand configuratiebestand gebruikt
CLI werkt, maar Apache, nginx of PHP-FPM faalt. SAPI-specifieke configuratie Vergelijk de CLI-uitvoer met phpinfo(), configureer de web-SAPI en start deze opnieuw op
De browser geeft HTTP 502 terug via nginx nginx naar PHP-FPM routering Controleer de fastcgi_pass socket aan de hand van de geïnstalleerde PHP-FPM versie en bevestig dat de service draait
Het browservoorbeeld rapporteert ontbrekende omgevingswaarden Web-server- of PHP-FPM-omgeving Configureer de variabelen voor de geselecteerde webruntime en start deze vervolgens opnieuw
Extensies laden maar een verbinding mislukt ODBC, netwerk, certificaat, authenticatie of SQL-product Lees de SQLSTATE en de native fout uit het serverlog; bouw de extensie niet opnieuw op tenzij de fout wijst op een laadprobleem of binaire incompatibiliteit

Tijdelijke testconfiguratie verwijderen

Na verificatie:

  1. Verwijder testsql.php, verify-php-drivers.php, en elke tijdelijke phpinfo() pagina uit de documentwortel.

  2. Verwijder tijdelijke inloggegevens en vermeldingen voor het doorsturen van omgevingsvariabelen.

  3. Laad de servicemanager opnieuw wanneer je een systemd-override verandert, en herstart dan PHP-FPM of de webserver.

  4. Bewaar de extensie-entries en geïnstalleerde pakketten die de applicatie vereist.

Verwante inhoud

  • Laatst bijgewerkt om