Руководство по установке драйверов Майкрософт для PHP для SQL Server в Linux и MacOS

В следующих инструкциях предполагается чистая среда и показано, как установить PHP 8.1, драйвер Microsoft ODBC, веб-сервер Apache и драйверы Майкрософт для PHP для SQL Server в Ubuntu, Red Hat, Debian, SUSE, Alpine и macOS. В этих инструкциях рекомендуется установка драйверов с помощью PECL, но вы можете скачать предварительно созданные двоичные файлы со страницы проекта драйверов Майкрософт для PHP для SQL Server на сайте GitHub и установить их по инструкциям из статьи Loading the Microsoft Drivers for PHP for SQL Server (Загрузка драйверов Майкрософт для PHP для SQL Server). Описание процесса загрузки расширений и причины, по которым расширения не добавляются в файл php.ini, см. в статье о загрузке драйверов.

С помощью следующих инструкций производится установка PHP 8.1 по умолчанию с помощью pecl install, если доступны пакеты PHP 8.1. Возможно, потребуется сначала выполнить pecl channel-update pecl.php.net. Некоторые поддерживаемые дистрибутивы Linux по умолчанию используют PHP 7.1 или более ранних версий, которые не поддерживаются последней версией драйверов PHP для SQL Server. См. заметки в начале каждого раздела, чтобы установить PHP 8.2 или 8.3.

Также включены инструкции по установке диспетчера процессов PHP FastCGI (PHP-FPM) в Ubuntu. PHP-FPM требуется, если вместо Apache используется веб-сервер nginx.

Хотя эти инструкции содержат команды для установки драйверов SQLSRV и PDO_SQLSRV, драйверы можно устанавливать и выполнять независимо. Пользователи, имеющие опыт работы с настройкой конфигурации, могут настроить эти инструкции индивидуально для SQLSRV или PDO_SQLSRV. Оба драйвера имеют одинаковые зависимости, кроме указанных ниже.

См . раздел "Матрица поддержки" для последней поддерживаемой версии операционных систем.

Примечание.

Убедитесь, что установлена последняя версия драйвера ODBC, чтобы обеспечить оптимальную производительность и безопасность. Инструкции по установке см. в разделе "Установка драйвера Microsoft ODBC для SQL Server (Linux) или установка драйвера Microsoft ODBC для SQL Server (macOS)".

Установка на Ubuntu

Примечание.

Чтобы установить PHP 8.2 или 8.3, замените 8.1 на 8.2 или 8.3 в следующих командах.

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

sudo su
add-apt-repository ppa:ondrej/php -y
apt-get update
apt-get install php8.1 php8.1-dev php8.1-xml -y --allow-unauthenticated

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

Установите драйвер ODBC для Ubuntu, следуя инструкциям в статье Установка Microsoft ODBC Driver for SQL Server (Linux). Также обязательно установите пакет unixodbc-dev. Он используется командой pecl для установки драйверов PHP.

sudo apt-get install unixodbc-dev

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

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/8.1/mods-available/sqlsrv.ini
printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/8.1/mods-available/pdo_sqlsrv.ini
exit
sudo phpenmod -v 8.1 sqlsrv pdo_sqlsrv

Если в системе только одна версия PHP, последний шаг можно упростить: phpenmod sqlsrv pdo_sqlsrv.

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

sudo su
apt-get install libapache2-mod-php8.1 apache2
a2dismod mpm_event
a2enmod mpm_prefork
a2enmod php8.1
exit

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

sudo service apache2 restart

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

Установка в Ubuntu с PHP-FPM

Примечание.

Чтобы установить PHP 8.2 или 8.3, замените 8.1 на 8.2 или 8.3 в следующих командах.

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

sudo su
add-apt-repository ppa:ondrej/php -y
apt-get update
apt-get install php8.1 php8.1-dev php8.1-fpm php8.1-xml -y --allow-unauthenticated

