Установите драйверы Microsoft для PHP на Linux и macOS

Эти инструкции устанавливают PHP, драйвер ODBC Microsoft для SQL Server, а также расширения SQLSRV и PDO_SQLSRV. Каждая вкладка использует пакет PHP, предоставляемый репозиторием, из которого эта вкладка выполняет установку, поэтому версия, указанная в командах, отличается от вкладки к вкладке. Замените его на другую версию PHP, указанную в матрице поддержки, если в этом репозитории доступна другая версия PHP.

Драйверы SQLSRV и PDO_SQLSRV используют одну и ту же зависимость от ODBC и могут устанавливаться отдельно. Установите оба расширения, если ваше приложение использует оба драйвера.

В конце процедуры CLI и выбранная среда выполнения веб-сервера должны загрузить оба расширения, оба PHP-API должны быть доступны, а образец для каждого API должен вернуть версию сервера базы данных.

Перед началом

  1. Выберите версию PHP, поддерживаемую текущим драйвером и доступную для вашей операционной системы.

  2. Определитесь, какие среды выполнения PHP вам нужны:

    • CLI для скриптов, запланированных задач или воркеров.
    • Модуль Apache для PHP под Apache.
    • PHP-FPM для nginx или конфигурации Apache FastCGI.

  3. Проверьте архитектуру операционной системы. Опубликованные архивы Linux содержат бинарные файлы x64, а опубликованные архивы для macOS — бинарные файлы Arm64. Сборки PIE предназначены для установки PHP на компьютере и являются основным способом установки в этой статье.

  4. Установите драйвер Microsoft ODBC и пакет разработки unixODBC. Пакет Microsoft обеспечивает коммуникацию с базами данных. Пакет unixODBC предоставляет заголовки, необходимые для сборки SQLSRV и PDO_SQLSRV.

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

Менеджер пакетов платформы устанавливает PHP и необходимые нативные компоненты. PIE создаёт и устанавливает расширения PHP. Конфигурация PHP определяет, загружает ли их каждая среда выполнения. Драйвер ODBC обрабатывает обмен данными с базой данных и шифрование после загрузки расширения.

Установите драйверы с помощью PIE

PIE, PHP Installer for Extensions, является поддерживаемым установщиком расширений для текущих версий драйверов. Он заменяет устаревший рабочий процесс PHP Extension Community Library (PECL).

Выполните предварительные требования к платформе в следующих разделах перед установкой драйверов. Затем установите PIE и каждый драйвер отдельно:

Установка PIE

PIE работает на PHP 8.1 и более поздних версиях. Он может установить расширение в другую PHP-установку при выборе инструментов разработки этой установки.

Установите curl и GitHub CLI перед тем, как продолжить. Разделы платформы включают curl, тогда как минимальная установка может не содержать его.

Скачайте архив PIE PHP (PHAR) и проверьте его с помощью интерфейса командной строки GitHub (CLI) перед установкой или запуском:

pie_tmp=$(mktemp -d)
curl -fL --output "$pie_tmp/pie.phar" https://github.com/php/pie/releases/latest/download/pie.phar
gh attestation verify --owner php "$pie_tmp/pie.phar"

Продолжайте только при успешной проверке:

sudo install -m 755 "$pie_tmp/pie.phar" /usr/local/bin/pie
rm "$pie_tmp/pie.phar"
rmdir "$pie_tmp"
unset pie_tmp

Временный каталог является частным для вашего аккаунта. Если загрузка или проверка не удаётся, не устанавливайте и не запускайте PHAR. Удалите временный файл и папку перед повторной попыткой.

Убедитесь, что установленный PHAR работает с исполняемым файлом PHP, который вы собираетесь использовать:

php /usr/local/bin/pie --version

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

В Linux и macOS PIE проверяет наличие нужных ему компилятора и инструментов разработки PHP. Установите пакет разработки платформы ODBC и компилятор на C++ перед запуском PIE. Запускайте PIE в интерактивном терминале. Может запросить ваш sudo пароль, когда ему требуется разрешение на установку файлов в системные директории.

