Загрузите драйверы Microsoft для PHP для SQL Server

Драйверы SQLSRV и PDO_SQLSRV — это расширения для PHP. PHP загружает их при запуске процесса PHP, читая php.ini и любые дополнительные файлы .ini.

Загрузка отдельна от установки. Копирование или сборка расширения размещает файл на диске. PHP не может использовать SQLSRV или PDO_SQLSRV, пока активная конфигурация не будет содержать правильную запись и процесс PHP не будет перезапущен.

Защитите веб-диагностические страницы

Перед созданием временной phpinfo() страницы настройте веб-сервер так, чтобы разрешать только запросы локального хоста или аутентифицированных администраторов. Оставьте это ограничение до удаления страницы. phpinfo() может раскрывать переменные среды, учетные данные и конфигурацию сервера. Удалите страницу сразу после проверки.

Понимание области действия конфигурации PHP

Каждый интерфейс прикладного программирования (SAPI) PHP-сервера может использовать разный исполняемый файл и конфигурацию:

Runtime Типичный источник конфигурации Как его определить
Интерфейс командной строки (CLI) Каталог сканирования, указанный php --ini и php.ini Запускайте php --ini с указанным исполняемым файлом
IIS FastCGI исполняемый файл PHP, настроенный в приложении IIS FastCGI Используйте временную phpinfo() страницу
Модуль Apache Конфигурация PHP-модуля Apache Используйте временную phpinfo() страницу
PHP-FPM Исполняемый файл FPM, пул, php.ini и каталог сканирования Запустите версионный FPM-бинар с -i или используйте временную страницу phpinfo()
Длительно работающий процесс Исполняемый файл и среда, которые запустили worker Проверьте службу worker и перезапустите её после изменений

Изменение конфигурации CLI не влияет на IIS, Apache или PHP-FPM при использовании другой PHP-установки или сканерной папки.

Найдите конфигурацию PHP

Выполните следующие команды с PHP-исполняемым файлом, используемым вашим приложением:

php --ini
php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir"

На Linux или macOS замените findstr на grep:

php -i | grep -E "PHP Version|Thread Safety|extension_dir"
file "$(php -r 'echo PHP_BINARY;')"

Команда file определяет архитектуру выбранного исполняемого файла. Для универсального исполняемого файла macOS следуйте явному выбору архитектуры.

Значения Загруженный файл конфигурации и Поиск дополнительных файлов .ini в определяют конфигурацию, используемую процессом командной строки. Веб-сервер или процесс PHP FastCGI Process Manager (PHP-FPM) может использовать другой исполняемый файл PHP или файл конфигурации. Используйте временную страницу phpinfo(), чтобы определить, какие значения относятся к этому процессу.

Перед редактированием файла запишите:

  • Путь исполняемого файла PHP и версия.
  • Загружено php.ini.
  • Дополнительный каталог .ini сканирования.
  • Каталог расширений.
  • Режим потокобезопасности и архитектура.
  • Каждый процесс, который нужно перезапустить.

Сделайте резервную копию каждого изменённого конфигурационного файла.

Установите драйверы в Windows

Для установки с помощью PHP Installer for Extensions (PIE) сначала скачайте и проверьте PIE. Выполните следующие команды из каталога, содержащего pie.phar, с исполняемым файлом PHP, который должен загружать драйверы:

php .\pie.phar install microsoft/sqlsrv
php .\pie.phar install microsoft/pdo_sqlsrv

Установить php_sqlsrv.dll и php_pdo_sqlsrv.dll. Если PIE не может автоматически включить расширения, удалите все существующие SQLSRV и PDO_SQLSRV записи из активного php.ini, затем добавьте:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

Используйте только один элемент для каждого водителя. Перезапустите процесс PHP после изменения его конфигурации.

