Carregue os drivers Microsoft para PHP para SQL Server

Os drivers SQLSRV e PDO_SQLSRV são extensões PHP. O PHP carrega-os quando o processo PHP começa, lendo php.ini e quaisquer ficheiros adicionais .ini .

O carregamento é separado da instalação. Copiar ou compilar a extensão coloca um ficheiro no disco. O PHP não pode usar SQLSRV ou PDO_SQLSRV até que a configuração ativa contenha a entrada correta e o processo PHP reinicie.

Proteger páginas de diagnóstico web

Antes de criar uma página temporária phpinfo() , configure o servidor web para permitir apenas pedidos do localhost ou administradores autenticados. Mantém essa restrição até eliminares a página. phpinfo() pode expor variáveis de ambiente, credenciais e configuração do servidor. Remova a página imediatamente após a verificação.

Compreender o âmbito da configuração do PHP

Cada interface de programação de aplicações do servidor PHP (SAPI) pode usar um executável e uma configuração diferentes:

Mudar a configuração da CLI não altera o IIS, Apache ou PHP-FPM quando usam outra instalação PHP ou diretório de scan.

Localizar a configuração do PHP

Execute estes comandos com o executável PHP usado pela sua aplicação:

php --ini
php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir"

No Linux ou macOS, substitua findstr por grep:

php -i | grep -E "PHP Version|Thread Safety|extension_dir"
file "$(php -r 'echo PHP_BINARY;')"

O file comando identifica a arquitetura do executável selecionado. Para um executável universal do macOS, siga a seleção explícita da arquitetura.

O Ficheiro de Configuração Carregado e os valores de Procurar ficheiros .ini adicionais em identificam a configuração usada pelo processo de linha de comandos. Um servidor web ou um processo PHP FastCGI Process Manager (PHP-FPM) pode usar um executável ou ficheiro de configuração PHP diferente. Utilize uma página temporária phpinfo() para identificar os valores desse processo.

Antes de editar um ficheiro, regista:

• O caminho e a versão do executável PHP.
• O carregamento php.ini.
• O diretório de análise adicional .ini.
• O diretório da extensão.
• O modo de segurança de execução entre threads e a arquitetura.
• Cada processo que tem de reiniciar.

Faz backup de cada ficheiro de configuração que alteras.

Instalar os controladores no Windows

Para uma instalação com o PHP Installer for Extensions (PIE), primeiro descarregue e verifique o PIE. Execute os seguintes comandos a partir do diretório que contém pie.phar, com o executável PHP que deve carregar os drivers:

php .\pie.phar install microsoft/sqlsrv
php .\pie.phar install microsoft/pdo_sqlsrv

PIE instala php_sqlsrv.dll e php_pdo_sqlsrv.dll. Se o PIE não conseguir ativar as extensões automaticamente, remova quaisquer entradas SQLSRV e PDO_SQLSRV existentes do ficheiro de configuração ativo php.ini, depois adicione:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

Use apenas um registo para cada condutor. Reinicie o processo PHP após alterar a sua configuração.

Para uma instalação ZIP, copie as bibliotecas de ligação dinâmica (DLLs) que correspondem à versão secundária do PHP, arquitetura e modo de segurança de threads para o diretório extension_dir. Um runtime PHP 8.5 x64 thread-safe utiliza estes nomes de ficheiros:

php_sqlsrv_85_ts_x64.dll
php_pdo_sqlsrv_85_ts_x64.dll

Adicione ambos os nomes de ficheiros ao php.ini utilizado pelo processo PHP:

extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

Substitua 85, ts e x64 pelos valores do runtime do PHP. Não misture ficheiros thread-safe e não-thread-safe, ficheiros de 32 bits e 64 bits, ou ficheiros compilados para outra versão secundária do PHP.

Carregue os controladores no Linux e macOS

Instala os drivers usando PIE. Para mais informações, consulte o tutorial de instalação do Linux e macOS. O PIE instala os ficheiros de extensão e tenta habilitá-los usando as ferramentas de configuração PHP da plataforma ou adicionando uma entrada extension= a um ficheiro adicional .ini ou ao ficheiro padrão php.ini. Se o PIE reportar que não conseguiu ativar uma extensão, adiciona tu mesmo a entrada e verifica a configuração ativa.