Проверьте состояние службы PHP-FPM, выполнив следующее:

systemctl status php8.1-fpm

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

Установите драйвер ODBC для Ubuntu, следуя инструкциям в статье Установка Microsoft ODBC Driver for SQL Server (Linux). Также обязательно установите пакет unixodbc-dev. Он используется командой pecl для установки драйверов PHP.

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

sudo pecl config-set php_ini /etc/php/8.1/fpm/php.ini
sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/8.1/mods-available/sqlsrv.ini
printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/8.1/mods-available/pdo_sqlsrv.ini
exit
sudo phpenmod -v 8.1 sqlsrv pdo_sqlsrv

Если в системе только одна версия PHP, последний шаг можно упростить: phpenmod sqlsrv pdo_sqlsrv.

Убедитесь, что sqlsrv.ini и pdo_sqlsrv.ini находятся в /etc/php/8.1/fpm/conf.d/:

ls /etc/php/8.1/fpm/conf.d/*sqlsrv.ini

Перезапустите службу PHP-FPM:

sudo systemctl restart php8.1-fpm

Шаг 4. Установка и настройка nginx (Ubuntu с PHP-FPM)

sudo apt-get update
sudo apt-get install nginx
sudo systemctl status nginx

Чтобы настроить nginx, необходимо изменить файл /etc/nginx/sites-available/default. Добавьте index.php в список под разделом со следующим текстом: # Add index.php to the list if you are using PHP:

# Add index.php to the list if you are using PHP
index index.html index.htm index.nginx-debian.html index.php;

Затем раскомментируйте и измените раздел после # pass PHP scripts to FastCGI server следующим образом:

# pass PHP scripts to FastCGI server
#
location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
}

Шаг 5. Перезапуск nginx и тестирование примера скрипта (Ubuntu с PHP-FPM)

sudo systemctl restart nginx.service

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

Установка в Red Hat

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

Чтобы установить PHP в Red Hat 7, выполните следующие команды:

Примечание.

Чтобы установить PHP 8.2 или 8.3, замените remi-php81 на remi-php82 или remi-php83 соответственно в следующих командах.

sudo su
yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum install https://rpms.remirepo.net/enterprise/remi-release-7.rpm
subscription-manager repos --enable=rhel-7-server-optional-rpms
yum install yum-utils
yum-config-manager --enable remi-php81
yum update
# Note: The php-pdo package is required only for the PDO_SQLSRV driver
yum install php php-pdo php-pear php-devel

Чтобы установить PHP в Red Hat 8, выполните следующие команды:

Примечание.

Чтобы установить PHP 8.2 или 8.3, замените remi-8.1 на remi-8.2 или remi-8.3 соответственно в следующих командах.

sudo su
dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
dnf install https://rpms.remirepo.net/enterprise/remi-release-8.rpm
dnf install yum-utils
dnf module reset php
dnf module install php:remi-8.1
subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms
dnf update
# Note: The php-pdo package is required only for the PDO_SQLSRV driver
dnf install php-pdo php-pear php-devel

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

Установите драйвер ODBC для Red Hat 7 или 8, следуя инструкциям в статье Установка Microsoft ODBC Driver for SQL Server (Linux). Также обязательно установите пакет unixodbc-dev. Он используется командой pecl для установки драйверов PHP.

Шаг 3. Установка драйверов PHP для Microsoft SQL Server (Red Hat)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
echo extension=pdo_sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/30-pdo_sqlsrv.ini
echo extension=sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/20-sqlsrv.ini
exit

Можно также установить их из репозитория Remi:

sudo yum install php-sqlsrv

Шаг 4. Установка Apache (Red Hat)

sudo yum install httpd

SELinux устанавливается по умолчанию и выполняется в принудительном режиме. Чтобы разрешить Apache подключаться к базам данных через SELinux, выполните следующую команду:

sudo setsebool -P httpd_can_network_connect_db 1

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

sudo apachectl restart

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

Установка в Debian

Примечание.

Чтобы установить PHP 8.2 или 8.3, замените 8.1 в следующих командах 8.2 или 8.3.

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

sudo su
apt-get install curl apt-transport-https
wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list
apt-get update
apt-get install -y php8.1 php8.1-dev php8.1-xml php8.1-intl

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

Установите драйвер ODBC для Debian, следуя инструкциям в статье Установка Microsoft ODBC Driver for SQL Server (Linux). Также обязательно установите пакет unixodbc-dev. Он используется командой pecl для установки драйверов PHP.

Кроме того, может потребоваться создать правильный языковой стандарт, чтобы выходные данные PHP правильно отображались в браузере. Например, для языкового стандарта en_US UTF-8 выполните следующие команды:

sudo su
sed -i 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/g' /etc/locale.gen
locale-gen

Может потребоваться добавить /usr/sbin в $PATH, так как там находится исполняемый файл locale-gen.

Шаг 3. Установка драйверов PHP для Microsoft SQL Server (Debian)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/8.1/mods-available/sqlsrv.ini
printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/8.1/mods-available/pdo_sqlsrv.ini
exit
sudo phpenmod -v 8.1 sqlsrv pdo_sqlsrv

Если в системе только одна версия PHP, последний шаг можно упростить: phpenmod sqlsrv pdo_sqlsrv. Как и в случае с locale-gen, phpenmod находится в /usr/sbin, поэтому может потребоваться добавить этот каталог в $PATH.

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

sudo su
apt-get install libapache2-mod-php8.1 apache2
a2dismod mpm_event
a2enmod mpm_prefork
a2enmod php8.1

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

sudo service apache2 restart

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

Установка в SUSE

Примечание.

В следующих инструкциях замените <SuseVersion> версию SUSE — если вы используете SUSE Linux Enterprise Server 15, она будет SLE_15_SP3 или SLE_15_SP4 (или выше). Для SUSE 12 используйте SLE_12_SP5 (или более поздней версии). Не все версии PHP доступны для всех версий SUSE Linux. См. сведения http://download.opensuse.org/repositories/devel:/languages:/php о том, какие версии SUSE доступны по умолчанию, или проверкаhttp://download.opensuse.org/repositories/devel:/languages:/php:/, чтобы узнать, какие другие версии PHP доступны для каких версий SUSE.

Примечание.

Пакеты для PHP 7.4 или более поздней версии недоступны для SUSE 12 по состоянию на сегодняшний день.

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

sudo su
zypper -n ar -f https://download.opensuse.org/repositories/devel:languages:php/<SuseVersion>/devel:languages:php.repo
zypper --gpg-auto-import-keys refresh
zypper -n install php8 php8-pdo php8-devel php8-openssl

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

Установите драйвер ODBC для SUSE, следуя инструкциям по установке драйвера Microsoft ODBC для SQL Server (Linux). Также обязательно установите пакет unixodbc-dev. Он используется командой pecl для установки драйверов PHP.

Шаг 3. Установка драйверов PHP для Microsoft SQL Server (SUSE)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
echo extension=pdo_sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/pdo_sqlsrv.ini
echo extension=sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/sqlsrv.ini
exit

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

sudo su
zypper install apache2 apache2-mod_php8
a2enmod php8
echo "extension=sqlsrv.so" >> /etc/php8/apache2/php.ini
echo "extension=pdo_sqlsrv.so" >> /etc/php8/apache2/php.ini
exit

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

sudo systemctl restart apache2

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

Установка в Alpine

Примечание.

PHP версии 8.1 или более поздней может быть доступен в тестовых или пограничных репозиториях для Alpine. Вместо этого можно скомпилировать PHP из источника.

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

Пакеты PHP для Alpine находятся в репозитории edge/community. Проверьте раздел Включить репозиторий сообщества на их вики-странице. Добавьте следующую строку в /etc/apk/repositories, заменив <mirror> на URL-адрес зеркального отображения репозитория Alpine:

http://<mirror>/alpine/edge/community

Затем запустите:

sudo su
apk update
# Note: The php*-pdo package is required only for the PDO_SQLSRV driver
# For PHP 7.*
apk add php7 php7-dev php7-pear php7-pdo php7-openssl autoconf make g++
# For PHP 8.*
apk add php8 php8-dev php8-pear php8-pdo php8-openssl autoconf make g++
# The following symbolic links are optional but useful
ln -s /usr/bin/php8 /usr/bin/php
ln -s /usr/bin/phpize8 /usr/bin/phpize
ln -s /usr/bin/pecl8 /usr/bin/pecl
ln -s /usr/bin/php-config8 /usr/bin/php-config

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

Установите драйвер ODBC для Alpine, следуя инструкциям в статье Установка Microsoft ODBC Driver for SQL Server (Linux). Также обязательно установите пакет unixodbc-dev (sudo apk add unixodbc-dev). Он используется командой pecl для установки драйверов PHP.

Шаг 3. Установка драйверов PHP для Microsoft SQL Server (Alpine)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
echo extension=pdo_sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/10_pdo_sqlsrv.ini
echo extension=sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/20_sqlsrv.ini

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

# For PHP 7.*
sudo apk add php7-apache2 apache2
# For PHP 8.*
sudo apk add php8-apache2 apache2

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

sudo rc-service apache2 restart

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

Установка в macOS

Установите brew, как описано ниже, если у вас ее еще нет:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Примечание.

Чтобы установить PHP 8.2 или 8.3, замените php@8.1 на php@8.2 или php@8.3 соответственно в следующих командах.

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

brew tap
brew tap homebrew/core
brew install php@8.1

PHP теперь должен быть указан в пути. Запустите php -v и убедитесь, что используется правильная версия PHP. Если в пути нет PHP или есть PHP неправильной версии, выполните следующие команды:

brew link --force --overwrite php@8.1

При использовании Apple M1 ARM64 может потребоваться задать путь:

export PATH="/opt/homebrew/bin:$PATH"

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

Установите драйвер ODBC для macOS, следуя инструкциям в статье Установка Microsoft ODBC Driver for SQL Server (macOS).

Примечание.

Если вы используете оборудование Apple M1 ARM64, установите драйвер Microsoft ODBC версии 17.8 или более поздней напрямую без эмулятора Rosetta 2.

Кроме того, может потребоваться установить средства make для GNU:

brew install autoconf automake libtool

Шаг 3. Установка драйверов PHP для Microsoft SQL Server (macOS)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv

Если вы используете Apple M1 ARM64, вместо этого выполните следующие действия.

sudo CXXFLAGS="-I/opt/homebrew/opt/unixodbc/include/" LDFLAGS="-L/opt/homebrew/lib/" pecl install sqlsrv
sudo CXXFLAGS="-I/opt/homebrew/opt/unixodbc/include/" LDFLAGS="-L/opt/homebrew/lib/" pecl install pdo_sqlsrv

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

Примечание.

Последняя версия macOS 11.0 Big Sur поставляется с предварительно установленным Apache 2.4, но компания Apple удалила некоторые необходимые сценарии. Можно установить и настроить Apache 2.4 через Homebrew. Эти действия здесь не описаны, поэтому для получения подробных сведений ознакомьтесь с руководствами Apache или Homebrew.

brew install apache2

Чтобы найти файл конфигурации Apache (httpd.conf) для установки Apache, выполните следующую команду:

/usr/local/bin/apachectl -V | grep SERVER_CONFIG_FILE

Следующие команды добавляют необходимую конфигурацию в httpd.conf. Не забудьте указать путь, возвращенный предыдущей командой, вместо /usr/local/etc/httpd/httpd.conf:

echo "LoadModule php7_module /usr/local/opt/php@8.1/lib/httpd/modules/libphp7.so" >> /usr/local/etc/httpd/httpd.conf
(echo "<FilesMatch .php$>"; echo "SetHandler application/x-httpd-php"; echo "</FilesMatch>";) >> /usr/local/etc/httpd/httpd.conf

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

sudo apachectl restart

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

Тестирование установки

Чтобы протестировать этот пример скрипта, создайте файл с именем testsql.php в корневом каталоге документов системы. Это путь /var/www/html/ в Ubuntu, Debian и Red Hat, /srv/www/htdocs в Suse, /var/www/localhost/htdocs в Alpine и /usr/local/var/www в macOS. Скопируйте приведенный ниже скрипт, заменив имя сервера, имя базы данных, имя пользователя и пароль правильными значениями.

Пример SQLSRV

<?php
$serverName = "yourServername";
$connectionOptions = array(
    "database" => "yourDatabase",
    "uid" => "yourUsername",
    "pwd" => "yourPassword"
);

function exception_handler($exception) {
    echo "<h1>Failure</h1>";
    echo "Uncaught exception: " , $exception->getMessage();
    echo "<h1>PHP Info for troubleshooting</h1>";
    phpinfo();
}

set_exception_handler('exception_handler');

// Establishes the connection
$conn = sqlsrv_connect($serverName, $connectionOptions);
if ($conn === false) {
    die(formatErrors(sqlsrv_errors()));
}

// Select Query
$tsql = "SELECT @@Version AS SQL_VERSION";

// Executes the query
$stmt = sqlsrv_query($conn, $tsql);

// Error handling
if ($stmt === false) {
    die(formatErrors(sqlsrv_errors()));
}
?>

<h1> Success Results : </h1>

<?php
while ($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC)) {
    echo $row['SQL_VERSION'] . PHP_EOL;
}

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

function formatErrors($errors)
{
    // Display errors
    echo "<h1>SQL Error:</h1>";
    echo "Error information: <br/>";
    foreach ($errors as $error) {
        echo "SQLSTATE: ". $error['SQLSTATE'] . "<br/>";
        echo "Code: ". $error['code'] . "<br/>";
        echo "Message: ". $error['message'] . "<br/>";
    }
}
?>

Пример PDO_SQLSRV

<?php
try {
    $serverName = "yourServername";
    $databaseName = "yourDatabase";
    $uid = "yourUsername";
    $pwd = "yourPassword";
    
    $conn = new PDO("sqlsrv:server = $serverName; Database = $databaseName;", $uid, $pwd);

    // Select Query
    $tsql = "SELECT @@Version AS SQL_VERSION";

    // Executes the query
    $stmt = $conn->query($tsql);
} catch (PDOException $exception1) {
    echo "<h1>Caught PDO exception:</h1>";
    echo $exception1->getMessage() . PHP_EOL;
    echo "<h1>PHP Info for troubleshooting</h1>";
    phpinfo();
}

?>

<h1> Success Results : </h1>

<?php
try {
    while ($row = $stmt->fetch(PDO::FETCH_ASSOC)) {
        echo $row['SQL_VERSION'] . PHP_EOL;
    }
} catch (PDOException $exception2) {
    // Display errors
    echo "<h1>Caught PDO exception:</h1>";
    echo $exception2->getMessage() . PHP_EOL;
}

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

Перейдите в браузере на страницу https://localhost/testsql.php (https://localhost:8080/testsql.php в Mac OS). Теперь вы сможете подключиться к базе данных SQL Server или SQL Azure. Если вы не видите сообщение об успешном выполнении с информацией о версии SQL, выполните основные действия по устранению неполадок, запустив скрипт из командной строки:

php testsql.php

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

См. также

Getting Started with the Microsoft Drivers for PHP for SQL Server (Начало работы с драйверами Майкрософт для PHP для SQL Server)

Загрузка драйверов Майкрософт для PHP для SQL Server

Системные требования драйверов Майкрософт для PHP для SQL Server