通过

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 进程管理器 (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.1 替换为 8.2 或 8.3。

步骤 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) 上的说明安装适用于 Ubuntu 的 ODBC 驱动程序。 确保也安装 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.1 替换为 8.2 或 8.3。

步骤 1. 安装 PHP（带 PHP-FPM 的 Ubuntu）

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. 安装必备组件（带 PHP-FPM 的 Ubuntu）

按照安装 Microsoft ODBC Driver for SQL Server (Linux) 上的说明安装适用于 Ubuntu 的 ODBC 驱动程序。 确保也安装 unixodbc-dev 包。 pecl 命令用它来安装 PHP 驱动程序。

步骤 3. 安装适用于 Microsoft SQL Server 的 PHP 驱动程序（带 PHP-FPM 的 Ubuntu）

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.ini 和 pdo_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（带 PHP-FPM 的 Ubuntu）

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 并测试示例脚本（带 PHP-FPM 的 Ubuntu）

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) 上的说明安装适用于 Red Hat 7 或 8 的 ODBC 驱动程序。 确保也安装 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.1 替换为 8.2 或 8.3。

步骤 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) 上的说明安装适用于 Debian 的 ODBC 驱动程序。 确保也安装 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 上安装

注意

在下面的说明中，将 <SuseVersion> 替换为 SUSE 版本，如果使用的是 SUSE Enterprise Linux 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) 上的说明安装适用于 SUSE 的 ODBC 驱动程序。 确保也安装 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 上安装

注意

可从 Alpine 的测试或边缘存储库中获取 PHP 8.1 或更高版本。 可以改为从源编译 PHP。

步骤 1。 安装 PHP (Alpine)

可以在 edge/community 存储库中找到用于 Alpine 的 PHP 包。 请查看 Wiki 页上的启用社区存储库。 将以下行添加到 /etc/apk/repositories，并将 <mirror> 替换为 Alpine 存储库镜像的 URL：

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) 上的说明安装适用于 Alpine 的 ODBC 驱动程序。 确保也安装 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) 上的说明安装适用于 macOS 的 ODBC 驱动程序。

注意

如果使用 Apple M1 ARM64 硬件，请直接安装 Microsoft ODBC 驱动程序 17.8+，而无需使用模拟器 Rosetta 2。

此外，可能需要安装 GNU make 工具：

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 安装的 Apache 配置文件 httpd.conf，请运行：

/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 系统要求