Compartilhar via

Tutorial de instalação para Linux e macOS dos drivers da Microsoft para PHP no SQL Server

As instruções a seguir pressupõem um ambiente limpo e mostram como instalar o PHP 8.1, o driver ODBC da Microsoft, o servidor Web Apache e os Drivers da Microsoft para PHP para SQL Server no Ubuntu, Red Hat, Debian, SUSE, Alpine e macOS. Essas instruções aconselham a instalação dos drivers usando PECL, mas você também pode baixar os binários predefinidos da página de projeto Drivers da Microsoft para PHP para SQL Server gitHub e instalá-los seguindo as instruções em Carregar os Drivers da Microsoft para PHP para SQL Server. Para obter uma explicação sobre o carregamento de extensão e por que não adicionamos as extensões a php.ini, consulte a seção sobre como carregar os drivers.

As instruções a seguir instalam o PHP 8.1 por padrão usando pecl install, se os pacotes PHP 8.1 estiverem disponíveis. Talvez seja necessário executar pecl channel-update pecl.php.net primeiro. Algumas distribuições Linux suportadas usam por padrão o PHP 7.1 ou versões anteriores, o que não é compatível com a última versão dos drivers PHP para SQL Server. Confira as anotações no início de cada seção para instalar o PHP 8.2 ou 8.3.

Também estão incluídas instruções para instalar o PhP FastCGI Process Manager, PHP-FPM, no Ubuntu. PHP-FPM é necessário se você estiver usando o servidor Web nginx em vez do Apache.

Embora essas instruções contenham comandos para instalar o SQLSRV e PDO_SQLSRV drivers, os drivers podem ser instalados e funcionar de forma independente. Os usuários confortáveis com a personalização de sua configuração podem ajustar essas instruções para serem específicos para SQLSRV ou PDO_SQLSRV. Ambos os drivers têm as mesmas dependências, exceto onde mencionado abaixo.

Consulte a Matriz de Suporte para a versão mais recente de sistemas operacionais com suporte.

Observação

Verifique se você instalou a versão mais recente do driver ODBC para garantir o desempenho e a segurança ideais. Para obter instruções de instalação, consulte Instalar o driver ODBC da Microsoft para SQL Server (Linux) ou instalar o driver ODBC da Microsoft para SQL Server (macOS).

Instalação no Ubuntu

Observação

Para instalar o PHP 8.2 ou 8.3, substitua 8.1 por 8.2 ou 8.3 nos comandos a seguir.

Etapa 1. Instalar o 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 sobre como instalar o driver ODBC da Microsoft para SQL Server (Linux). Instale também o unixodbc-dev pacote. Ele é usado pelo pecl comando 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

Se houver apenas uma versão php no sistema, a última etapa poderá ser simplificada para phpenmod sqlsrv pdo_sqlsrv.

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

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

Etapa 5. Reinicie o Apache e teste o script de exemplo (Ubuntu)

sudo service apache2 restart

Para testar sua instalação, consulte Testando sua instalação no final deste documento.

Instalação no Ubuntu com PHP-FPM

Observação

Para instalar o PHP 8.2 ou 8.3, substitua 8.1 por 8.2 ou 8.3 nos comandos a seguir.

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 do serviço 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 sobre como instalar o driver ODBC da Microsoft para SQL Server (Linux). Instale também o unixodbc-dev pacote. Ele é usado pelo pecl comando 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

Se houver apenas uma versão php no sistema, a última etapa poderá ser simplificada para phpenmod sqlsrv pdo_sqlsrv.

Verifique que 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 PHP-FPM:

sudo systemctl restart php8.1-fpm

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

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

Para configurar o nginx, você deve editar o /etc/nginx/sites-available/default arquivo. Adicione index.php à lista abaixo a seção que diz # 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, descomente e modifique a seção após # pass PHP scripts to FastCGI server da seguinte maneira:

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

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

sudo systemctl restart nginx.service

Para testar sua instalação, consulte Testando sua instalação no final deste documento.

Instalação no Red Hat

Etapa 1. Instalar o PHP (Red Hat)

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

Observação

Para instalar o PHP 8.2 ou 8.3, substitua remi-php81 por remi-php82 ou remi-php83, respectivamente, nos comandos a seguir.

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:

Observação

Para instalar o PHP 8.2 ou 8.3, substitua remi-8.1 por remi-8.2 ou remi-8.3, respectivamente, nos comandos a seguir.

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 sobre como instalar o driver ODBC da Microsoft para SQL Server (Linux). Instale também o unixodbc-dev pacote. Ele é usado pelo pecl comando para instalar os drivers PHP.

Etapa 3. Instalar os drivers PHP para o 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, você pode instalar no 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 a bancos de dados por meio do SELinux, execute o seguinte comando:

sudo setsebool -P httpd_can_network_connect_db 1

Etapa 5. Reinicie o Apache e teste o script de exemplo (Red Hat)

sudo apachectl restart

Para testar sua instalação, consulte Testando sua instalação no final deste documento.

Instalando no Debian

Observação

Para instalar o PHP 8.2 ou 8.3, substitua 8.1 nos comandos a seguir por 8.2 ou 8.3.