PIE ориентируется на PHP-установку, использованную для его вызова. Для версионной установки добавьте --with-php-config к каждой команде установки, чтобы выбрать инструменты разработки для этой версии. Например, используйте pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv тогда, когда предполагаемый инструмент — /usr/bin/php-config8.4. Примените тот же вариант к microsoft/pdo_sqlsrv. Alpine использует версионные исполняемые имена; следуйте командам Alpine вместо неверсионных команд в этом разделе.

Выполните по одной команде для каждого расширения. Эти команды используют стандартную установку PHP от PIE:

pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

PIE пытается включить каждое расширение через инструменты настройки PHP платформы или элемент конфигурации extension= и предупреждает, если это невозможно. PHP использует серверный интерфейс прикладного программирования (SAPI) для каждой среды выполнения. На Debian, Ubuntu и SUSE конфигурации командной строки, Apache и PHP FastCGI Process Manager (PHP-FPM) могут отличаться. Успешная установка из командной строки не подтверждает, что веб-сервер загружает драйверы.

Проверьте php --ini на наличие командной строки. Перед созданием временной phpinfo() страницы для веб-сервера ограничьте доступ к диагностической странице. Проверьте загруженный конфигурационный файл и отсканированные .ini файлы для каждой среды выполнения. Если записи отсутствуют, следуйте инструкциям в статье Загрузка драйверов в Linux и macOS, чтобы добавить их в правильном порядке загрузки. Перезагрузите веб-сервер или PHP-FPM после изменений конфигурации. Red Hat обычно использует php.ini совместно между SAPI, но проверьте активную конфигурацию перед тем, как полагаться на один PIE-запуск.

Установите на своей платформе

Выберите операционную систему и конфигурацию веб-сервера. Выполните шаги установки в этой вкладке, затем перейдите к разделу «Тестирование установки».

Установка в Ubuntu

Замечание

Следующие команды используют репозиторий packages.sury.org PHP, чтобы вы могли выбрать поддерживаемую версию PHP. Используйте официальные инструкции Microsoft, чтобы установить драйвер ODBC для вашего релиза Ubuntu.

Шаг 1. Установка PHP (Ubuntu)

sudo apt-get update
sudo apt-get install ca-certificates apt-transport-https curl gnupg2 lsb-release -y
sudo install -d -m 755 /etc/apt/keyrings
sudo curl -fsSL https://packages.sury.org/php/apt.gpg -o /etc/apt/keyrings/php.gpg
sudo chmod 644 /etc/apt/keyrings/php.gpg
echo "deb [signed-by=/etc/apt/keyrings/php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
sudo apt-get update
sudo apt-get install php8.4 php8.4-dev php8.4-xml -y

Шаг 2. Установка необходимых компонентов (Ubuntu)

Следуйте инструкциям в статье Установка драйвера Microsoft ODBC для SQL Server в Linux, затем установите заголовки разработки.

sudo apt-get install unixodbc-dev g++ make git -y

Шаг 3. Установите драйверы PHP для Microsoft SQL Server с PIE (Ubuntu)

Далее установите драйверы с помощью PIE, добавив --with-php-config=/usr/bin/php-config8.4 к обеим командам установки. Проверьте файлы конфигурации командной строки с php8.4 --ini.

/usr/local/bin/pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv
/usr/local/bin/pie install --with-php-config=/usr/bin/php-config8.4 microsoft/pdo_sqlsrv

Шаг 4. Установка Apache и настройка загрузки драйверов (Ubuntu)

sudo apt-get install apache2 libapache2-mod-php8.4 -y
sudo a2enmod php8.4

Шаг 5. Перезапустите Apache и проверьте пример скрипта (Ubuntu)

sudo systemctl restart apache2

Чтобы проверить установку, ознакомьтесь с разделом "Тестирование установки " в конце этого документа.

Устаревшая установка PECL

PECL объявлен устаревшим для текущих выпусков драйверов. Используйте PIE для новых установок и обновлений. Если существующее развертывание закреплено на PECL, поддерживайте версии пакетов в соответствии со средой выполнения PHP и планируйте переход на PIE.

