Installera Microsoft-drivrutinerna för PHP på Linux och macOS

Dessa instruktioner installerar PHP, den Microsoft ODBC-drivrutinen för SQL Server, samt SQLSRV- och PDO_SQLSRV-tilläggen. Varje flik använder PHP-paketet som tillhandahålls av det repo som fliken installeras från, så versionen i kommandona skiljer sig från en flik till nästa. Byt ut den mot en annan PHP-version som finns med i supportmatrisen om det arkivet erbjuder en annan.

SQLSRV- och PDO_SQLSRV drivrutinerna använder samma ODBC-beroende och kan installeras oberoende. Installera båda tilläggen om din applikation använder båda drivrutinerna.

I slutet av proceduren ska CLI:n och den valda webbserverns runtime ladda båda tilläggen, båda PHP-API:erna ska vara tillgängliga och exemplet för varje API ska returnera databasserverversionen.

Innan du börjar

  1. Välj en PHP-version som stöds av den aktuella drivrutinsversionen och som finns tillgänglig för din operativsystemversion.

  2. Bestäm vilka PHP-runtimes du behöver:

    • CLI för skript, schemalagda uppgifter eller worker-processer.
    • Apache-modul för Apache-hostad PHP.
    • PHP-FPM för nginx eller en Apache FastCGI-konfiguration.

  3. Bekräfta operativsystemets arkitektur. Släppta Linux-arkiv innehåller x64-binärfiler och släppta macOS-arkiv innehåller Arm64-binärfiler. PIE skapar paket för PHP-installationen på datorn och är den primära installationsvägen i denna artikel.

  4. Installera Microsoft ODBC-drivrutinen och utvecklingspaketet unixODBC. Microsoft-paketet hanterar databaskommunikation. UnixODBC-paketet tillhandahåller headers som krävs för att bygga SQLSRV och PDO_SQLSRV.

  5. Planera att starta om varje webbserver, PHP-FPM-pool och långvarig bakgrundsprocess efter installation eller ändring av ett tillägg.

Plattformspakethanteraren installerar PHP och inbyggda förutsättningar. PIE bygger och installerar PHP-tilläggen. PHP-konfigurationen styr om varje runtime laddar dem. ODBC-drivrutinen hanterar databaskommunikation och kryptering efter att tillägget har laddats.

Installera drivrutinerna med PIE

PIE, PHP-installationsprogrammet för tillägg, är det tilläggsinstallationsprogram som stöds för aktuella drivrutinsversioner. Den ersätter det föråldrade arbetsflödet för PHP Extension Community Library (PECL).

Uppfyll plattformsförutsättningarna i följande avsnitt innan du installerar drivrutinerna. Installera sedan PIE och varje drivrutin separat:

Installera PIE

PIE körs på PHP 8.1 och senare versioner. Den kan installera ett tillägg i en annan PHP-installation när du väljer den installationens utvecklingsverktyg.

Installera curl och installera GitHub CLI innan du fortsätter. Plattformsavsnitten innehåller curl där en minimal installation kanske inte tillhandahåller det.

Ladda ner PIE PHP-arkivet (PHAR) och verifiera det med GitHub-kommandoradsgränssnittet (CLI) innan du installerar eller kör det:

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"

Fortsätt endast om verifieringen lyckas:

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

Den tillfälliga katalogen är privat för ditt konto. Om nedladdning eller verifiering misslyckas, installera eller kör inte PHAR. Ta bort den temporära filen och katalogen innan du försöker igen.

Bekräfta att den installerade PHAR körs med den PHP-körbara fil du tänker använda:

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

Installera SQLSRV- och PDO_SQLSRV drivrutinerna

På Linux och macOS kontrollerar PIE om kompilatorn och de PHP-utvecklingsverktyg som behövs finns. Installera plattformens ODBC-utvecklingspaket och en C++-kompilator innan du kör PIE. Kör PIE från en interaktiv terminal. Den kan begära ditt sudo lösenord när den behöver tillstånd för att installera filer i systemkataloger.

