Microsoft Drivers for PHP for SQL Server 系统要求

下载 PHP 驱动程序

本文列出了您必须在系统上安装哪些组件,才能通过使用 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前加载。

选择一个兼容的套件

在下载或构建驱动之前,请完成以下检查:

  1. 识别每个为该应用服务的PHP运行时。 调度任务、命令行工作程序、IIS 站点、Apache 模块和 PHP-FPM 池可以使用不同的 PHP 可执行文件和配置文件。

  2. 对每个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。 构建、加载和测试扩展时使用相同的架构选择。

  3. 选择支持 PHP 小版本、操作系统和数据库目标的 PHP 驱动版本。

  4. 从本文的兼容性表中选择受支持的 Microsoft ODBC 驱动程序版本。

  5. 将扩展文件或PIE构建匹配到PHP架构和线程安全模式。 除非所有这些数值都匹配,否则不要从另一个PHP安装复制扩展。

  6. 分别配置和验证CLI和Web服务器运行时。 成功的 php -m 命令仅证明 CLI 运行时加载了扩展。

PHP

从 PHP官网下载PHP二进制文件。 选择 PHP 版本支持中列出的 PHP 版本。

线程安全性与架构

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 。

诊断要求失败

问题 可能的所有者 检查
PHP Startup: Unable to load dynamic library PHP 运行时或扩展选择 PHP 小版本、架构、线程安全模式及 extension_dir确切文件名
Call to undefined function sqlsrv_connect() SQLSRV 扩展配置 php --ri sqlsrv、活动的 php.ini 文件和扫描的 .ini 文件
PDOException: could not find driver PDO_SQLSRV扩展或PDO加载顺序 php --ri pdo_sqlsrv, PDO::getAvailableDrivers(), 以及 PDO是否先加载
缺失 msodbcsql 或 libodbc 库 ODBC 安装或操作系统加载程序 安装的 ODBC 包、体系结构和共享的库依赖项
CLI成功了,但网站失败了 SAPI 专用的 PHP 配置 在php --ini后,将与临时phpinfo()页面进行比较
扩展程序已加载,但连接失败 ODBC、网络、认证、证书或数据库目标 捕获SQLSRV错误集合或PDO异常并排查所报告的 SQLSTATE