Microsoft Drivers for PHP for SQL Server 概述

下载 PHP 驱动程序

PHP for SQL Server 的Microsoft驱动包括两个 PHP 扩展,分别是 SQLSRV 和 PDO_SQLSRV。 PDO_SQLSRV实现了PHP数据对象(PDO)接口。 这两个扩展都使用Microsoft ODBC驱动for SQL Server来连接Microsoft SQL。 它们的PHP API、驱动程序特定选项和默认PHP类型各不相同。 例如,SQLSRV 默认将日期和时间值返回为 DateTime 对象,而 PDO_SQLSRV 默认返回字符串。 关于系统需求,请参见 Microsoft PHP for SQL Server 驱动程序的系统需求。

选择 SQLSRV 或 PDO_SQLSRV

如果你... Use
正在开始一个新项目,且其他地方没有 PDO 代码 选择你的应用将始终使用的界面。 SQLSRV 公开过程式函数和显式参数描述符。 PDO_SQLSRV 适合围绕 PDO 和 PDOStatement 对象组织的代码。
已经将 PDO 与其他数据库(MySQL、PostgreSQL、SQLite)配合使用 PDO_SQLSRV,这样你的数据访问层在数据库间保持一致。
使用一个期望有 PDO 连接对象的框架或库 PDO_SQLSRV。
需要手动、逐块控制流数据何时发送 SQLSRV,使用 sqlsrv_send_stream_data()。 PDO_SQLSRV 也支持流式传输大值,方法是使用 PDO::PARAM_LOB 绑定 PHP 流资源,但它会在 execute() 期间自动发送整个流,而不是通过调用方控制的分块发送。
维护一个已经调用 sqlsrv_* 函数的应用程序 SQLSRV,除非你打算将其数据访问代码重写为 PDO。

安装其中一个扩展或两个都安装。 Windows 下载包含独立的扩展二进制文件;在 Linux 和 macOS 上,需分别安装sqlsrv和pdo_sqlsrv包。 你可以在同一个 PHP 进程中加载两者。 SQLSRV 返回连接和语句资源;PDO_SQLSRV返回 PDO 和 PDOStatement 对象。 不要把资源从一个 API 传递到另一个 API。

使用 PDO 并不意味着 Transact-SQL(T-SQL)语法可以移植到其他数据库。 PDO 给你一个通用的 PHP 接口;你的查询、模式、认证和驱动程序特定属性仍然可以依赖于 Microsoft SQL。 同样,使用过程式扩展并不要求整个应用程序都采用过程式组织方式:你可以从自己的类调用 SQLSRV。

比较两个 API 中的相同结果

在确定应用程序期望的 PHP 表示形式之前,请先运行这些程序。 它们选择相同的整数、日期和 SQL NULL,但默认设置并不完全相同。 无需表格或样本数据库。

安装并加载选定的扩展。 在进程环境中为现有的 SQL Server 测试数据库设置 SQL_SERVER、SQL_DATABASE、SQL_USER 和 SQL_PASSWORD。 服务器证书必须是可信的,并且与配置端点匹配。 有关设置和无密码 Azure 替代方案,请参阅连接到服务器。

SQLSRV

将此完整程序保存为 compare-sqlsrv.php,并运行 php compare-sqlsrv.php。