PIE använder PHP-installationen som används för att anropa det. För en versionerad installation, lägg till --with-php-config i varje installationskommando för att välja utvecklingsverktygen för den versionen. Till exempel, använd pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv när det avsedda verktyget är /usr/bin/php-config8.4. Använd samma alternativ för microsoft/pdo_sqlsrv. Alpine använder versionerade körbara namn; följ Alpine-kommandona istället för de oversionerade kommandona i denna sektion.

Kör ett kommando för varje tillägg. Dessa kommandon använder PIE:s standardinstallation av PHP:

pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

PIE försöker aktivera varje tillägg via plattformens PHP-konfigurationsverktyg eller en extension= post, och varnar om det inte går. PHP använder ett serverapplikationsprogrammeringsgränssnitt (SAPI) för varje exekveringsmiljö. På Debian, Ubuntu och SUSE kan kommandorads-, Apache- och PHP FastCGI Process Manager (PHP-FPM) konfigurationerna skilja sig åt. En lyckad kommandoradsinstallation bekräftar inte att en webbserver laddar drivrutinerna.

Se php --ini för kommandoraden. Innan du skapar en tillfällig phpinfo() sida för webbservern, begränsa åtkomsten till diagnostiska sidor. Kontrollera den laddade konfigurationsfilen och de skannade .ini filerna för varje körning. Om posterna saknas, följ Läsa in drivrutiner på Linux och macOS för att lägga till dem i rätt laddningsordning. Starta om webbservern eller PHP-FPM efter konfigurationsändringar. Red Hat delar php.ini ofta mellan SAPI:er, men verifiera den aktiva konfigurationen innan du förlitar dig på en PIE-körning.

Installera på din plattform

Välj ditt operativsystem och webbserverkonfiguration. Slutför installationsstegen på den fliken och följ sedan Testa din installation.

Installera på Ubuntu

Anmärkning

Följande kommandon använder packages.sury.org PHP-arkiv så att du kan välja en stödd PHP-version. Använd de officiella Microsoft-instruktionerna för att installera ODBC-drivrutinen för din Ubuntu-version.

Steg 1. Installera 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

Steg 2. Installera förutsättningar (Ubuntu)

Följ Installera Microsoft ODBC-drivrutinen för SQL Server på Linux och installera sedan utvecklingshuvuden.

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

Steg 3. Installera PHP-drivrutinerna för Microsoft SQL Server med PIE (Ubuntu)

Följ Installera drivrutinerna med PIE, lägg till --with-php-config=/usr/bin/php-config8.4 i båda installationskommandona. Kontrollera kommandoradskonfigurationsfilerna med 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

Steg 4. Installera Apache och konfigurera inläsning av drivrutiner (Ubuntu)

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

Steg 5. Starta om Apache och testa exempelskriptet (Ubuntu)

sudo systemctl restart apache2

Information om hur du testar installationen finns i Testa installationen i slutet av det här dokumentet.

äldre PECL-installation

PECL är utfasat för aktuella drivrutinsversioner. Använd PIE för nya installationer och uppgraderingar. Om en befintlig driftsättning är fastnålad till PECL, håll dess paketversioner anpassade till PHP-runtime och planera en övergång till PIE.

Testa din installation

Verifiera kommandoradens körmiljö. På Alpine, ersätt php med php84. För en versionshanterad PHP-installation på en annan distribution, använd dess motsvarande exekverbara fil.

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

Båda --ri kommandona ska skriva ut modulinformation som inkluderar ExtensionVer. Modullistan bör innehålla separata sqlsrv- och pdo_sqlsrv-rader.

Innan du testar en anslutning, verifiera båda PHP API-ytorna med 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);

Förväntat resultat:

SQLSRV: loaded
PDO_SQLSRV: loaded

För PHP-FPM eller en webbserver, begränsa åtkomsten till diagnostiksidan innan du skapar en tillfällig phpinfo() sida. Bekräfta den laddade konfigurationsfilen, extension_dir och båda drivrutinssektionerna. Starta om PHP-FPM eller webbservern efter att ha ändrat konfigurationen eller bytt ut ett tillägg. Ta bort sidan efter verifiering.