Проверьте установку

Проверьте среду выполнения командной строки. На Alpine замените php на php84. Для установки PHP определённой версии на другом дистрибутиве используйте соответствующий исполняемый файл.

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

Обе --ri команды должны печатать информацию о модулях, включающую ExtensionVer. Список модулей должен содержать отдельные sqlsrv и pdo_sqlsrv строки.

Перед тестированием соединения проверьте обе поверхности API PHP с помощью verify-php-drivers.php:

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

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

exit($failed ? 1 : 0);

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

SQLSRV: loaded
PDO_SQLSRV: loaded

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

Чтобы проверить активное подключение, создайте файл с именем testsql.php в корневом каталоге документов вашей системы. Этот путь - /var/www/html в Ubuntu, Debian и Red Hat, /srv/www/htdocs в SUSE, /var/www/localhost/htdocs в Alpine или $(brew --prefix)/var/www в macOS. Перед запуском скрипта установите переменные среды SQL_SERVER_NAME, SQL_DATABASE, SQL_UID и SQL_PWD для процесса PHP. Не прописывайте жестко учетные данные в файле под корнем документа.

Для тестирования в командной строке используйте интерактивные подсказки для установки переменных среды без ввода пароля в историю оболочки.

При тестировании модуля Apache не храните учётные данные в обычно доступном для чтения конфигурационном файле сайта:

  1. Создайте приватный файл вне корня документа. Используйте свободное имя файла в каталоге конфигурации Apache. В Linux:

    sudo install -o root -g root -m 600 /dev/null /etc/apache2/php-sql-driver-test.conf

    В Red Hat замените /etc/apache2 на /etc/httpd. На macOS создайте файл из-под учётной записи, от имени которой запускается Apache Homebrew:

    install -m 600 /dev/null "$(brew --prefix)/etc/httpd/php-sql-driver-test.conf"

    Только владелец файла и root могут читать эти настройки. Аккаунт, который запускает Apache, должен уметь читать файл.

  2. Отредактируйте приватный файл в текстовом редакторе и добавьте следующие записи:

    SetEnv SQL_SERVER_NAME "tcp:<server>,1433"
SetEnv SQL_DATABASE "<database>"
SetEnv SQL_UID "<user_id>"
SetEnv SQL_PWD "<password>"

    Внутри аргументов с двойными кавычками пишите \\ для каждой литеральной обратной косой черты и \" для каждой литеральной двойной кавычки. Сохраняйте начальные и конечные пробелы внутри кавычек. Apache также заменяет ссылки ${NAME}. Если значение содержит эту последовательность или разрыв строки, используйте вместо этого командную строку. Для получения дополнительной информации см. экранирование и заключение в кавычки в конфигурации Apache.

  3. Внутри виртуального хоста сайта добавьте Files блок, включающий приватный файл только для testsql.php. Если виртуальный хост не настроен, разместите блок в конфигурации основного сервера. Замените placeholder на абсолютный путь приватного файла:

    <Files "testsql.php">
    Include "<absolute-path-to-private-file>"
</Files>

  4. Перезапустите Apache. После тестирования удалите добавленный блок Files, удалите приватный файл и снова перезапустите Apache. Сохранить несвязанные настройки сайта.

PHP-FPM по умолчанию очищает наследованные переменные среды, а nginx не передаёт свою среду в PHP-FPM. Используйте следующую процедуру Ubuntu или Red Hat только с изолированным тестовым PHP-FPM сервисом и пулом. Не добавляйте учетные данные тестов в сервис или пул, который запускает другие приложения: каждый скрипт в этом пуле может их прочитать. Если вы используете виртуальный хостинг, используйте тест в командной строке.

  1. Создайте root-файл вне корня документа, например /etc/php-sql-driver-test.env, и ограничьте доступ к нему:

    sudo touch /etc/php-sql-driver-test.env
sudo chmod 600 /etc/php-sql-driver-test.env

    Добавьте настройки соединения в файл:

    SQL_SERVER_NAME="tcp:<server>,1433"
