Tutorial de instalação de Linux e macOS para Drivers da Microsoft para PHP para SQL Server

As instruções a seguir pressupõem que o ambiente esteja limpo e mostram como instalar o PHP 8.1, o Microsoft ODBC Driver, o servidor Web Apache e o Microsoft Drivers para PHP para SQL Server no Ubuntu, no Red Hat, no Debian, no SUSE, no Alpine e no macOS. Essas instruções aconselham a instalar os drivers usando PECL, mas também é possível baixar os binários predefinidos na página de projetos do GitHub Drivers da Microsoft para PHP e para SQL Server e instalá-los seguindo as instruções em Como carregar os Drivers da Microsoft para PHP e para SQL Server. Para obter uma explicação do carregamento da extensão e por que não adicionamos as extensões ao php.ini, confira a seção sobre carregar os drivers.

Se os pacotes do PHP 8.1 estiverem disponíveis, as instruções abaixo instalarão o PHP 8.1 por padrão usando pecl install. Talvez seja necessário executar primeiro pecl channel-update pecl.php.net. Algumas distribuições do Linux com suporte têm como padrão o PHP 7.1 ou anterior, que não tem suporte para a versão mais recente dos drivers PHP para o SQL Server. Como alternativa, confira as observações no início de cada seção para instalar o PHP 8.2 ou 8.3.

As instruções para instalar o Gerenciador de Processos do PHP FastCGI e o PHP-FPM no Ubuntu também estão incluídas. O PHP-FPM será necessário caso esteja usando um servidor Web nginx em vez do Apache.

Embora essas instruções contenham comandos para instalar os drivers SQLSRV e PDO_SQLSRV, os drivers podem ser instalados e funcionam de maneira independente. Usuários confortáveis com a personalização de suas configurações podem ajustar essas instruções para que sejam específicas a SQLSRV ou PDO_SQLSRV. Os dois drivers têm as mesmas dependências, exceto quando indicado abaixo.

Confira Matriz de Suporte para obter a versão mais recente dos sistemas operacionais com suporte.

Instalando no Ubuntu

Etapa 1. Instalar 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

Etapa 2. Instalar pré-requisitos (Ubuntu)

Instale o driver ODBC para Ubuntu seguindo as instruções do artigo Instalar o Microsoft ODBC Driver for SQL Server (Linux). Lembre-se de instalar também o pacote unixodbc-dev. Ele é usado pelo comando pecl para instalar os drivers PHP.

sudo apt-get install unixodbc-dev

Etapa 3. Instalar os drivers PHP para o 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

Caso haja somente uma versão do PHP no sistema, a última etapa poderá ser simplificada para phpenmod sqlsrv pdo_sqlsrv.

Etapa 4. Instalar o Apache e configurar o carregamento do driver (Ubuntu)

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

Etapa 5. Reiniciar o Apache e testar o script de exemplo (Ubuntu)

sudo service apache2 restart

Para testar sua instalação, confira Testar a instalação no final deste documento.

Como instalar no Ubuntu com PHP-FPM