Для установки из ZIP скопируйте библиотеки динамической компоновки (DLL), соответствующие минорной версии PHP, архитектуре и режиму безопасности потоков, в каталог extension_dir. PHP 8.5 x64 потоково-безопасная среда выполнения использует следующие имена файлов:

php_sqlsrv_85_ts_x64.dll
php_pdo_sqlsrv_85_ts_x64.dll

Добавьте оба имени файлов к php.ini, используемому процессом PHP:

extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

Замените 85, tsи x64 на значения для вашего PHP-runtime. Не смешивайте потокобезопасные и непотокобезопасные файлы, 32-битные и 64-битные файлы, а также файлы, созданные для другой минорной версии PHP.

Установите драйверы в Linux и macOS

Устанавливайте драйверы с помощью PIE. Для получения дополнительной информации смотрите руководство по установке Linux и macOS. PIE устанавливает файлы расширений и пытается активировать их с помощью инструментов конфигурации PHP платформы или путем добавления записи extension= в дополнительный файл .ini или стандартный php.ini. Если PIE сообщает, что не смог включить расширение, добавьте запись сами и проверьте активную конфигурацию.

Для ручной установки выберите готовые .so файлы, соответствующие вашей версии PHP, архитектуре, режиму безопасности потоков и нативным библиотекам операционной системы. Проверьте предварительно собранные зависимости для Linux и macOS; используйте PIE, если они не соответствуют вашей среде.

Например, непотокобезопасные файлы PHP 8.4 имеют имена SQLSRV_8.4_NTS.so и PDO_SQLSRV_8.4_NTS.so. Поместите их в каталог, возвращаемый php -i | grep extension_dir. Переименуйте их в sqlsrv.so и pdo_sqlsrv.so, чтобы использовать следующие записи ниже, или вместо этого используйте в записях точные имена файлов пакетов. Добавьте записи в вашу активную конфигурацию PHP в порядке загрузки, описанном в этом разделе:

extension=sqlsrv.so
extension=pdo_sqlsrv.so

Объекты данных PHP (PDO) должны загружаться до PDO_SQLSRV. PHP читает php.ini перед сканированием дополнительных .ini файлов в алфавитном порядке. Если в вашем дистрибутиве pdo.so загружается из отсканированного файла, поместите запись PDO_SQLSRV в более поздний отсканированный файл, например 30-pdo_sqlsrv.ini, когда PDO использует 10-pdo.ini. В таком случае не помещайте запись PDO_SQLSRV в php.ini.

Выберите элементы расширения

Используйте записи, соответствующие способу установки драйверов:

Платформа и метод Запись SQLSRV запись PDO_SQLSRV
Windows с PIE extension=php_sqlsrv.dll extension=php_pdo_sqlsrv.dll
ZIP-файл, созданный Windows Точное версионное имя DLL, например, extension=php_sqlsrv_85_ts_x64.dll Точное версионное имя DLL, например, extension=php_pdo_sqlsrv_85_ts_x64.dll
Linux или macOS с PIE extension=sqlsrv.so extension=pdo_sqlsrv.so
архив для Linux или macOS, переименованные файлы extension=sqlsrv.so extension=pdo_sqlsrv.so
Архив для Linux или macOS, оригинальные файлы Точное имя архивного файла, например extension=SQLSRV_8.4_NTS.so Точное имя архивного файла, например extension=PDO_SQLSRV_8.4_NTS.so

Не настраивайте одновременно короткое и версионное имя для одного и того же расширения. PHP может сообщить, что модуль уже загружен, или продолжить загрузку старого файла после обновления.

Перезагрузите PHP, чтобы загрузить драйверы

Перезапустите процесс после изменения файла расширения или конфигурации. Перезапустите веб-сервер, PHP-FPM, обработчики очереди и другие долговременные PHP-процессы, загружающие драйвер.

Расширения SQLSRV и PDO_SQLSRV можно загружать отдельно, но устанавливайте и проверяйте оба, когда ваше приложение использует оба драйвера. PDO встроен во многие PHP-пакеты. Если PDO не встроен, включите расширение PDO перед PDO_SQLSRV.

