Carregue os drivers Microsoft para PHP para SQL Server

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

O carregamento é separado da instalação. Copiar ou compilar a extensão coloca um arquivo 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 seja reiniciado.

Proteger páginas de diagnóstico web

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

Entenda o escopo de configuração do PHP

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

Runtime Fonte típica de configuração Como identificá-lo
CLI (interface de linha de comando) O php.ini e o diretório de varredura são reportados por php --ini Execute php --ini com o executável correto
IIS FastCGI O executável PHP configurado na aplicação IIS FastCGI Use uma página temporária phpinfo()
Módulo Apache Configuração do módulo PHP do Apache Use uma página temporária phpinfo()
PHP-FPM O executável do FPM, pool, php.ini e diretório de varredura Execute o binário FPM versionado com -i ou use uma página phpinfo() temporária
worker de longa duração O executável e o ambiente que iniciam o worker Inspecione o serviço worker e reinicie após as alterações

Mudar a configuração da CLI não afeta o IIS, o Apache ou o PHP-FPM se eles usarem outra instalação do PHP ou outro diretório de varredura.

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 Arquivo de Configuração Carregado e os valores de Procurar arquivos .ini adicionais em identificam a configuração usada pelo processo de linha de comando. Um servidor web ou um processo PHP FastCGI Process Manager (PHP-FPM) pode usar um executável ou arquivo de configuração PHP diferente. Use uma página temporária phpinfo() para identificar os valores desse processo.

Antes de editar um arquivo, registre:

  • O caminho e a versão do executável do PHP.
  • O carregamento php.ini.
  • O diretório adicional de varredura .ini.
  • O diretório de extensões.
  • O modo de segurança de threads e a arquitetura.
  • Cada processo que você deve reiniciar.

Faça backup de cada arquivo de configuração que você alterar.

Carregue os drivers no Windows

Para uma instalação com o PHP Installer for Extensions (PIE), primeiro baixe 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 puder ativar as extensões automaticamente, remova quaisquer entradas SQLSRV e PDO_SQLSRV existentes do arquivo de configuração ativo php.ini, então adicione:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

Use apenas um registro para cada motorista. Reinicie o processo PHP após alterar sua configuração.

Para uma instalação ZIP, copie as bibliotecas de vínculo dinâmico (DLLs) que correspondem à versão secundária do PHP, arquitetura e modo de segurança de threads para o diretório extension_dir. Uma runtime PHP 8.5 x64 thread-safe usa estes nomes de arquivo:

php_sqlsrv_85_ts_x64.dll
php_pdo_sqlsrv_85_ts_x64.dll

Adicione ambos os nomes de arquivo ao php.ini usado 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 arquivos thread-safe e non-thread-safe, arquivos de 32 bits e 64 bits, ou arquivos compilados para outra versão secundária do PHP.

Carregue os drivers no Linux e macOS

Instale os drivers usando o PIE. Para mais informações, veja o tutorial de instalação do Linux e macOS. O PIE instala os arquivos de extensão e tenta habilitá-los usando as ferramentas de configuração PHP da plataforma ou adicionando uma entrada extension= a um arquivo adicional .ini ou ao arquivo padrão php.ini. Se o PIE informar que não conseguiu habilitar uma extensão, adicione a entrada você mesmo e verifique a configuração ativa.

Para uma instalação manual, selecione os arquivos pré-construídos .so que correspondem à sua versão PHP, arquitetura, modo de segurança de threads e bibliotecas nativas do sistema operacional. Verifique os requisitos pré-construídos para Linux e macOS; use PIE se eles não combinarem com o seu ambiente.

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

extension=sqlsrv.so
extension=pdo_sqlsrv.so

Os Objetos de Dados PHP (PDO) devem ser carregados antes de PDO_SQLSRV. PHP lê php.ini antes de escanear arquivos adicionais .ini em ordem alfabética. Se sua distribuição carregar pdo.so a partir de um arquivo escaneado, coloque a entrada PDO_SQLSRV em um arquivo escaneado posterior, como 30-pdo_sqlsrv.ini quando o PDO usa 10-pdo.ini. Nesse caso, não coloque a entrada PDO_SQLSRV em php.ini.

