Microsoft Drivers for PHP for SQL Server 的 Linux 和 macOS 安裝教學課程

下列指示假設一個全新的環境,並示範如何在 Ubuntu、Red Hat、Debian、SUSE、Alpine 和 macOS 上安裝 PHP 8.1、Microsoft ODBC 驅動程式、Apache Web 伺服器,以及 Microsoft Drivers for PHP for SQL Server。 這些指示建議使用 PECL 安裝驅動程式,但您也可以從 Microsoft Drivers for PHP for SQL Server \(英文\) GitHub 專案頁面中下載預先建置的二進位檔,並遵循載入 Microsoft Drivers for PHP for SQL Server 中的指示進行安裝。 如需載入延伸模組以及我們未將延伸模組新增至 php.ini 的原因說明,請參閱關於載入驅動程式的小節。

如果 PHP 8.1 套件可供使用,下列指示預設會使用 pecl install 來安裝 PHP 8.1。 您可能需要先執行 pecl channel-update pecl.php.net。 部分支援的 Linux 發行版本會預設為 PHP 7.1 或更早版本,但適用於 SQL Server 的最新版 PHP 驅動程式並不支援這些版本。 請參閱每節開頭的注意事項以改為安裝 PHP 8.2 或 8.3。

同時包含在 Ubuntu 上安裝 PHP FastCGI Process Manager (PHP-FPM) 的指示。 如果您使用 nginx Web 伺服器而非 Apache,便需要 PHP-FPM。

雖然這些指示包含同時安裝 SQLSRV 和 PDO_SQLSRV 驅動程式的命令,但您也可以可以獨立安裝及運作驅動程式。 使用者若熟悉如何自訂其設定,可以將這些指示調整為特定於 SQLSRV 或 PDO_SQLSRV。 這兩個驅動程式具有相同的相依性,但下列所述除外。

如需最新的支援作業系統版本,請參閱支援矩陣

注意

請確定您已安裝最新版的 ODBC 驅動程式,以確保最佳的效能和安全性。 如需安裝指示,請參閱安裝 Microsoft ODBC Driver for SQL Server (Linux)安裝 Microsoft ODBC Driver for SQL Server (macOS)

安裝在 Ubuntu 上

注意

若要安裝 PHP 8.2 或 8.3,請在下列命令中使用 8.2 或 8.3 來取代 8.1。

步驟 1: 安裝 PHP (Ubuntu)

sudo su
add-apt-repository ppa:ondrej/php -y
apt-get update
apt-get install php8.1 php8.1-dev php8.1-xml -y --allow-unauthenticated

步驟 2: 安裝必要條件 (Ubuntu)

遵循安裝 Microsoft ODBC Driver for SQL Server (Linux) 上的指示來安裝 ODBC Driver for Ubuntu。 請務必也安裝 unixodbc-dev 套件。 pecl 命令會使用此套件來安裝 PHP 驅動程式。

sudo apt-get install unixodbc-dev

步驟 3: 安裝適用於 Microsoft SQL Server 的 PHP 驅動程式 (Ubuntu)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/8.1/mods-available/sqlsrv.ini
printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/8.1/mods-available/pdo_sqlsrv.ini
exit
sudo phpenmod -v 8.1 sqlsrv pdo_sqlsrv

如果系統中只有單一 PHP 版本,則最後的步驟可以簡化為 phpenmod sqlsrv pdo_sqlsrv

步驟 4: 安裝 Apache 並設定驅動程式載入 (Ubuntu)

sudo su
apt-get install libapache2-mod-php8.1 apache2
a2dismod mpm_event
a2enmod mpm_prefork
a2enmod php8.1
exit

步驟 5: 重新啟動 Apache 並測試範例指令碼 (Ubuntu)

sudo service apache2 restart

若要測試安裝,請參閱本文件結尾的測試您的安裝

使用 PHP-FPM 在 Ubuntu 上進行安裝

注意

若要安裝 PHP 8.2 或 8.3,請在下列命令中使用 8.2 或 8.3 來取代 8.1。

步驟 1: 安裝 PHP (Ubuntu 搭配 PHP-FPM)

sudo su
add-apt-repository ppa:ondrej/php -y
apt-get update
apt-get install php8.1 php8.1-dev php8.1-fpm php8.1-xml -y --allow-unauthenticated

透過執行下列內容來確認 PHP-FPM 服務的狀態:

systemctl status php8.1-fpm