SQL_DATABASE="<database>"
SQL_UID="<user_id>"
SQL_PWD="<password>"

    Оставьте каждый параметр в одной строке. Внутри двойных кавычек пишите \\ для каждой буквальной обратной черты и \" для каждой буквальной двойной кавычки. Долларовые знаки и обратные апострофы не воспринимаются как выражения оболочки. Редактируйте файл напрямую, а не запускайте или подключайте его через source в оболочке. Для получения дополнительной информации см. синтаксис systemd EnvironmentFile.

  2. Запускайте sudo systemctl edit php8.4-fpm на Ubuntu или sudo systemctl edit php-fpm на Red Hat. Добавьте это переопределение systemd:

    [Service]
EnvironmentFile=/etc/php-sql-driver-test.env

  3. Добавьте эти записи в конфигурацию активного пула PHP-FPM. Распространённые локации — /etc/php/8.4/fpm/pool.d/www.conf на Ubuntu и /etc/php-fpm.d/www.conf на Red Hat:

    env[SQL_SERVER_NAME] = $SQL_SERVER_NAME
env[SQL_DATABASE] = $SQL_DATABASE
env[SQL_UID] = $SQL_UID
env[SQL_PWD] = $SQL_PWD

  4. Перезагрузите systemd и перезапустите соответствующий сервис PHP-FPM:

    sudo systemctl daemon-reload
sudo systemctl restart php8.4-fpm

    В Red Hat замените php8.4-fpm на php-fpm.

После тестирования удалите временный файл среды, добавленную EnvironmentFile= запись, записи тестового пула и testsql.php. Удаляйте файл перенастройки сервиса только если вы создали его для этого теста и в нём нет других настроек. Сохраняйте все уже существующие переопределения и настройки пула. Перезагрузите systemd и перезапустите PHP-FPM после удаления тестовой конфигурации.

Пример SQLSRV

Сохраняйте значения переменных окружения без изменений. Каждый пример проверяет наличие и непустоту настроек перед подключением. Каждый пример затем удваивает замыкающие скобки и добавляет внешние скобы перед передачей драйверу имени базы данных, пользователя и пароля. Такое кодирование сохраняет буквальные скобки и предотвращает разделение параметров подключения точками с запятой.

<?php
$serverName = getenv('SQL_SERVER_NAME');
$databaseName = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $databaseName === false || $databaseName === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    handle_failure("Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD.");
}

$databaseName = '{' . str_replace('}', '}}', $databaseName) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';
$connectionOptions = array(
    "Database" => $databaseName,
    "UID" => $uid,
    "PWD" => $pwd,
    "Encrypt" => 1,
    "TrustServerCertificate" => 0
);

function handle_failure($message) {
    error_log($message);
    http_response_code(500);
    echo "<h1>Failure</h1>";
    echo "An error occurred. Check the server error log for details.";
    exit(1);
}

function format_errors($errors) {
    $lines = [];
    foreach ($errors as $error) {
        $lines[] = "SQLSTATE: {$error['SQLSTATE']}, code: {$error['code']}, message: {$error['message']}";
    }
    return implode(PHP_EOL, $lines);
}

$conn = sqlsrv_connect($serverName, $connectionOptions);
if ($conn === false) {
    handle_failure(format_errors(sqlsrv_errors()));
}

$tsql = "SELECT @@Version AS SQL_VERSION";

$stmt = sqlsrv_query($conn, $tsql);
if ($stmt === false) {
    handle_failure(format_errors(sqlsrv_errors()));
}

$row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
if ($row === null || $row === false) {
    handle_failure("Query returned no rows.");
}

echo "<h1>Success</h1>";
echo htmlspecialchars($row['SQL_VERSION']);

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);
?>

Пример PDO_SQLSRV

<?php
$serverName = getenv('SQL_SERVER_NAME');
$databaseName = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $databaseName === false || $databaseName === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    handle_failure(new RuntimeException("Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD."));
}

$databaseName = '{' . str_replace('}', '}}', $databaseName) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';

function handle_failure($exception) {
    error_log($exception->getMessage());
    http_response_code(500);
    echo "<h1>Failure</h1>";
    echo "An error occurred. Check the server error log for details.";
    exit(1);
}