Escolha as entradas da extensão

Use as entradas que correspondam à forma como os drivers foram instalados:

Plataforma e método Entrada do SQLSRV item PDO_SQLSRV
Windows com PIE extension=php_sqlsrv.dll extension=php_pdo_sqlsrv.dll
Windows descompactou o ZIP Nome exato da DLL versionado, como extension=php_sqlsrv_85_ts_x64.dll Nome exato da DLL versionado, como extension=php_pdo_sqlsrv_85_ts_x64.dll
Linux ou macOS com PIE extension=sqlsrv.so extension=pdo_sqlsrv.so
Linux ou macOS, arquivo disponibilizado, arquivos renomeados extension=sqlsrv.so extension=pdo_sqlsrv.so
Arquivo liberado para Linux ou macOS e arquivos originais Nome exato do arquivo compactado, como extension=SQLSRV_8.4_NTS.so Nome exato do arquivo compactado, como extension=PDO_SQLSRV_8.4_NTS.so

Não configure tanto um nome curto quanto um nome versionado para a mesma extensão. O PHP pode informar que um módulo já está carregado, ou pode continuar carregando um arquivo antigo após uma atualização.

Reinicie o PHP para carregar os drivers

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

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

Verifique os drivers carregados

Para o runtime de linha de comando, 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, restrinja o acesso à página de diagnóstico antes de criar uma página temporária contendo <?php phpinfo(); ?>. Confirme o arquivo de configuração carregado, extension_dir e as seções sqlsrv e pdo_sqlsrv separadas. Exclua a página após a verificação.

Também faça uma verificação em nível PHP para que a verificação cubra ambas as APIs, e não apenas os nomes dos módulos. Salve 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 sua aplicação utiliza:

php verify-php-drivers.php

Resultado esperado:

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

Para um runtime da web, coloque o arquivo temporariamente na raiz do site e acesse-o em um navegador. Remova-o após a verificação. Esse programa não abre uma conexão de banco de dados nem imprime valores de configuração.

Exclua verify-php-drivers.php depois de terminar as verificações de CLI e runtime da web.

Solucionar problemas de carregamento do driver

Sintoma Causa a verificar Ação corretiva
Unable to load dynamic library Nome de arquivo errado, extension_dir, versão secundária do PHP, arquitetura ou modo de segurança de thread errado Compare php -i com o arquivo de driver selecionado e use temporariamente um caminho absoluto para isolar erros de caminho
The specified module could not be found no Windows A DLL do driver ou uma de suas dependências não está disponível Confirme que a DLL está em extension_dir, instale o runtime Visual C++ correspondente e inspecione qualquer dependência de DLL ausente restante
undefined symbol ou erro de biblioteca compartilhada no Linux ou macOS Descompasso entre extensão e build de PHP ou falta de dependência de ODBC Reconstrua com o destino pretendido php-config, então inspecione a biblioteca ausente relatada
Module "sqlsrv" is already loaded Itens duplicados ou dois arquivos digitalizados Pesquise o php.ini carregado e o diretório de varredura, depois mantenha uma entrada
could not find driver a partir do PDO PDO_SQLSRV não está carregado, ou o PDO carrega depois dele Verifique php --ri pdo_sqlsrv e mova a entrada PDO_SQLSRV após o PDO
A CLI funciona, mas as requisições web falham Configuração SAPI diferente ou um processo que não foi reiniciado Compare os valores de configuração de CLI e de phpinfo(), edite a configuração web e reinicie o processo web
Vestígios antigos ExtensionVer permanecem após uma atualização A configuração ainda nomeia um arquivo versionado Substitua a entrada antiga pelo arquivo instalado pelo método selecionado, remova duplicatas e reinicie todos os processos PHP

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

Conteúdo relacionado

  • Última atualização em