Partilhar via

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

As instruções seguintes assumem um ambiente limpo e mostram como instalar o PHP 8.1, o driver Microsoft ODBC, o servidor web Apache e os drivers Microsoft para PHP para SQL Server no Ubuntu, Red Hat, Debian, SUSE, Alpine e macOS. Estas instruções aconselham a instalar os drivers usando PECL, mas também pode descarregar os binários pré-construídos da página do projeto Microsoft Drivers for PHP for SQL Server no GitHub e instalá-los seguindo as instruções em Loading the Microsoft Drivers for PHP for SQL Server. Para uma explicação sobre o carregamento das extensões e porque não adicionamos as extensões a php.ini, veja a secção sobre o carregamento dos drivers.

As instruções seguintes instalam por padrão o PHP 8.1 usando pecl install, se os pacotes PHP 8.1 estiverem disponíveis. Talvez precises de executar pecl channel-update pecl.php.net primeiro. Algumas distribuições Linux suportadas têm por defeito PHP 7.1 ou versões anteriores, que não são compatíveis com a última versão dos drivers PHP para SQL Server. Consulte as notas no início de cada secção para instalar PHP 8.2 ou 8.3 em vez disso.

Também estão incluídas instruções para instalar o PHP FastCGI Process Manager, PHP-FPM, no Ubuntu. PHP-FPM é necessário se estiveres a usar o servidor web nginx em vez do Apache.

Embora estas instruções contenham comandos para instalar tanto os drivers SQLSRV como PDO_SQLSRV, os drivers podem ser instalados e funcionar de forma independente. Utilizadores confortáveis em personalizar a sua configuração podem ajustar estas instruções para serem específicas para SQLSRV ou PDO_SQLSRV. Ambos os drivers têm as mesmas dependências, exceto onde indicado abaixo.

Por favor, consulte a Matriz de Suporte para a versão mais recente do sistema operativo suportada.

Observação

Certifique-se de que instalou a versão mais recente do driver ODBC para garantir desempenho e segurança ótimos. Para instruções de instalação, consulte Instalar o driver Microsoft ODBC para SQL Server (Linux) ou Instalar o driver Microsoft ODBC para SQL Server (macOS).

Instalação no Ubuntu

Observação

Para instalar PHP 8.2 ou 8.3, substitua 8.1 por 8.2 ou 8.3 nos comandos seguintes.

Passo 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

Passo 2. Pré-requisitos para instalação (Ubuntu)

Instale o driver ODBC para Ubuntu seguindo as instruções em Instalar o driver Microsoft ODBC para SQL Server (Linux). Certifica-te também de instalar o unixodbc-dev pacote. É usado pelo pecl comando para instalar os drivers PHP.

sudo apt-get install unixodbc-dev

Passo 3. Instale os drivers PHP para 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 existir apenas uma versão PHP no sistema, então o último passo pode ser simplificado para phpenmod sqlsrv pdo_sqlsrv.

Passo 4. Instalar o Apache e configurar o carregamento dos drivers (Ubuntu)

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

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

sudo service apache2 restart

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

Instalar no Ubuntu com PHP-FPM

Observação

Para instalar PHP 8.2 ou 8.3, substitua 8.1 por 8.2 ou 8.3 nos comandos seguintes.

Passo 1. Instalar 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 estado do serviço PHP-FPM executando:

systemctl status php8.1-fpm

Passo 2. Pré-requisitos para instalação (Ubuntu com PHP-FPM)

Instale o driver ODBC para Ubuntu seguindo as instruções em Instalar o driver Microsoft ODBC para SQL Server (Linux). Certifica-te também de instalar o unixodbc-dev pacote. É usado pelo pecl comando para instalar os drivers PHP.

Passo 3. Instale os drivers PHP para 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 existir apenas uma versão PHP no sistema, então o último passo pode ser simplificado para phpenmod sqlsrv pdo_sqlsrv.

Verifique isso 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

Passo 4. Instale e configure o nginx (Ubuntu com PHP-FPM)

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

Para configurar nginx, tens de editar o /etc/nginx/sites-available/default ficheiro. Adicione index.php à lista abaixo a secçã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;

De seguida, descomenta e modifica a secção seguinte # pass PHP scripts to FastCGI server da seguinte forma:

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

Passo 5. Reinicia o nginx e testa o script de exemplo (Ubuntu com PHP-FPM)

sudo systemctl restart nginx.service

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

Instalação na Red Hat

Passo 1. Instalar PHP (Red Hat)

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

Observação

Para instalar PHP 8.2 ou 8.3, substitua remi-php81 por remi-php82 ou remi-php83, respetivamente, nos comandos seguintes.

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 PHP 8.2 ou 8.3, substitua remi-8.1 por remi-8.2 ou remi-8.3 respetivamente nos comandos seguintes.

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

Passo 2. Pré-requisitos para instalação (Red Hat)

Instale o driver ODBC para Red Hat 7 ou 8 seguindo as instruções em Instalar o driver Microsoft ODBC para SQL Server (Linux). Certifica-te também de instalar o unixodbc-dev pacote. É usado pelo pecl comando para instalar os drivers PHP.

Passo 3. Instale 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

Podes instalar a partir do repositório Remi:

sudo yum install php-sqlsrv

Passo 4. Instalar o Apache (Red Hat)

sudo yum install httpd

O SELinux está instalado por defeito e corre em modo de imposição. Para permitir que o Apache se ligue a bases de dados através do SELinux, execute o seguinte comando:

sudo setsebool -P httpd_can_network_connect_db 1

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

sudo apachectl restart

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

Instalação no Debian

Observação

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

Passo 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

Passo 2. Pré-requisitos de instalação (Debian)