Etapa 1. Instalar o 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 sobre como instalar o driver ODBC da Microsoft para SQL Server (Linux). Instale também o unixodbc-dev pacote. Ele é usado pelo pecl comando para instalar os drivers PHP.

Talvez você também precise gerar a localidade correta para que a saída do 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, pois o executável locale-gen está localizado lá.

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

Se houver apenas uma versão php no sistema, a última etapa poderá ser simplificada para phpenmod sqlsrv pdo_sqlsrv. Assim como em locale-gen, phpenmod está localizado em /usr/sbin, portanto, 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. Reinicie o Apache e teste o script de exemplo (Debian)

sudo service apache2 restart

Para testar sua instalação, consulte Testando sua instalação no final deste documento.

Instalando no SUSE

Observação

Nas instruções a seguir, substitua <SuseVersion> pela sua versão do SUSE – se você estiver usando o SUSE Linux Enterprise Server 15, ele será SLE_15_SP3 ou SLE_15_SP4 (ou superior). Para SUSE 12, use SLE_12_SP5 (ou uma versão superior). Nem todas as versões do PHP estão disponíveis para todas as versões do SUSE Linux . Consulte http://download.opensuse.org/repositories/devel:/languages:/php quais versões do SUSE têm a versão padrão PHP disponível ou verifique http://download.opensuse.org/repositories/devel:/languages:/php:/ quais outras versões do PHP estão disponíveis para quais versões do SUSE.

Observação

Os pacotes para PHP 7.4 ou superior não estão disponíveis para o SUSE 12, a partir de hoje.

Etapa 1. Instalar o 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 sobre como instalar o driver ODBC da Microsoft para SQL Server (Linux). Instale também o unixodbc-dev pacote. Ele é usado pelo pecl comando para instalar os drivers PHP.

Etapa 3. Instalar os drivers PHP para o 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 de 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 SUSE (script de exemplo)

sudo systemctl restart apache2

Para testar sua instalação, consulte Testando sua instalação no final deste documento.

Instalando no Alpine

Observação

O PHP 8.1 ou superior pode estar disponível em repositórios de teste ou repositórios experimentais para Alpine. Em vez disso, você pode compilar o PHP da origem.

Etapa 1. Instalar o PHP (Alpine)

Os pacotes PHP para Alpine podem ser encontrados no edge/community repositório. Verifique Habilitar Repositório de Comunidade em sua página WIKI. Adicione a seguinte linha em /etc/apk/repositories, substituindo <mirror> pela URL de um espelho de 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 sobre como instalar o driver ODBC da Microsoft para SQL Server (Linux). Instale também o unixodbc-dev pacote (sudo apk add unixodbc-dev). Ele é usado pelo pecl comando para instalar os drivers PHP.

Etapa 3. Instalar os drivers PHP para o 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. Reinicie o Apache e teste o script de exemplo (Alpine)

sudo rc-service apache2 restart

Para testar sua instalação, consulte Testando sua instalação no final deste documento.

Instalação no macOS

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

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

Observação

Para instalar o PHP 8.2 ou 8.3, substitua php@8.1 por php@8.2 ou php@8.3, respectivamente, nos comandos a seguir.

Etapa 1. Instalar o PHP (macOS)

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

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

brew link --force --overwrite php@8.1

Se estiver usando o Apple M1 ARM64, talvez seja 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 sobre como instalar o driver ODBC da Microsoft para SQL Server (macOS).

Observação

Se estiver usando o hardware do Apple M1 ARM64, instale o driver Microsoft ODBC 17.8+ diretamente sem usar o emulador Rosetta 2.

Além disso, talvez seja necessário instalar as ferramentas de criação de GNU:

brew install autoconf automake libtool

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

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv

Se estiver usando o Apple M1 ARM64, faça o seguinte em vez disso:

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)

Observação

O macOS 11.0 Big Sur mais recente vem com o Apache 2.4 pré-instalado, mas a Apple também removeu alguns scripts necessários. A solução é instalar o Apache 2.4 via Homebrew e configurá-lo, mas isso está fora do escopo deste guia de instalação, portanto, verifique o Apache ou o Homebrew para obter instruções detalhadas.

brew install apache2

Para localizar o arquivo de configuração do Apache, httpd.confpara 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 a httpd.conf. Substitua 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, consulte Testando sua instalação no final deste documento.

Testando sua instalação

Para testar esse script de exemplo, crie um arquivo chamado testsql.php na raiz do documento do sistema. Esse caminho está /var/www/html/ no Ubuntu, Debian e Red Hat, /srv/www/htdocs no SUSE, /var/www/localhost/htdocs no Alpine ou /usr/local/var/www no macOS. Copie o script a seguir para ele, 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ê deve ser capaz de se conectar ao banco de dados SQL Server/SQL do Azure. Se você não vir uma mensagem de êxito mostrando informações de versão do SQL, poderá fazer alguma solução de problemas básica 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, consulte os recursos de suporte para locais para ir.

Consulte Também

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

Carregando os Drivers da Microsoft para PHP para SQL Server

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

  • Last updated on