För att testa en live-anslutning, skapa en fil med namnet testsql.php i systemets dokumentrot. Den här sökvägen finns /var/www/html på Ubuntu, Debian och Red Hat, /srv/www/htdocs på SUSE, /var/www/localhost/htdocs på Alpine eller $(brew --prefix)/var/www på macOS. Ställ SQL_SERVER_NAMEin , SQL_DATABASE, SQL_UID, och SQL_PWD miljövariablerna för PHP-processen innan du kör skriptet. Hårdkoda inte inloggningsuppgifter i en fil under dokumentroten.

För ett kommandoradstest, använd de interaktiva promptarna för att sätta miljövariabler utan att ange lösenord i skalhistoriken.

För ett Apache-modultest, håll inloggningsuppgifterna utanför sajtens allmänt läsbara konfigurationsfil:

  1. Skapa en privat fil utanför dokumentroten. Använd ett oanvänt filnamn i Apaches konfigurationskatalog. På Linux:

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

    På Red Hat, ersätt /etc/apache2 med /etc/httpd. På macOS, skapa filen som det konto som startar Homebrew's Apache:

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

    Endast filägaren och rooten kan läsa dessa inställningar. Det konto som startar Apache måste kunna läsa filen.

  2. Redigera den privata filen i en textredigerare och lägg till dessa poster:

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

    Inom de dubbelciterade argumenten, skriv \\ för varje bokstavlig backslash och \" för varje bokstavlig dubbelcitat. Behåll ledande och efterföljande utrymmen inom citationstecknen. Apache ersätter också ${NAME}-referenser. Om ett värde innehåller den sekvensen eller ett radbryt, använd istället kommandoradstestet. För mer information, se Apache configuration quoting and escaping.

  3. Inne i sajtens virtuella värd, lägg till ett Files-block som endast inkluderar den privata filen för testsql.php. Om ingen virtuell värd är konfigurerad, placera blocket i huvudserverkonfigurationen. Byt ut platshållaren mot den privata filens absoluta bana:

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

  4. Starta om Apache. Efter test, ta bort blocket Files du lagt till, ta bort den privata filen och starta om Apache igen. Behåll inställningar för orelaterade webbplatser.

PHP-FPM rensar ärvda miljövariabler som standard, och nginx skickar inte sin miljö till PHP-FPM. Använd följande Ubuntu- eller Red Hat-procedur endast med en isolerad PHP-FPM-testtjänst och -pool. Lägg inte till testautentiseringsuppgifter i en tjänst eller pool som kör andra applikationer: varje skript i den poolen kan läsa dem. Om du använder delad hosting, använd kommandoradstestet istället.

  1. Skapa en rot-ägd fil utanför dokumentroten, såsom /etc/php-sql-driver-test.env, och begränsa åtkomsten till den:

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

    Lägg till anslutningsinställningarna i filen:

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

    Håll varje inställning på en rad. Inom de dubbla citattecknen, skriv \\ för varje bokstavligt omvänt snedstreck och \" för varje bokstavligt dubbelt citattecken. Dollartecken och backticks utvärderas inte som shell-uttryck. Redigera filen direkt istället för att köra eller sourca den i ett skal. För mer information, se systemd EnvironmentFile-syntax.

  2. Kör sudo systemctl edit php8.4-fpm på Ubuntu eller sudo systemctl edit php-fpm på Red Hat. Lägg till denna systemd-åsidosättning:

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

  3. Lägg till dessa poster i den aktiva PHP-FPM poolens konfiguration. Vanliga platser är /etc/php/8.4/fpm/pool.d/www.conf på Ubuntu och /etc/php-fpm.d/www.conf på 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. Ladda om systemd och starta om den aktuella PHP-FPM-tjänsten:

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

    På Red Hat, ersätt php8.4-fpm med php-fpm.

Efter testning, ta bort filen för den tillfälliga miljön, posten EnvironmentFile= du lade till, testpoolens poster och testsql.php. Ta bort tjänsteöverskrivningsfilen endast om du skapade den för detta test och den inte innehåller några andra inställningar. Behåll alla befintliga åsidosättningar och poolinställningar. Ladda om systemd och starta om PHP-FPM igen efter att ha tagit bort testkonfigurationen.