Проверьте загруженные драйверы

Для среды выполнения командной строки выполните:

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | findstr /I "sqlsrv pdo_sqlsrv"

В Linux или macOS используйте:

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | grep -E "sqlsrv|pdo_sqlsrv"

Для веб-сервера ограничите доступ к диагностической странице перед созданием временной страницы, содержащей <?php phpinfo(); ?>. Подтвердите загруженный конфигурационный файл, extension_dir и отдельные разделы sqlsrv и pdo_sqlsrv. Удалите страницу после проверки.

Также запустите проверку на уровне PHP, чтобы проверка охватывала оба API, а не только имена модулей. Сохраните эту программу как verify-php-drivers.php:

<?php
$checks = [
    'SQLSRV extension' => extension_loaded('sqlsrv'),
    'SQLSRV API' => function_exists('sqlsrv_connect'),
    'PDO_SQLSRV extension' => extension_loaded('pdo_sqlsrv'),
    'PDO_SQLSRV API' => class_exists('PDO')
        && in_array('sqlsrv', PDO::getAvailableDrivers(), true),
];

$failed = false;
foreach ($checks as $name => $passed) {
    echo $name . ': ' . ($passed ? 'loaded' : 'missing') . PHP_EOL;
    $failed = $failed || !$passed;
}

exit($failed ? 1 : 0);

Запустите программу с каждым исполняемым файлом PHP, который использует ваше приложение:

php verify-php-drivers.php

Ожидаемые выходные данные:

SQLSRV extension: loaded
SQLSRV API: loaded
PDO_SQLSRV extension: loaded
PDO_SQLSRV API: loaded

Для веб-среды исполнения временно поместите файл в корень документа и откройте его в браузере. Удалите его после проверки. Эта программа не открывает соединение с базой данных и не печатает значения конфигурации.

Удалите verify-php-drivers.php после завершения проверок CLI и веб-runtime.

Устранение неполадок при загрузке драйверов

Симптом Вызвать проверку Корректирующее действие
Unable to load dynamic library Неправильное имя файла, extension_dir, минорная версия PHP, архитектура или режим безопасности потоков Сравните php -i с выбранным драйверным файлом и временно используйте абсолютный путь для выделения ошибок пути
The specified module could not be found в Windows DLL драйвера или одна из его зависимостей недоступна Убедитесь, что DLL находится в extension_dir, установите соответствующую среду выполнения Visual C++ и проверьте все ещё отсутствующие зависимости DLL
undefined symbol или ошибка в разделяемой библиотеке на Linux или macOS Несоответствие сборки расширений и PHP или отсутствие зависимости ODBC Пересоберите с нужным php-config, затем проверьте библиотеку, указанную как отсутствующая
Module "sqlsrv" is already loaded Дублирующие записи или два отсканированных файла Ищите в загруженном php.ini и каталоге сканирования, затем оставьте одну запись
could not find driver от PDO PDO_SQLSRV не загружен, или PDO загружается после него Проверьте php --ri pdo_sqlsrv и переместите запись PDO_SQLSRV после PDO
CLI работает, но веб-запросы не работают Другая конфигурация SAPI или неперезапущенный процесс Сравните значения CLI и phpinfo() конфигурации, отредактируйте веб-конфигурацию и перезапустите веб-процесс
Старое ExtensionVer остается после обновления В конфигурации всё ещё указан более старый версионный файл Замените старый элемент на файл, установленный выбранным методом, удалите дубликаты и перезапустите все PHP-процессы

PHP отвечает за поиск расширений и порядок загрузки. PIE или копирование вручную предоставляет файл расширения. Загрузчик операционной системы обрабатывает нативные зависимости. Драйвер Microsoft ODBC управляет протоколом базы данных после загрузки расширения.

Связанные материалы

  • Последнее обновление: