本文列出了您必须在系统上安装哪些组件,才能通过使用 SQLSRV 或 PDO_SQLSRV 驱动访问SQL Server或Azure SQL 数据库数据。
有关PHP驱动支持生命周期和需求的更多信息,请参见 支持矩阵。 每个版本中的 SQLSRV 和 PDO_SQLSRV 驱动具有相同的 PHP、操作系统、架构、线程安全和 ODBC 要求。
驱动程序堆栈如何协同工作
PHP 应用程序不直接连接到数据库服务器。 每一层必须与其相邻的层兼容:
| 层 | 你选择或配置的内容 | 不匹配项的外观 |
|---|---|---|
| Application | SQLSRV 函数或 PDO_SQLSRV类和属性 | 未定义的函数、不可用的 PDO 驱动程序,或应用级错误 |
| PHP 扩展 | 为PHP小版本、架构和线程安全模式构建的SQLSRV和PDO_SQLSRV文件 | PHP 启动警告、模块加载失败或进程崩溃 |
| PHP 运行时 | 命令行界面(CLI)、Apache 模块、PHP-FPM 或 IIS FastCGI 配置 | CLI会加载驱动,但网页应用不会 |
| Microsoft ODBC 驱动程序 | 所选 PHP 驱动程序版本支持的版本 | 连接失败或缺失的 ODBC 库 |
| 操作系统 | 一个支持的版本和架构,包含所需的运行时和构建包 | 没有兼容包、未解决的共享库或源代码构建失败 |
| 数据库产品 | 受支持的 SQL Server 或 Azure SQL 目标 | 连接建立后的服务器版本或功能特定错误 |
SQLSRV和PDO_SQLSRV在同一ODBC驱动上提供不同的PHP API。 当你的应用程序同时使用两个 API 时,请安装这两个 API。 安装一个扩展不会自动安装或启用另一个。
| API | 编程模型 | 特定于安装的检查 |
|---|---|---|
| SQLSRV | 过程函数 sqlsrv_* 与 SQLSRV 常量 |
extension_loaded('sqlsrv') 和 function_exists('sqlsrv_connect') |
| PDO_SQLSRV | PHP 数据对象(PDO)类、属性和异常 |
extension_loaded('pdo_sqlsrv') 中的 sqlsrv 和 PDO::getAvailableDrivers() |
这些扩展模块可以独立安装。 PDO_SQLSRV还要求PDO在PDO_SQLSRV前加载。
选择一个兼容的套件
在下载或构建驱动之前,请完成以下检查:
识别每个为该应用服务的PHP运行时。 调度任务、命令行工作程序、IIS 站点、Apache 模块和 PHP-FPM 池可以使用不同的 PHP 可执行文件和配置文件。
对每个PHP可执行文件执行以下命令:
php -i | findstr /I "PHP Version Architecture Thread Safety extension_dir"在Linux或macOS上,请使用:
php -i | grep -E "PHP Version|Thread Safety|extension_dir" file "$(php -r 'echo PHP_BINARY;')"file命令显示该可执行文件的架构。 如果其显示为通用 macOS 可执行文件,请明确选择预期的架构,例如arch -arm64 php --version或arch -x86_64 php --version。 构建、加载和测试扩展时使用相同的架构选择。选择支持 PHP 小版本、操作系统和数据库目标的 PHP 驱动版本。
从本文的兼容性表中选择受支持的 Microsoft ODBC 驱动程序版本。
将扩展文件或PIE构建匹配到PHP架构和线程安全模式。 除非所有这些数值都匹配,否则不要从另一个PHP安装复制扩展。
分别配置和验证CLI和Web服务器运行时。 成功的
php -m命令仅证明 CLI 运行时加载了扩展。
PHP
从 PHP官网下载PHP二进制文件。 选择 PHP 版本支持中列出的 PHP 版本。
启用与你PHP版本匹配的驱动文件。 关于文件名,请参见 驱动程序版本。 从Download the Microsoft Drivers for PHP for SQL Server下载这些文件。 关于配置说明,请参见“加载 Microsoft Drivers for PHP for SQL Server”。
选择 PHP 和应用程序框架支持的 Web 服务器和 PHP 集成方法。 按照 PHP安装文档 和你框架的部署说明,配置Web服务器运行PHP。 在Web服务器运行时与CLI分开验证扩展加载。
线程安全性与架构
PHP 构建文件和扩展文件中的这两个值必须一致。
| PHP值 | 所需的驱动程序选择 |
|---|---|
Thread Safety => enabled |
线程安全(ts 或 TS)驱动文件 |
Thread Safety => disabled |
非线程安全(nts 或 NTS)驱动文件 |
Architecture => x64 |
64位驱动文件和64位ODBC组件 |
Architecture => x86 |
32位Windows驱动文件和32位ODBC组件 |
CLI可以使用线程安全或非线程安全的PHP构建版本。 选择扩展时应按所报告的值,而不是假设每个 CLI 构建都是非线程安全的。
ODBC 驱动程序
在运行PHP的电脑上安装支持的Microsoft ODBC驱动for SQL Server。 从Download ODBC Driver for SQL Server下载驱动。
如果要在 64 位版本的 Windows 上下载 Windows 版本的驱动程序,ODBC 64 位安装程序将同时安装 32 位和 64 位 ODBC 驱动程序。 如果使用的是 32 位版本的 Windows,请使用 ODBC x86 安装程序。 在非 Windows 平台上,仅 64 位版本的驱动程序可用。
表格包含了用于升级规划的历史组合方案。 使用当前的PHP驱动版本及其列出的ODBC版本进行新安装。 兼容旧版本并不会延长其支持生命周期。 查看 PHP驱动支持生命周期 和 支持的PHP版本。
空白单元并不意味着PHP驱动一定会拒绝该ODBC版本。 单个功能可能需要比基础组合更新的ODBC版本。
| PHP 驱动程序版本 → ↓ ODBC 驱动程序版本 |
5.13 | 5.12 | 5.11 | 5.10 | 5.9 | 5.8 | 5.6 | 5.3 | 5.2 | 4.3 | 4.0 | 3.2 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ODBC 驱动程序 18 | 是 | 是 | 是 | 是 | ||||||||
| ODBC 驱动程序 17 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | |||
| ODBC 驱动程序 13.1 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | ||
| ODBC 驱动程序 13 | 是 | |||||||||||
| ODBC 驱动程序 11 | 是 | 是 | 是 | 是 | 是 | 是 | 是 |
如果使用的是 SQLSRV 驱动程序,sqlsrv_client_info 将返回有关 Microsoft Drivers for PHP for SQL Server 正在使用哪个版本的 SQL Server Microsoft ODBC Driver for SQL Server 的信息。 如果使用的是 PDO_SQLSRV 驱动程序,可以使用 PDO::getAttribute 来发现版本。
SQL Server
有关支持的 SQL Server 版本,请参见支持的数据库版本。
分别评估 SQL Server、Azure SQL 数据库、Azure SQL 托管实例、Azure Synapse Analytics、Microsoft Fabric 中的 SQL 数据库和 Microsoft Fabric 中的 Warehouse 的目标支持。 安装需求是客户端要求,并不意味着每个目标环境都支持所有认证方法、连接选项、Transact-SQL(T-SQL)功能或数据类型。 根据你的应用程序使用的方案,使用支持矩阵和目标产品的文档。
操作系统
关于支持的操作系统,请参见 支持的操作系统。
驱动程序版本
适用于 SQL Server 的 Microsoft PHP 驱动程序每次发布时都会附带 SQLSRV 和 PDO_SQLSRV 驱动文件,分为线程安全和非线程安全两种版本。 在 Windows 上,每个变体也提供 32 位和 64 位 PHP 版本。 将驱动文件与你的PHP版本、线程安全模式和架构匹配。 下载驱动程序文件后,如需启用它,请参见“加载 Microsoft PHP for SQL Server 驱动程序”。
在 Linux 和 macOS 上,按照 Linux 和 macOS 安装说明,使用 PIE(扩展 PHP 安装程序)安装驱动程序。 PIE 取代了已弃用的 PHP 扩展社区库(PECL)包系统,并将已安装的扩展命名为 sqlsrv.so 或 pdo_sqlsrv.so。 下列表格列出了你从Microsoft Drivers for PHP for SQL Server releases页面手动下载的预构建二进制包的文件名。
以下表格列出了5.13版本版本中的文件。 文件名中,ts和TS表示线程安全,nts和NTS表示非线程安全。
Windows驱动文件
该 Windows_5.13.xRTW.zip 包包含这些文件。
| SQLSRV 文件 | PDO_SQLSRV文件 | PHP 版本 | 线程是否安全? | 体系结构 |
|---|---|---|---|---|
php_sqlsrv_83_nts_x86.dll |
php_pdo_sqlsrv_83_nts_x86.dll |
8.3 | 否 | 32-bit |
php_sqlsrv_83_ts_x86.dll |
php_pdo_sqlsrv_83_ts_x86.dll |
8.3 | 是 | 32-bit |
php_sqlsrv_83_nts_x64.dll |
php_pdo_sqlsrv_83_nts_x64.dll |
8.3 | 否 | 64 位 |
php_sqlsrv_83_ts_x64.dll |
php_pdo_sqlsrv_83_ts_x64.dll |
8.3 | 是 | 64 位 |
php_sqlsrv_84_nts_x86.dll |
php_pdo_sqlsrv_84_nts_x86.dll |
8.4 | 否 | 32-bit |
php_sqlsrv_84_ts_x86.dll |
php_pdo_sqlsrv_84_ts_x86.dll |
8.4 | 是 | 32-bit |
php_sqlsrv_84_nts_x64.dll |
php_pdo_sqlsrv_84_nts_x64.dll |
8.4 | 否 | 64 位 |
php_sqlsrv_84_ts_x64.dll |
php_pdo_sqlsrv_84_ts_x64.dll |
8.4 | 是 | 64 位 |
php_sqlsrv_85_nts_x86.dll |
php_pdo_sqlsrv_85_nts_x86.dll |
8.5 | 否 | 32-bit |
php_sqlsrv_85_ts_x86.dll |
php_pdo_sqlsrv_85_ts_x86.dll |
8.5 | 是 | 32-bit |
php_sqlsrv_85_nts_x64.dll |
php_pdo_sqlsrv_85_nts_x64.dll |
8.5 | 否 | 64 位 |
php_sqlsrv_85_ts_x64.dll |
php_pdo_sqlsrv_85_ts_x64.dll |
8.5 | 是 | 64 位 |
使用非线程安全的驱动文件配合非线程安全的PHP构建,使用线程安全的驱动文件配合线程安全的PHP构建。 命令行界面(CLI)可以使用任一构建版本。 要确认你用的是哪个构建,可以运行 php -i 并检查 线程安全 值。
Linux 和 macOS 驱动文件
Linux_5.13.xRTW.tar.gz和Mac_5.13.xRTW.tar.gz包包含这些文件。 Linux 归档包含 x64 二进制文件,macOS 归档文件包含 Arm64 二进制文件。
预构建文件还必须与操作系统的原生库匹配。 Linux 5.13.3 二进制文件需要 glibc 2.38 及更高版本,以及提供 GLIBCXX_3.4.32 的 C++ 运行时。 macOS 5.13.3 二进制文件将 macOS 26 定为其最低部署目标。 这些二进制要求与操作系统对源代码构建的支持是分开的。
当归档的架构或原生库需求与你的PHP安装不符时,使用PIE。 为已安装的PHP和本地库提供PIE构建。 不要手动替换系统库来加载预构建的扩展。
| SQLSRV 文件 | PDO_SQLSRV文件 | PHP 版本 | 线程是否安全? |
|---|---|---|---|
SQLSRV_8.3_NTS.so |
PDO_SQLSRV_8.3_NTS.so |
8.3 | 否 |
SQLSRV_8.3_TS.so |
PDO_SQLSRV_8.3_TS.so |
8.3 | 是 |
SQLSRV_8.4_NTS.so |
PDO_SQLSRV_8.4_NTS.so |
8.4 | 否 |
SQLSRV_8.4_TS.so |
PDO_SQLSRV_8.4_TS.so |
8.4 | 是 |
SQLSRV_8.5_NTS.so |
PDO_SQLSRV_8.5_NTS.so |
8.5 | 否 |
SQLSRV_8.5_TS.so |
PDO_SQLSRV_8.5_TS.so |
8.5 | 是 |
把你需要的每个文件复制到你的PHP扩展目录里。 你可以保留包文件名并写入 extension=SQLSRV_8.4_NTS.so,或者将文件重命名为 sqlsrv.so 并写成简写形式 extension=sqlsrv。 同样的命名选择也适用于PDO_SQLSRV。 要找到扩展目录,运行 php -i | grep extension_dir. 请按照 在 Linux 和 macOS 上加载驱动程序 中的说明操作,在正确的配置文件中启用扩展,并在 PDO_SQLSRV 之前加载 PHP 数据对象(PDO)。
早期版本
对于 5.13 之前版本中包含的驱动程序文件,请从 Microsoft Drivers for PHP for SQL Server releases 页面下载该版本的软件包并列出其内容。 5.12 之前的版本会为每个操作系统和 PHP 版本发布一个独立的包,而不是每个平台发布一个单独的包。
验证所选环境
安装PHP扩展和ODBC驱动后,但在配置网页服务器之前,先进行以下检查:
php --version
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv
最后两个命令必须显示独立的模块信息部分。 如果任一命令报告扩展不存在,请先完成平台安装和加载流程,再测试数据库连接。
创建 verify-php-drivers.php 以检查两个 PHP API,而无需使用凭据:
<?php
$failures = [];
if (!extension_loaded('sqlsrv') || !function_exists('sqlsrv_connect')) {
$failures[] = 'SQLSRV is not loaded.';
}
if (!extension_loaded('pdo_sqlsrv') || !in_array('sqlsrv', PDO::getAvailableDrivers(), true)) {
$failures[] = 'PDO_SQLSRV is not loaded.';
}
echo $failures === []
? "SQLSRV and PDO_SQLSRV are loaded." . PHP_EOL
: implode(PHP_EOL, $failures) . PHP_EOL;
exit($failures === [] ? 0 : 1);
使用服务该应用程序的 PHP 可执行文件运行它:
php verify-php-drivers.php
预期输出:
SQLSRV and PDO_SQLSRV are loaded.
该检查用于验证扩展加载。 它不验证 ODBC 连接性、认证、证书信任、网络访问或数据库权限。
记录结果后删除 verify-php-drivers.php 。