try {
    $conn = new PDO(
        "sqlsrv:server=$serverName;Database=$databaseName;Encrypt=1;TrustServerCertificate=0",
        $uid,
        $pwd
    );
    $conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    $tsql = "SELECT @@Version AS SQL_VERSION";

    $stmt = $conn->query($tsql);
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException("Query returned no rows.");
    }

    echo "<h1>Success</h1>";
    echo htmlspecialchars($row['SQL_VERSION']);
} catch (Throwable $exception) {
    handle_failure($exception);
}

unset($stmt);
unset($conn);
?>

Укажите браузер http://localhost/testsql.php (http://localhost:8080/testsql.php в macOS). Успешное соединение отображает строку версии сервера базы данных. Оба примера записывают детали ошибок в журнал ошибок PHP. Если страница показывает сбой, проверьте этот журнал.

Чтобы сравнить поведение командной строки и веб-сервера, установите одни и те же переменные среды для терминала и запустите:

php testsql.php

Если запуск из командной строки успешен, но в браузере ничего не появляется, проверьте лог-файлы Apache. Для получения дополнительной информации смотрите ресурсы поддержки драйвера PHP SQL.

Оценивайте программы подключения отдельно для SQL Server, База данных SQL Azure, Управляемый экземпляр SQL Azure, Azure Synapse Analytics, SQL database в Microsoft Fabric и Хранилище в Microsoft Fabric. Выбранный метод аутентификации, опции соединения и запрос должны поддерживаться целевым объектом. Установка осуществляется на стороне клиента. Успешная проверка расширения не доказывает, что целевой сервер принимает учетные данные, доверяет клиенту или поддерживает все функции базы данных.

Устранение неполадок, связанных с установкой

Симптом Владеющий слой Корректирующее действие
PIE не может найти phpize, php-configили заголовки Пакеты разработки на PHP Установите пакет разработки для целевой версии PHP и передайте соответствующий параметр --with-php-config
Компиляция не удаётся из-за отсутствия компилятора C++ Инструменты сборки ОС Установите пакет компилятора платформы C++, например g++ или gcc-c++
Компилятор не может найти sql.h Пакет разработки ODBC или пути компилятора Установите unixodbc-dev или unixODBC-devel; на Apple silicon установите флаги include и library для Homebrew
php --ri говорит, что расширение отсутствует Конфигурация PHP Проверьте загруженный объект php.ini и директорию сканирования, добавьте правильную запись и заново запустите процесс
Отчёты PDO could not find driver Загрузка PDO_SQLSRV или порядок загрузки PDO Сначала подтвердите загрузку PDO и убедитесь, что PDO_SQLSRV использует более поздно сканируемый конфигурационный файл
CLI работает, но Apache, nginx или PHP-FPM не работает Конфигурация для SAPI Сравните вывод CLI с phpinfo(), настройте веб-SAPI и перезапустите его
Браузер получает HTTP 502 от nginx Маршрутизация NGINX в PHP-FPM Проверьте fastcgi_pass сокет по сравнению с установленной версией PHP-FPM и убедитесь, что сервис работает
Пример браузера сообщает об отсутствующих значениях среды Веб-сервер или среда PHP-FPM Настройте переменные для выбранной веб-среды выполнения, затем перезапустите её
Расширения загружаются, но не удаётся подключиться ODBC, сеть, сертификат, аутентификация или продукт SQL Читайте SQLSTATE и нативную ошибку из лога сервера; не перестраивайте расширение, если ошибка не указывает на проблему загрузки или бинарной совместимости

Удалить временную тестовую конфигурацию

После проверки:

  1. Удалите testsql.php, verify-php-drivers.php, и любую временную phpinfo() страницу из корня документа.

  2. Удалите временные учетные данные и записи перенаправления переменных окружения.

  3. Перезагрузите менеджер сервисов после изменения файла переопределения systemd, затем перезапустите PHP-FPM или веб-сервер.

  4. Сохраняйте записи расширения и установленные пакеты, которые требуются приложению.

Связанный контент

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