Etapa 1. Instalar o PHP (Ubuntu com 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

Verifique o status de serviço do PHP-FPM executando:

systemctl status php8.1-fpm

Etapa 2. Instalar pré-requisitos (Ubuntu com PHP-FPM)

Instale o driver ODBC para Ubuntu seguindo as instruções do artigo Instalar o Microsoft ODBC Driver for SQL Server (Linux). Lembre-se de instalar também o pacote unixodbc-dev. Ele é usado pelo comando pecl para instalar os drivers PHP.

Etapa 3. Instalar os drivers PHP para o Microsoft SQL Server (Ubuntu com 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

Caso haja somente uma versão do PHP no sistema, a última etapa poderá ser simplificada para phpenmod sqlsrv pdo_sqlsrv.

Verifique se sqlsrv.ini e pdo_sqlsrv.ini estão localizados em /etc/php/8.1/fpm/conf.d/:

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

Reinicie o serviço do PHP-FPM:

sudo systemctl restart php8.1-fpm

Etapa 4. Instalar e configurar nginx (Ubuntu com PHP-FPM)

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

Para configurar o nginx será necessário editar o arquivo /etc/nginx/sites-available/default. Adicione index.php à lista abaixo da seção com o texto # 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;

Em seguida, remova a marca de comentário e modifique a seção de acordo com # pass PHP scripts to FastCGI server, conforme mostrado abaixo:

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

Etapa 5. Reiniciar o nginx e testar o script de exemplo (Ubuntu com PHP-FPM)

sudo systemctl restart nginx.service

Para testar sua instalação, confira Testar a instalação no final deste documento.

Como instalar no Red Hat

Etapa 1. Instalar PHP (Red Hat)

Para instalar o PHP no Red Hat 7, execute os seguintes comandos:

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

Para instalar o PHP no Red Hat 8, execute os seguintes comandos:

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

Etapa 2. Instalar pré-requisitos (Red Hat)

Instale o driver ODBC para Red Hat 7 ou 8 seguindo as instruções do artigo Instalar o Microsoft ODBC Driver for SQL Server (Linux). Lembre-se de instalar também o pacote unixodbc-dev. Ele é usado pelo comando pecl para instalar os drivers PHP.

Etapa 3. Instalar os drivers PHP para 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

Como alternativa é possível instalar usando o repositório Remi:

sudo yum install php-sqlsrv

Etapa 4. Instalar o Apache (Red Hat)

sudo yum install httpd

O SELinux é instalado por padrão e é executado no modo de imposição. Para permitir que o Apache se conecte aos bancos de dados por meio do SELinux, execute o seguinte comando:

sudo setsebool -P httpd_can_network_connect_db 1

Etapa 5. Reiniciar o Apache e testar o script de exemplo (Red Hat)

sudo apachectl restart

Para testar sua instalação, confira Testar a instalação no final deste documento.

Como instalar no Debian

Etapa 1. Instalar 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

Etapa 2. Instalar pré-requisitos (Debian)

Instale o driver ODBC para Debian seguindo as instruções do artigo Instalar o Microsoft ODBC Driver for SQL Server (Linux). Lembre-se de instalar também o pacote unixodbc-dev. Ele é usado pelo comando pecl para instalar os drivers PHP.

Você também precisa gerar a localidade correta para que uma saída PHP seja exibida corretamente em um navegador. Por exemplo, para a localidade en_US UTF-8, execute os seguintes comandos:

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

Talvez seja necessário adicionar /usr/sbin ao seu $PATH, já que o locale-gen executável está localizado lá.

Etapa 3. Instalar os drivers PHP para 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

Caso haja somente uma versão do PHP no sistema, a última etapa poderá ser simplificada para phpenmod sqlsrv pdo_sqlsrv. Assim como locale-gen, phpenmod está localizado em /usr/sbin, por isso, talvez seja necessário adicionar esse diretório ao seu $PATH.

Etapa 4. Instalar o Apache e configurar o carregamento do driver (Debian)

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

Etapa 5. Reiniciar o Apache e testar o script de exemplo (Debian)

sudo service apache2 restart

Para testar sua instalação, confira Testar a instalação no final deste documento.

Como instalar no SUSE

Etapa 1. Instalar 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

Etapa 2. Instalar pré-requisitos (SUSE)

Instale o driver ODBC para SUSE seguindo as instruções do artigo Instalar o Microsoft ODBC Driver for SQL Server (Linux). Lembre-se de instalar também o pacote unixodbc-dev. Ele é usado pelo comando pecl para instalar os drivers PHP.

Etapa 3. Instalar os drivers PHP para 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

Etapa 4. Instalar o Apache e configurar o carregamento do driver (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

Etapa 5. Reiniciar o Apache e testar o script de exemplo (SUSE)

sudo systemctl restart apache2

Para testar sua instalação, confira Testar a instalação no final deste documento.

Como instalar no Alpine

Etapa 1. Instalar PHP (Alpine)

Os pacotes PHP para Alpine podem ser encontrados no repositório edge/community. Confira Habilitar Repositório da Comunidade na página WIKI. Adicione a seguinte linha em /etc/apk/repositories, substituindo <mirror> pela URL de um espelho do repositório Alpine:

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

Em seguida, execute:

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

Etapa 2. Instalar pré-requisitos (Alpine)

Instale o driver ODBC para Alpine seguindo as instruções do artigo Instalar o Microsoft ODBC Driver for SQL Server (Linux). Lembre-se de instalar também o pacote unixodbc-dev (sudo apk add unixodbc-dev). Ele é usado pelo comando pecl para instalar os drivers PHP.

Etapa 3. Instalar os drivers PHP para 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

Etapa 4. Instalar o Apache e configurar o carregamento do driver (Alpine)

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

Etapa 5. Reiniciar o Apache e testar o script de exemplo (Alpine)

sudo rc-service apache2 restart

Para testar sua instalação, confira Testar a instalação no final deste documento.

Como instalar no macOS

Se você ainda não fez isso, instale o brew da seguinte maneira:

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

Etapa 1. Instalar PHP (macOS)

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

Agora, o PHP deve estar no seu caminho. Execute php -v para verificar se você está executando a versão correta do PHP. Se o PHP não estiver no seu caminho ou não tiver a versão correta, execute os seguintes comandos:

brew link --force --overwrite php@8.1

Ao usar o Apple M1 ARM64, pode ser necessário definir o caminho:

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

Etapa 2. Instalar pré-requisitos (macOS)

Instale o driver ODBC para macOS seguindo as instruções do artigo Instalar o Microsoft ODBC Driver for SQL Server (macOS).

Além disso, você precisa instalar as ferramentas de criação do GNU:

brew install autoconf automake libtool

Etapa 3. Instalar os drivers PHP para Microsoft SQL Server (macOS)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv

Se você estiver usando o Apple M1 ARM64, faça o seguinte:

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

Etapa 4. Instalar o Apache e configurar o carregamento do driver (macOS)

brew install apache2

Para localizar o arquivo de configuração do Apache, httpd.conf, para a instalação do Apache, execute:

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

Os comandos a seguir acrescentam a configuração necessária para httpd.conf. Certifique-se de substituir o caminho retornado pelo comando anterior no lugar de /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

Etapa 5. Reiniciar o Apache e testar o script de exemplo (macOS)

sudo apachectl restart

Para testar sua instalação, confira Testar a instalação no final deste documento.

Testar a instalação

Para testar esta amostra de script, crie um arquivo chamado testsql.php na raiz do documento do seu sistema. O caminho é /var/www/html/ no Ubuntu, Debian e RedHat, /srv/www/htdocs no SUSE, /var/www/localhost/htdocs no Alpine ou /usr/local/var/www no macOS. Copie o script a seguir para esse arquivo, substituindo o servidor, o banco de dados, o nome de usuário e a senha, conforme apropriado.

Exemplo com 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/>";
    }
}
?>

Exemplo com 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);
?>

Aponte seu navegador para https://localhost/testsql.php (https://localhost:8080/testsql.php no macOS). Agora, você pode se conectar ao banco de dados do SQL Server/SQL do Azure. Se não vir uma mensagem de êxito mostrando informações sobre a versão do SQL, você poderá realizar algumas soluções de problemas básicas executando o script na linha de comando:

php testsql.php

Se a execução da linha de comando for bem-sucedida, mas nada aparecer no navegador, verifique os arquivos de log do Apache. Para obter mais ajuda, confira os Recursos de suporte e veja ao que você pode recorrer.

Consulte Também

Introdução aos Drivers da Microsoft para PHP para SQL Server

Carregando os Microsoft Drivers for PHP for SQL Server

Requisitos do sistema para os Microsoft Drivers for PHP for SQL Server