SQLSRV-exempel

Behåll miljövärdena oförändrade. Varje exempel avvisar saknade eller tomma inställningar innan den ansluter. Varje exempel dubblar sedan stängningsklamrarna och lägger till yttre klamrar innan det skickar databasnamnet, användarnamnet och lösenordet till drivrutinen. Denna kodning bevarar bokstavliga klamrar och förhindrar semikolon från att separera anslutningsalternativ.

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

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

Peka webbläsaren på http://localhost/testsql.php (http://localhost:8080/testsql.php på macOS). En lyckad anslutning visar databasserverns versionssträng. Båda exemplen skriver feldetaljer till PHP-felloggen. Om sidan visar ett fel, kontrollera loggen.

För att jämföra kommandorads- och webbserverbeteende, ställ in samma miljövariabler för din terminal och kör:

php testsql.php

Om det går att köra från kommandoraden men inget dyker upp i din webbläsare, kolla Apache-loggfilerna. För mer hjälp, se Supportresurser för PHP SQL-drivrutinen.

Utvärdera anslutningsprogrammen separat för SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, SQL Database i Microsoft Fabric och Warehouse i Microsoft Fabric. Den valda autentiseringsmetoden, anslutningsalternativen och frågeuttrycket måste stödjas av målsystemet. Installationen sker på klientsidan. En lyckad tilläggskontroll bevisar inte att ett mål accepterar inloggningsuppgifterna, litar på klienten eller stöder alla databasfunktioner.

Felsöka installationsproblem

Symtom Ägarlager Korrigeringsåtgärder
PIE kan inte hitta phpize, php-config, eller rubriker PHP-utvecklingspaket Installera utvecklingspaketet för målversionen av PHP och ange motsvarande alternativet --with-php-config
Kompilering misslyckas eftersom en C++-kompilator saknas Verktyg för operativsystemsbygge Installera plattformens C++-kompilatorpaket, såsom g++ eller gcc-c++
Kompileringen kan inte hitta sql.h ODBC-utvecklingspaket eller kompilatorvägar Installera unixODBC-devel eller unixodbc-dev; på Apple silicon, ställ in Homebrews include- och biblioteksflaggor
php --ri säger att tillägget inte finns PHP-konfiguration Inspektera den inlästa katalogen php.ini och skanna katalogen, lägg till rätt post och starta om processen
PDO-rapporter could not find driver PDO_SQLSRV inläsning eller PDO-inläsningsordning Bekräfta att PDO laddas först och PDO_SQLSRV använder en senare skannad konfigurationsfil
CLI fungerar men Apache, nginx eller PHP-FPM fungerar inte SAPI-specifik konfiguration Jämför CLI-utdata med phpinfo(), konfigurera webb-SAPI:n och starta om den
Webbläsaren returnerar HTTP 502 via nginx nginx till PHP-FPM routning Kontrollera socketen fastcgi_pass mot den installerade PHP-FPM-versionen och bekräfta att tjänsten körs
Webbläsarexemplet rapporterar saknade miljövärden Webbserver eller PHP-FPM-miljö Konfigurera variablerna för den valda webbruntimen och starta sedan om den
Tillägg laddas men en anslutning misslyckas ODBC, nätverksprodukt, certifikatprodukt, autentiseringsprodukt eller SQL-produkt Läs SQLSTATE och det nativa felet från serverloggen; bygg inte om tillägget om inte felet visar på laddning eller binärkompatibilitet

Ta bort den tillfälliga testkonfigurationen

Efter verifiering:

  1. Ta bort testsql.php, verify-php-drivers.php, och alla tillfälliga phpinfo() sidor från dokumentroten.

  2. Ta bort tillfälliga inloggningsuppgifter och poster för vidarebefordran av miljövariabler.

  3. Ladda om servicehanteraren när du ändrar en systemd-överskrivning, och starta sedan om PHP-FPM eller webbservern.

  4. Behåll tilläggsposterna och installerade paket som applikationen kräver.

Relaterat innehåll

  • Uppdaterades senast