<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name before running this example.");
    }
    $config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$conn = sqlsrv_connect($config['SQL_SERVER'], [
    'Database' => $config['SQL_DATABASE'],
    'UID' => $config['SQL_USER'],
    'PWD' => $config['SQL_PASSWORD'],
    'Encrypt' => true,
    'TrustServerCertificate' => false,
    'LoginTimeout' => 30,
    'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$stmt = null;
try {
    $stmt = sqlsrv_query($conn, "SELECT CAST(42 AS int) AS CountValue, "
        . "CAST('2026-10-19' AS date) AS DayValue, CAST(NULL AS int) AS Missing");
    if ($stmt === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    $row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    if (!is_array($row) || $row['CountValue'] !== 42
        || !($row['DayValue'] instanceof DateTime)
        || $row['DayValue']->format('Y-m-d') !== '2026-10-19'
        || $row['Missing'] !== null) {
        throw new RuntimeException('Unexpected SQLSRV values or default types.');
    }
    echo get_debug_type($row['CountValue']), ', ',
        get_debug_type($row['DayValue']), ', ', get_debug_type($row['Missing']), PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

预期输出:

int, DateTime, null

PDO_SQLSRV

将这个独立程序保存为 compare-pdo.php,并运行 php compare-pdo.php。 它有意让数值和日期的获取保持 PDO_SQLSRV 的默认设置。

<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name before running this example.");
    }
    $config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$server = $config['SQL_SERVER'];
$database = $config['SQL_DATABASE'];
$pdo = new PDO(
    "sqlsrv:Server=$server;Database=$database;Encrypt=true;"
    . "TrustServerCertificate=false;LoginTimeout=30",
    $config['SQL_USER'],
    $config['SQL_PASSWORD'],
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
    ]
);
$stmt = null;
try {
    $stmt = $pdo->query("SELECT CAST(42 AS int) AS CountValue, "
        . "CAST('2026-10-19' AS date) AS DayValue, CAST(NULL AS int) AS Missing");
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['CountValue' => '42', 'DayValue' => '2026-10-19', 'Missing' => null]) {
        throw new RuntimeException('Unexpected PDO_SQLSRV values or default types.');
    }
    echo get_debug_type($row['CountValue']), ', ',
        get_debug_type($row['DayValue']), ', ', get_debug_type($row['Missing']), PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

预期输出:

string, string, null

这两个程序都明确请求命名结果键。 这些PHP数组使用如 CountValue 这样的列名,而非从零开始的数字索引。 NULL SQL 在任一 API 中都变成了 PHPnull。 它不是空字符串,也不是缺失的结果行。

这两个程序都读取了环境中的实际数据库名称、用户名和密码。 它们会针对 PHP 驱动程序的 ODBC 风格连接处理,对这些值转义一次。 双重闭括号并将值包裹在大括号中可以保留特殊字符;这不会重命名数据库或更改存储的密码。 更多信息请参见“连接服务器”。

这些示例会在出错时停止,并在 finally 中释放资源。 SQLSRV 通过 false 和 sqlsrv_errors() 报告数据库失败;PDO_SQLSRV 在连接失败时抛出异常,并在配置了错误模式的情况下,针对查询失败使用异常。 在网页应用中,在处理请求的代码中捕捉这些异常。 将诊断细节记录在受保护的日志中,而不是返回到浏览器。

练习结束后,如果你不再需要它们,请删除 compare-sqlsrv.php 和 compare-pdo.php。 完成测试后,清除测试进程中的凭证环境变量。

选择类型、编码和错误处理

确定你的应用程序期望哪些 PHP 类型、如何处理文本和错误,以及何时释放数据库资源。

决定 SQLSRV PDO_SQLSRV 对应用程序代码的影响
整数结果类型 将 SQL int 列映射为原生 PHP 整数。 默认返回字符串;PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE 则请求受支持的数值型 PHP 类型。 严格的比较和序列化输出可能存在差异。 不要假设每种 SQL 数值类型都适合 PHP 的整数或浮点数。
日期和时间结果 DateTime 默认选择对象;ReturnDatesAsStrings 选择字符串。 默认是字符串; PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE 选择对象。 在序列化或传递给应用程序代码之前,先对表示进行规范化。
字符编码 显式设置 CharacterSet => 'UTF-8' 。 默认编码为 UTF-8;可通过 PDO::SQLSRV_ATTR_ENCODING 进行配置。 不要将 SQLSRV 选项传递到 PDO DSN 中。
错误处理 立即检查 false 并捕获完整的 SQLSRV 错误集合。 配置 PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION。 缺行和查询失败需要不同的处理方式。
参数重用 在 sqlsrv_prepare() 描述符中按引用绑定变量。 使用 bindParam() 表示变量,或使用 bindValue() 表示其当前值。 重新分配变量影响的是参考绑定,而不是先前的值绑定。
清理行动 先释放语句,再关闭连接资源。 先释放语句引用,再释放 PDO 对象。 一个语句可以在另一个引用被设置为 null后保持 PDO 连接的存活。

如果你迁移了现有应用,在更改数据库代码之前,先用代表性的数值测试这些行为。 包含非ASCII文本、SQL NULL、日期、精确十进制值和存储过程输出参数。 还要比较一下你的框架是如何配置 PDO 属性的。 仅仅替换函数名并不能迁移错误处理、引用绑定或返回的PHP类型。

对于同时使用两个 API 的写入和读取工作流的完整示例,请参阅编程指南。 对于重复执行和类型化输入,可以使用比较查询执行函数。

了解每个组件的功能

你的扩展选择会改变 PHP API 及其类型转换。 这两个扩展都使用 ODBC 与服务器通信、加密连接并进行身份验证。 操作系统提供可信证书和服务,如Windows 身份验证或Kerberos。 SQL 目标控制权限、模式和支持的 T-SQL 语句。

这些比较程序使用 SQL 身份验证连接到 SQL Server。 对于 Azure SQL 数据库、Azure SQL 托管实例、Azure Synapse Analytics、Fabric 中的 SQL 数据库或 Fabric 中的仓库,在重用获取模式之前,请先配置服务终结点和受支持的身份验证。 这两个 Fabric 产品都需要 Microsoft Entra ID 认证;仓库还需要禁用多个主动结果集(MARS)。 在 SQL Server 上成功进行类型比较并不能证明不同目标支持本概述中列出的所有功能。

两种扩展都能提供什么

  • 集成认证、SQL 认证以及 Microsoft Entra ID 认证,具体取决于目标是否支持。 托管标识不使用应用程序密码;ActiveDirectoryServicePrincipal 使用客户端 ID 和客户端机密。 更多信息请参见“连接服务器”。
  • 参数化查询、预备语句以及方向性(输入/输出)参数。 更多信息请参见“ 比较执行函数 ”和 “使用方向参数”。
  • 事务、用于大字符和二进制值的流输入参数,以及表值参数。
  • Always Encrypted,包括在 ODBC 驱动程序和 SQL Server 目标支持的情况下使用安全飞地。 更多信息请参见《使用 Microsoft PHP for SQL Server 驱动程序实现 Always Encrypted》。
  • 连接SQL Server、Azure SQL 数据库、Azure SQL 托管实例、Azure Synapse Analytics、Microsoft Fabric中的SQL database和Microsoft Fabric中的Warehouse。 认证和SQL特性因目标而异;参见Azure和Fabric连接。