步驟 2: 安裝必要條件 (Ubuntu 搭配 PHP-FPM)

遵循安裝 Microsoft ODBC Driver for SQL Server (Linux) 上的指示來安裝 ODBC Driver for Ubuntu。 請務必也安裝 unixodbc-dev 套件。 pecl 命令會使用此套件來安裝 PHP 驅動程式。

步驟 3: 安裝適用於 Microsoft SQL Server 的 PHP 驅動程式 (Ubuntu 搭配 PHP-FPM)

sudo pecl config-set php_ini /etc/php/8.1/fpm/php.ini
sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/8.1/mods-available/sqlsrv.ini
printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/8.1/mods-available/pdo_sqlsrv.ini
exit
sudo phpenmod -v 8.1 sqlsrv pdo_sqlsrv

如果系統中只有單一 PHP 版本,則最後的步驟可以簡化為 phpenmod sqlsrv pdo_sqlsrv

確認 sqlsrv.inipdo_sqlsrv.ini 皆位於 /etc/php/8.1/fpm/conf.d/ 中:

ls /etc/php/8.1/fpm/conf.d/*sqlsrv.ini

重新啟動 PHP-FPM 服務:

sudo systemctl restart php8.1-fpm

步驟 4: 安裝和設定 nginx (Ubuntu 搭配 PHP-FPM)

sudo apt-get update
sudo apt-get install nginx
sudo systemctl status nginx

若要設定 nginx,您必須編輯 /etc/nginx/sites-available/default 檔案。 將 index.php 新增至下列清單中顯示 # Add index.php to the list if you are using PHP 的區段:

# Add index.php to the list if you are using PHP
index index.html index.htm index.nginx-debian.html index.php;

接下來,請以如下方式將 # pass PHP scripts to FastCGI server 後面的區段取消註解並進行修改:

# pass PHP scripts to FastCGI server
#
location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
}

步驟 5: 重新啟動 nginx 並測試範例指令碼 (Ubuntu 搭配 PHP-FPM)

sudo systemctl restart nginx.service

若要測試安裝,請參閱本文件結尾的測試您的安裝

在 Red Hat 上進行安裝

步驟 1: 安裝 PHP (Red Hat)

若要在 Red Hat 7 上安裝 PHP,請執行下列命令:

注意

若要安裝 PHP 8.2 或 8.3,請在下列命令中分別使用 remi-php82 或 remi-php83 來取代 remi-php81。

sudo su
yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum install https://rpms.remirepo.net/enterprise/remi-release-7.rpm
subscription-manager repos --enable=rhel-7-server-optional-rpms
yum install yum-utils
yum-config-manager --enable remi-php81
yum update
# Note: The php-pdo package is required only for the PDO_SQLSRV driver
yum install php php-pdo php-pear php-devel

若要在 Red Hat 8 上安裝 PHP,請執行下列命令:

注意

若要安裝 PHP 8.2 或 8.3,請在下列命令中分別使用 remi-8.2 或 remi-8.3 來取代 remi-8.1。

sudo su
dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
dnf install https://rpms.remirepo.net/enterprise/remi-release-8.rpm
dnf install yum-utils
dnf module reset php
dnf module install php:remi-8.1
subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms
dnf update
# Note: The php-pdo package is required only for the PDO_SQLSRV driver
dnf install php-pdo php-pear php-devel

步驟 2: 安裝必要條件 (Red Hat)

遵循安裝 Microsoft ODBC Driver for SQL Server (Linux) 上的指示來安裝 ODBC Driver for Red Hat 7 或 8。 請務必也安裝 unixodbc-dev 套件。 pecl 命令會使用此套件來安裝 PHP 驅動程式。

步驟 3: 安裝適用於 Microsoft SQL Server 的 PHP 驅動程式 (Red Hat)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
echo extension=pdo_sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/30-pdo_sqlsrv.ini
echo extension=sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/20-sqlsrv.ini
exit

或者,您也可以從 Remi 存放庫安裝:

sudo yum install php-sqlsrv

步驟 4: 安裝 Apache (Red Hat)

sudo yum install httpd

預設會安裝 SELinux,並以強制模式執行。 若要允許 Apache 透過 SELinux 連線到資料庫,請執行下列命令:

sudo setsebool -P httpd_can_network_connect_db 1

步驟 5。 重新啟動 Apache 並測試範例指令碼 (Red Hat)

sudo apachectl restart

若要測試安裝,請參閱本文件結尾的測試您的安裝

安裝在 Debian 上

注意

若要安裝 PHP 8.2 或 8.3,請在下列命令中使用 8.2 或 8.3 來取代 8.1。

步驟 1: 安裝 PHP (Debian)

sudo su
apt-get install curl apt-transport-https
wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list
apt-get update
apt-get install -y php8.1 php8.1-dev php8.1-xml php8.1-intl

步驟 2: 安裝必要條件 (Debian)

遵循安裝 Microsoft ODBC Driver for SQL Server (Linux) 上的指示來安裝 ODBC Driver for Debian。 請務必也安裝 unixodbc-dev 套件。 pecl 命令會使用此套件來安裝 PHP 驅動程式。

此外,您可能也需要產生正確的地區設定,以取得要在瀏覽器中正確顯示的 PHP 輸出。 例如,針對 en_US UTF-8 地區設定,執行下列命令:

sudo su
sed -i 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/g' /etc/locale.gen
locale-gen

您可能需要將 /usr/sbin 新增到您的 $PATH,因為 locale-gen 可執行檔位於這裡。

步驟 3: 安裝適用於 Microsoft SQL Server 的 PHP 驅動程式 (Debian)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/8.1/mods-available/sqlsrv.ini
printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/8.1/mods-available/pdo_sqlsrv.ini
exit
sudo phpenmod -v 8.1 sqlsrv pdo_sqlsrv

如果系統中只有單一 PHP 版本,則最後的步驟可以簡化為 phpenmod sqlsrv pdo_sqlsrv。 和 locale-gen 相同,由於 phpenmod 位於 /usr/sbin 中,因此您可能需要將此目錄新增到您的 $PATH

步驟 4: 安裝 Apache 並設定驅動程式載入 (Debian)

sudo su
apt-get install libapache2-mod-php8.1 apache2
a2dismod mpm_event
a2enmod mpm_prefork
a2enmod php8.1

步驟 5: 重新啟動 Apache 並測試範例指令碼 (Debian)

sudo service apache2 restart

若要測試安裝,請參閱本文件結尾的測試您的安裝

在 SUSE 上進行安裝

注意

在下列指示中,使用您的 SUSE 版本來取代 <SuseVersion>;如果您要使用 SUSE Linux Enterprise Server 15,則其將是 SLE_15_SP3 或 SLE_15_SP4 (或更新版本)。 若為 SUSE 12,請使用 SLE_12_SP5 (或更新版本)。 並非所有 PHP 版本都可供適用於 SUSE Linux 的所有版本使用,請參閱 http://download.opensuse.org/repositories/devel:/languages:/php 以查看哪些版本的 SUSE 具有可用的預設版本 PHP,或參閱 http://download.opensuse.org/repositories/devel:/languages:/php:/ 以查看哪些其他版本的 PHP 可供哪些版本的 SUSE 使用。

注意

到目前為止,PHP 7.4 或更新版本的套件仍不適用於 SUSE 12。

步驟 1: 安裝 PHP (SUSE)

sudo su
zypper -n ar -f https://download.opensuse.org/repositories/devel:languages:php/<SuseVersion>/devel:languages:php.repo
zypper --gpg-auto-import-keys refresh
zypper -n install php8 php8-pdo php8-devel php8-openssl

步驟 2: 安裝必要條件 (SUSE)

遵循安裝 Microsoft ODBC Driver for SQL Server (Linux) 上的指示來安裝 ODBC Driver for SUSE。 請務必也安裝 unixodbc-dev 套件。 pecl 命令會使用此套件來安裝 PHP 驅動程式。

步驟 3: 安裝適用於 Microsoft SQL Server 的 PHP 驅動程式 (SUSE)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
echo extension=pdo_sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/pdo_sqlsrv.ini
echo extension=sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/sqlsrv.ini
exit

步驟 4: 安裝 Apache 並設定驅動程式載入 (SUSE)

sudo su
zypper install apache2 apache2-mod_php8
a2enmod php8
echo "extension=sqlsrv.so" >> /etc/php8/apache2/php.ini
echo "extension=pdo_sqlsrv.so" >> /etc/php8/apache2/php.ini
exit

步驟 5: 重新啟動 Apache 並測試範例指令碼 (SUSE)

sudo systemctl restart apache2

若要測試安裝,請參閱本文件結尾的測試您的安裝

安裝在 Alpine 上

注意

PHP 8.1 或更新版本可從 Alpine 的測試或邊緣存放庫取得。 您可以改為從來源編譯 PHP。

步驟 1: 安裝 PHP (Alpine)

適用於 Alpine 的 PHP 套件可以在 edge/community 存放庫中找到。 請在其 WIKI 頁面上查看 Enable Community Repository (啟用社群存放庫)。 將下列行新增至 /etc/apk/repositories,並以 Alpine 存放庫鏡像的 URL 取代 <mirror>

http://<mirror>/alpine/edge/community

然後執行:

sudo su
apk update
# Note: The php*-pdo package is required only for the PDO_SQLSRV driver
# For PHP 7.*
apk add php7 php7-dev php7-pear php7-pdo php7-openssl autoconf make g++
# For PHP 8.*
apk add php8 php8-dev php8-pear php8-pdo php8-openssl autoconf make g++
# The following symbolic links are optional but useful
ln -s /usr/bin/php8 /usr/bin/php
ln -s /usr/bin/phpize8 /usr/bin/phpize
ln -s /usr/bin/pecl8 /usr/bin/pecl
ln -s /usr/bin/php-config8 /usr/bin/php-config

步驟 2: 安裝必要條件 (Alpine)

遵循安裝 Microsoft ODBC Driver for SQL Server (Linux) 上的指示來安裝 ODBC Driver for Alpine。 請務必也安裝 unixodbc-dev 套件 (sudo apk add unixodbc-dev)。 pecl 命令會使用此套件來安裝 PHP 驅動程式。

步驟 3: 安裝適用於 Microsoft SQL Server 的 PHP 驅動程式 (Alpine)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
echo extension=pdo_sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/10_pdo_sqlsrv.ini
echo extension=sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/20_sqlsrv.ini

步驟 4: 安裝 Apache 並設定驅動程式載入 (Alpine)

# For PHP 7.*
sudo apk add php7-apache2 apache2
# For PHP 8.*
sudo apk add php8-apache2 apache2

步驟 5: 重新啟動 Apache 並測試範例指令碼 (Alpine)

sudo rc-service apache2 restart

若要測試安裝,請參閱本文件結尾的測試您的安裝

在 macOS 上進行安裝

如果您尚未安裝,請以如下方式安裝 brew:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

注意

若要安裝 PHP 8.2 或 8.3,請在下列命令中分別使用 php@8.2 或 php@8.3 來取代 php@8.1。

步驟 1: 安裝 PHP (macOS)

brew tap
brew tap homebrew/core
brew install php@8.1

PHP 現在應該位於您的路徑中。 執行 php -v 以確認正在執行正確的 PHP 版本。 如果 PHP 不在您的路徑中或不是正確版本,請執行下列命令:

brew link --force --overwrite php@8.1

如果使用 Apple M1 ARM64,您可能需要設定路徑:

export PATH="/opt/homebrew/bin:$PATH"

步驟 2: 安裝必要條件 (macOS)

遵循安裝 Microsoft ODBC Driver for SQL Server (macOS) 上的指示來安裝 ODBC Driver for macOS。

注意

如果使用 Apple M1 ARM64 硬體,請直接安裝 Microsoft ODBC Driver 17.8+,而不要使用模擬器 Rosetta 2。

此外,您可能需要安裝 GNU 製作工具:

brew install autoconf automake libtool

步驟 3: 安裝適用於 Microsoft SQL Server 的 PHP 驅動程式 (macOS)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv

如果使用 Apple M1 ARM64,請改為執行下列命令:

sudo CXXFLAGS="-I/opt/homebrew/opt/unixodbc/include/" LDFLAGS="-L/opt/homebrew/lib/" pecl install sqlsrv
sudo CXXFLAGS="-I/opt/homebrew/opt/unixodbc/include/" LDFLAGS="-L/opt/homebrew/lib/" pecl install pdo_sqlsrv

步驟 4: 安裝 Apache 並設定驅動程式載入 (macOS)

注意

最新的 macOS 11.0 Big Sur 已預先安裝 Apache 2.4,但 Apple 也移除了一些必要指令碼。 此解決方案是透過 Homebrew 安裝 Apache 2.4,然後進行設定,但此操作不在本安裝指南的涵蓋範圍內,因此請查看 Apache 或 Homebrew 以取得詳細指示。

brew install apache2

若要尋找 Apache 設定檔 (httpd.conf) 以進行 Apache 安裝,請執行:

/usr/local/bin/apachectl -V | grep SERVER_CONFIG_FILE

下列命令會將必要的設定附加到 httpd.conf。 請務必將 /usr/local/etc/httpd/httpd.conf 取代為上述命令所傳回的路徑:

echo "LoadModule php7_module /usr/local/opt/php@8.1/lib/httpd/modules/libphp7.so" >> /usr/local/etc/httpd/httpd.conf
(echo "<FilesMatch .php$>"; echo "SetHandler application/x-httpd-php"; echo "</FilesMatch>";) >> /usr/local/etc/httpd/httpd.conf

步驟 5。 重新啟動 Apache 並測試範例指令碼 (macOS)

sudo apachectl restart

若要測試安裝,請參閱本文件結尾的測試您的安裝

測試您的安裝

若要測試此範例指令碼,在系統的文件根目錄中建立名為 testsql.php 的檔案。 此路徑在 Ubuntu、Debian 和 Red Hat 上為 /var/www/html/、在 SUSE 上為 /srv/www/htdocs、在 Alpine 上為 /var/www/localhost/htdocs,或是在 macOS 上為 /usr/local/var/www。 將下列指令碼複製到其中,適當地取代伺服器、資料庫、使用者名稱和密碼。

SQLSRV 範例

<?php
$serverName = "yourServername";
$connectionOptions = array(
    "database" => "yourDatabase",
    "uid" => "yourUsername",
    "pwd" => "yourPassword"
);

function exception_handler($exception) {
    echo "<h1>Failure</h1>";
    echo "Uncaught exception: " , $exception->getMessage();
    echo "<h1>PHP Info for troubleshooting</h1>";
    phpinfo();
}

set_exception_handler('exception_handler');

// Establishes the connection
$conn = sqlsrv_connect($serverName, $connectionOptions);
if ($conn === false) {
    die(formatErrors(sqlsrv_errors()));
}

// Select Query
$tsql = "SELECT @@Version AS SQL_VERSION";

// Executes the query
$stmt = sqlsrv_query($conn, $tsql);

// Error handling
if ($stmt === false) {
    die(formatErrors(sqlsrv_errors()));
}
?>

<h1> Success Results : </h1>

<?php
while ($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC)) {
    echo $row['SQL_VERSION'] . PHP_EOL;
}

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

function formatErrors($errors)
{
    // Display errors
    echo "<h1>SQL Error:</h1>";
    echo "Error information: <br/>";
    foreach ($errors as $error) {
        echo "SQLSTATE: ". $error['SQLSTATE'] . "<br/>";
        echo "Code: ". $error['code'] . "<br/>";
        echo "Message: ". $error['message'] . "<br/>";
    }
}
?>

PDO_SQLSRV 範例

<?php
try {
    $serverName = "yourServername";
    $databaseName = "yourDatabase";
    $uid = "yourUsername";
    $pwd = "yourPassword";
    
    $conn = new PDO("sqlsrv:server = $serverName; Database = $databaseName;", $uid, $pwd);

    // Select Query
    $tsql = "SELECT @@Version AS SQL_VERSION";

    // Executes the query
    $stmt = $conn->query($tsql);
} catch (PDOException $exception1) {
    echo "<h1>Caught PDO exception:</h1>";
    echo $exception1->getMessage() . PHP_EOL;
    echo "<h1>PHP Info for troubleshooting</h1>";
    phpinfo();
}

?>

<h1> Success Results : </h1>

<?php
try {
    while ($row = $stmt->fetch(PDO::FETCH_ASSOC)) {
        echo $row['SQL_VERSION'] . PHP_EOL;
    }
} catch (PDOException $exception2) {
    // Display errors
    echo "<h1>Caught PDO exception:</h1>";
    echo $exception2->getMessage() . PHP_EOL;
}

unset($stmt);
unset($conn);
?>

將您的瀏覽器指向 https://localhost/testsql.php (macOS 上的 https://localhost:8080/testsql.php )。 您現在應該能夠連線到您的 SQL Server/Azure SQL 資料庫。 如果您看不到顯示 SQL 版本資訊的成功訊息,則可以從命令列執行指令碼來進行一些基本的疑難排解:

php testsql.php

如果您成功從命令列執行,但瀏覽器上未顯示任何內容,請檢查 Apache 記錄檔 \(英文\)。 如需其他說明,請參閱支援資源以了解取得說明的相關位置。

另請參閱

開始使用 Microsoft Drivers for PHP for SQL Server

載入 Microsoft Drivers for PHP for SQL Server

Microsoft Drivers for PHP for SQL Server 的系統需求