Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
В этой статье перечислены компоненты, которые необходимо установить на вашу систему для доступа к данным в SQL Server или База данных SQL Azure с помощью драйвера SQLSRV или PDO_SQLSRV.
Для получения дополнительной информации о жизненном цикле поддержки и требованиях к драйверам PHP смотрите матрицу поддержки. Драйверы SQLSRV и PDO_SQLSRV в каждом релизе имеют одинаковые требования к PHP, операционной системе, архитектуре, безопасности потоков и ODBC.
Как сочетается стек драйверов
PHP-приложение не подключается напрямую к серверу базы данных. Каждый слой должен быть совместим с соседним слоем:
| Слой | Что вы выбираете или настраиваете | Как выглядит несоответствие |
|---|---|---|
| Application | Функции SQLSRV или PDO_SQLSRV классы и атрибуты | Неопределённые функции, недоступный драйвер PDO или ошибки на уровне приложений |
| Расширение PHP | SQLSRV и PDO_SQLSRV файлы, созданные для минорной версии PHP, архитектуры и режима безопасности потоков | Предупреждение о запуске PHP, сбое загрузки модуля или сбое процесса |
| Среда выполнения PHP | Командный интерфейс (CLI), модуль Apache, конфигурация PHP-FPM или IIS FastCGI | CLI загружает драйверы, а веб-приложение — нет |
| Драйвер ODBC Microsoft. | Версия, которую поддерживает выбранный выпуск драйвера PHP | Сбои соединения или отсутствие библиотеки ODBC |
| Операционная система | Поддерживаемый релиз и архитектура с необходимыми пакетами для выполнения и сборки | Нет совместимого пакета, неразрешённой общей библиотеки или сбоя сборки исходного кода |
| Продукт базы данных | Поддерживаемый целевой SQL Server или Azure SQL | Ошибки, зависящие от версии сервера или функции, после установления соединения |
SQLSRV и PDO_SQLSRV предоставляют разные PHP-API через один и тот же драйвер ODBC. Устанавливайте оба, когда ваше приложение использует оба API. Установка одного расширения не автоматически устанавливает и не включает другое.
| API | Модель программирования | Проверка для конкретной установки |
|---|---|---|
| SQLSRV | Процедурные sqlsrv_* функции и константы SQLSRV |
extension_loaded('sqlsrv') и function_exists('sqlsrv_connect'). |
| PDO_SQLSRV | Классы, атрибуты и исключения PHP Data Objects (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 и среды выполнения веб-сервера по отдельности. Успешное выполнение команды
php -mдоказывает только, что среда выполнения CLI загрузила расширение.
PHP
Скачайте PHP-бинарные файлы с сайта PHP. Выберите версию PHP, указанную в разделе поддержки версий PHP.
Включите драйверный файл, который соответствует вашей версии PHP. Для названий файлов см. Версии драйверов. Скачайте файлы по ссылке Скачать драйверы Microsoft для PHP для SQL Server. Для инструкций по настройке см. Загрузите драйверы Microsoft для PHP для SQL Server.
Выберите метод интеграции веб-сервера и PHP, поддерживаемый PHP и вашим прикладным фреймворком. Следуйте документации по установке PHP и инструкциям по развертыванию вашего фреймворка, чтобы настроить веб-сервер для запуска PHP. Проверьте загрузку расширения в среде выполнения веб-сервера отдельно от 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
Установите поддерживаемый драйвер Microsoft ODBC для SQL Server на компьютер, на котором работает PHP. Скачайте драйвер с Download ODBC Driver for SQL Server.
Если вы скачиваете версию драйвера для 64-разрядной версии Windows, установщик 64-разрядной ODBC установит как 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 ODBC Driver для SQL Server применяется драйверами Microsoft для PHP для SQL Server. Если вы используете драйвер PDO_SQLSRV, можно применить PDO::getAttribute для определения версии.
SQL Server
Для поддерживаемых версий SQL Server см. раздел «Поддерживаемые версии баз данных».
Отдельно оценивайте поддержку целевых объектов для SQL Server, База данных SQL Azure, Управляемый экземпляр SQL Azure, Azure Synapse Analytics, базы данных SQL в Microsoft Fabric и Warehouse в Microsoft Fabric. Требования к установке — это требования на стороне клиента и не означают, что все методы аутентификации, варианты подключения, возможности Transact-SQL (T-SQL) или типы данных доступны в каждой целевой системе. Используйте матрицу поддержки и документацию целевого продукта для сценария, который использует ваше приложение.
Операционные системы
Для поддерживаемых операционных систем см. раздел Поддерживаемые операционные системы.
Версии драйвера
Каждый релиз Microsoft Drivers for PHP for SQL Server поставляет файлы драйверов SQLSRV и PDO_SQLSRV в вариантах, безопасных для потоков, и не безопасных для потоков. В Windows каждая версия также собрана для 32-битного и 64-битного PHP. Сопоставьте файл драйвера с вашей версией PHP, режимом безопасности потоков и архитектурой. Чтобы активировать файл драйвера после его скачивания, смотрите «Загрузка драйверов Microsoft для PHP для SQL Server».
На Linux и macOS устанавливайте драйверы с помощью PIE — PHP Installer for Extensions, как описано в инструкциях по установке Linux и macOS. PIE заменяет устаревшую систему пакетов PHP Extension Community Library (PECL) и называет установленное расширение sqlsrv.so или pdo_sqlsrv.so. В следующих таблицах приведены имена файлов готовых бинарных пакетов, которые вы вручную скачиваете со страницы релизов Microsoft Drivers for PHP for SQL Server.
В следующих таблицах перечислены файлы в пакетах релиза 5.13. В названиях файлов ts и TS означают «потокобезопасно», а nts и NTS означают «непотокобезопасно».
Файлы драйверов Windows
Пакет Windows_5.13.xRTW.zip содержит эти файлы.
| Файл SQLSRV | PDO_SQLSRV файл | Версия PHP | Является потокобезопасным? | Architecture |
|---|---|---|---|---|
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-bit |
php_sqlsrv_83_ts_x64.dll |
php_pdo_sqlsrv_83_ts_x64.dll |
8.3 | да | 64-bit |
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-bit |
php_sqlsrv_84_ts_x64.dll |
php_pdo_sqlsrv_84_ts_x64.dll |
8.4 | да | 64-bit |
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-bit |
php_sqlsrv_85_ts_x64.dll |
php_pdo_sqlsrv_85_ts_x64.dll |
8.5 | да | 64-bit |
Используйте файл драйвера, не безопасный для потоков, с 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 или более поздней, а также среду выполнения C++, которая обеспечивает GLIBCXX_3.4.32. Бинарные файлы macOS 5.13.3 указывают macOS 26 в качестве минимальной целевой версии развертывания. Эти двоичные требования отделены от поддержки операционных систем для сборок из исходного кода.
Используйте PIE, если архитектура архива или требования нативной библиотеки несовместимы с вашей средой PHP. PIE-сборки для установленного PHP и нативных библиотек. Не заменяйте системные библиотеки вручную, чтобы загрузить готовое расширение.
| Файл 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, чтобы включить расширения в правильном конфигурационном файле и загрузить PHP Data Objects (PDO) до PDO_SQLSRV.
Более ранние выпуски
Для файлов драйверов, включённых в релизы до версии 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 |
Связанные материалы
- Getting Started with the Microsoft Drivers for PHP for SQL Server (Начало работы с драйверами Майкрософт для PHP для SQL Server)
- Руководство по программированию драйверов Microsoft для PHP для SQL Server
- Справочник по API для драйвера SQLSRV
- Справочник по драйверу PDO_SQLSRV