Para uma instalação manual, selecione os ficheiros pré-construídos .so que correspondam à sua versão PHP, arquitetura, modo de segurança de threads e bibliotecas nativas do sistema operativo. Verifica os requisitos pré-construídos para Linux e macOS; usa PIE se não corresponderem ao teu ambiente.

Por exemplo, ficheiros PHP 8.4 sem segurança para threads são nomeados SQLSRV_8.4_NTS.so e PDO_SQLSRV_8.4_NTS.so. Coloque-os no diretório devolvido por php -i | grep extension_dir. Renomeie-os para sqlsrv.so e pdo_sqlsrv.so para usar as seguintes entradas, ou use os nomes exatos dos ficheiros de pacote nas entradas. Adicione as entradas à sua configuração PHP ativa na ordem de carregamento descrita nesta secção:

extension=sqlsrv.so
extension=pdo_sqlsrv.so

PHP Data Objects (PDO) devem ser carregados antes de PDO_SQLSRV. O PHP lê php.ini antes de analisar ficheiros adicionais .ini por ordem alfabética. Se a sua distribuição carregar pdo.so a partir de um ficheiro analisado, coloque a entrada PDO_SQLSRV num ficheiro analisado posterior, como 30-pdo_sqlsrv.ini quando o PDO usa 10-pdo.ini. Nesse caso, não coloques a entrada PDO_SQLSRV em php.ini.

Escolha as entradas da extensão

Use itens que correspondam à forma como os drivers foram instalados:

Não configures tanto um nome curto como um nome versionado para a mesma extensão. O PHP pode reportar que um módulo já está carregado, ou pode continuar a carregar um ficheiro mais antigo após uma atualização.

Reinicie o PHP para carregar os drivers

Reinicie o processo após alterar um ficheiro de extensão ou de configuração. Reinicie o servidor web, o PHP-FPM, os trabalhadores de fila e outros processos PHP de longa duração que carreguem o driver.

As extensões SQLSRV e PDO_SQLSRV podem ser carregadas de forma independente, mas instale e verifique ambas quando a sua aplicação usar ambos os drivers. O PDO está integrado em muitos pacotes PHP. Se o PDO não estiver incorporado, ativa a extensão PDO antes de PDO_SQLSRV.

Verifique os drivers carregados

Para o tempo de execução da linha de comandos, execute:

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | findstr /I "sqlsrv pdo_sqlsrv"

No Linux ou macOS, use:

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

Para um servidor web, restringa o acesso a páginas de diagnóstico antes de criar uma página temporária contendo <?php phpinfo(); ?>. Confirme o ficheiro de configuração carregado, extension_dir e as secções sqlsrv e pdo_sqlsrv. Remova a folha após a verificação.

Também faz uma verificação ao nível PHP para que a verificação cubra ambas as APIs e não apenas os nomes dos módulos. Guarde este programa como verify-php-drivers.php:

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

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

exit($failed ? 1 : 0);

Execute o programa com cada executável PHP que a sua aplicação utilize:

php verify-php-drivers.php

Produção esperada:

SQLSRV extension: loaded
SQLSRV API: loaded
PDO_SQLSRV extension: loaded
PDO_SQLSRV API: loaded

Para um ambiente de execução web, coloque temporariamente o ficheiro na document root e abra-o num navegador. Remova-o após verificação. Este programa não abre uma ligação à base de dados nem imprime valores de configuração.

Elimina verify-php-drivers.php depois de terminares a CLI e as verificações de web-runtime.

Resolução de problemas de carregamento do controlador

O PHP é responsável pela descoberta de extensões e pela ordem de carregamento. O PIE ou uma cópia feita manualmente fornece o ficheiro de extensão. O carregador do sistema operativo resolve dependências nativas. O Microsoft ODBC Driver assume o protocolo da base de dados após o carregamento da extensão.

Conteúdo relacionado

• Instale os drivers PHP para SQL Server no Windows
• Requisitos de sistema para os drivers Microsoft para PHP para SQL Server
• Atualizar os drivers PHP para o SQL Server
• Referência da API do Driver SQLSRV
• Referência do Driver PDO_SQLSRV