Instale o driver ODBC para Debian seguindo as instruções em Instalar o driver Microsoft ODBC para SQL Server (Linux). Certifica-te também de instalar o unixodbc-dev pacote. É usado pelo pecl comando para instalar os drivers PHP.

Também pode ser necessário gerar a localização correta para que a saída PHP seja exibida corretamente num navegador. Por exemplo, para o local 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

Pode ser necessário adicionar /usr/sbin ao seu $PATH, pois o locale-gen executável está localizado aí.

Passo 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

Se existir apenas uma versão PHP no sistema, então o último passo pode ser simplificado para phpenmod sqlsrv pdo_sqlsrv. Assim como locale-gen, phpenmod está localizado em /usr/sbin, por isso pode ser necessário adicionar este diretório ao seu $PATH.

Passo 4. Instalar o Apache e configurar o carregamento de drivers (Debian)

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

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

sudo service apache2 restart

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

Instalação no SUSE

Observação

Nas instruções seguintes, substitua <SuseVersion> pela sua versão do SUSE - se estiver a usar o SUSE Linux Enterprise Server 15, será SLE_15_SP3 ou SLE_15_SP4 (ou superior). Para SUSE 12, use SLE_12_SP5 (ou superior). Nem todas as versões do PHP estão disponíveis para todas as versões do SUSE Linux – por favor, consulte http://download.opensuse.org/repositories/devel:/languages:/php para ver 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.

Observação

Pacotes para PHP 7.4 ou superiores não estão disponíveis para SUSE 12, até hoje.

Passo 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

Passo 2. Pré-requisitos para instalação (SUSE)

Instale o driver ODBC para SUSE seguindo as instruções em Instalar o driver Microsoft ODBC para SQL Server (Linux). Certifica-te também de instalar o unixodbc-dev pacote. É usado pelo pecl comando para instalar os drivers PHP.

Passo 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

Passo 4. Instalar o Apache e configurar o carregamento dos drivers (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

Passo 5. Reinicie o Apache e teste o script de exemplo (SUSE)

sudo systemctl restart apache2

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

Instalação no Alpine

Observação

PHP 8.1 ou superior pode estar disponível em repositórios de teste ou edge para o Alpine. Pode, em vez disso, compilar PHP a partir da fonte.

Passo 1. Instalar PHP (Alpine)

Os pacotes PHP para Alpine podem ser encontrados no edge/community repositório. Verifique Ativar Repositório Comunitário na página WIKI deles. Adicione a seguinte linha a /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

Passo 2. Pré-requisitos para instalação (Alpine)

Instale o driver ODBC para Alpine seguindo as instruções em Instalar o driver Microsoft ODBC para SQL Server (Linux). Certifica-te também de instalar o unixodbc-dev pacote (sudo apk add unixodbc-dev). É usado pelo pecl comando para instalar os drivers PHP.

Passo 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

Passo 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

Passo 5. Reinicie o Apache e teste o script de exemplo (Alpine)

sudo rc-service apache2 restart

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

Instalação no macOS

Se ainda não o tiveres, instala o brew da seguinte forma:

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

Observação

Para instalar PHP 8.2 ou 8.3, substitua php@8.1 por php@8.2 ou php@8.3, respetivamente, nos comandos seguintes.

Passo 1. Instalar PHP (macOS)

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

O PHP deve agora estar no teu caminho. Executa php -v para verificar se estás a usar a versão correta do PHP. Se o PHP não estiver no seu caminho ou não for a versão correta, execute os seguintes comandos:

brew link --force --overwrite php@8.1

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

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

Passo 2. Pré-requisitos para instalação (macOS)

Instale o driver ODBC para macOS seguindo as instruções em Instalar o driver Microsoft ODBC para SQL Server (macOS).

Observação

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

Além disso, pode ser necessário instalar as ferramentas GNU make:

brew install autoconf automake libtool

Passo 3. Instale os drivers PHP para Microsoft SQL Server (macOS)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv

Se estiver a usar 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

Passo 4. Instalar o Apache e configurar o carregamento de drivers (macOS)

Observação

O mais recente macOS 11.0 Big Sur vem com o Apache 2.4 pré-instalado, mas a Apple também removeu alguns scripts obrigatórios. A solução é instalar o Apache 2.4 via Homebrew e depois configurá-lo, mas isto está fora do âmbito deste guia de instalação, por isso por favor consulte o Apache ou Homebrew para instruções detalhadas.

brew install apache2

Para encontrar o ficheiro de configuração do Apache, httpd.conf, para a sua instalação do Apache, execute:

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

Os seguintes comandos acrescentam a configuração necessária a httpd.conf. Certifique-se de substituir o caminho devolvido pelo comando anterior em vez 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

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

sudo apachectl restart

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

Testar a Sua Instalação

Para testar este script de exemplo, crie um ficheiro chamado testsql.php na raiz do documento do seu sistema. Este 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 seguinte para ele, substituindo o servidor, base de dados, nome de utilizador e palavra-passe conforme apropriado.

Exemplo de 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 exemplo

<?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 o seu navegador para https://localhost/testsql.php (https://localhost:8080/testsql.php no macOS). Agora deves conseguir ligar-te à tua base de dados SQL Server/Azure SQL. Se não vir uma mensagem de sucesso que mostra a informação da versão do SQL, pode realizar alguma resolução de problemas básica executando o script a partir da linha de comandos.

php testsql.php

Se correr a partir da linha de comandos for bem-sucedido mas nada aparecer no seu navegador, verifique os ficheiros de registo do Apache. Para mais ajuda, consulte recursos de apoio para locais a visitar.

Ver também

Começar com os drivers Microsoft para PHP para SQL Server

Carregamento dos drivers Microsoft para PHP para SQL Server

Requisitos de Sistema para os Drivers Microsoft para PHP no SQL Server

  • Last updated on