Carga los controladores de Microsoft para PHP para SQL Server

Los controladores SQLSRV y PDO_SQLSRV son extensiones PHP. PHP los carga cuando el proceso PHP comienza leyendo php.ini y cualquier archivo adicional .ini .

La carga es independiente de la instalación. Al copiar o compilar la extensión, se coloca un archivo en disco. PHP no puede usar SQLSRV ni PDO_SQLSRV hasta que la configuración activa contenga la entrada correcta y el proceso PHP se reinicie.

Proteger las páginas de diagnóstico web

Antes de crear una página temporal phpinfo(), configura el servidor web para permitir solo solicitudes desde localhost o administradores autenticados. Mantén esa restricción hasta que borres la página. phpinfo() puede exponer variables del entorno, credenciales y configuración del servidor. Elimina la página inmediatamente después de verificar.

Entender el alcance de configuración de PHP

Cada interfaz de programación de aplicaciones de servidor (SAPI) PHP puede usar un ejecutable y una configuración diferentes:

Runtime Fuente típica de configuración Cómo identificarlo
Interfaz de la línea de comandos (CLI) El php.ini y el directorio de análisis notificado por php --ini Ejecuta php --ini con el ejecutable exacto
IIS FastCGI El ejecutable PHP configurado en la aplicación IIS FastCGI Usa una página temporal phpinfo()
Módulo apache Configuración del módulo PHP en Apache Usa una página temporal phpinfo()
PHP-FPM El ejecutable FPM, el pool, php.ini y el directorio de escaneo Ejecuta el binario FPM versionado -i o usa una página temporal phpinfo()
Proceso de trabajo de ejecución prolongada El ejecutable y el entorno que iniciaron el proceso de trabajo Inspecciona el servicio worker y reinicia el servicio tras los cambios

Cambiar la configuración de la CLI no afecta a IIS, Apache ni PHP-FPM cuando usan otra instalación de PHP o directorio de escaneo.

Encuentra la configuración de PHP

Ejecuta estos comandos con el ejecutable PHP que usa tu aplicación:

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

En Linux o macOS, sustituye findstr por grep:

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

El file comando identifica la arquitectura del ejecutable seleccionado. Para un ejecutable universal de macOS, sigue la selección explícita de arquitectura.

Los valores Archivo de configuración cargado y Buscar archivos .ini adicionales en identifican la configuración utilizada por el proceso de línea de comandos. Un servidor web o un proceso PHP FastCGI Process Manager (PHP-FPM) podría usar un ejecutable o archivo de configuración PHP diferente. Utiliza una página temporal phpinfo() para identificar los valores de ese proceso.

Antes de editar un archivo, anota:

  • La ruta ejecutable y la versión de PHP.
  • El php.ini cargado.
  • El directorio de análisis de .ini adicionales.
  • El directorio de la extensión.
  • El modo de seguridad para subprocesos y la arquitectura.
  • Cada proceso que debes reiniciar.

Haz una copia de seguridad de cada archivo de configuración que cambies.

Cargar los controladores en Windows

Para una instalación con el PHP Installer for Extensions (PIE), primero descarga y verifica PIE. Ejecuta los siguientes comandos desde el directorio que contiene pie.phar, con el ejecutable PHP que debería cargar los controladores:

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

PIE instala php_sqlsrv.dll y php_pdo_sqlsrv.dll. Si PIE no puede habilitar las extensiones automáticamente, elimine cualquier entrada SQLSRV y PDO_SQLSRV existente del archivo php.ini activo y, a continuación, agregue:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

Use un solo registro por controlador. Reinicia el proceso PHP tras cambiar su configuración.

Para una instalación ZIP, copie las bibliotecas de vínculo dinámico (DLLs) que coincidan con la versión menor de PHP, la arquitectura y el modo de seguridad para subprocesos en el directorio extension_dir. Un entorno de ejecución PHP 8.5 x64 con seguridad de hilos utiliza estos nombres de archivo:

php_sqlsrv_85_ts_x64.dll
php_pdo_sqlsrv_85_ts_x64.dll

Agregue ambos nombres de archivo al php.ini utilizado por el proceso de PHP:

extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

Sustituye 85, ts, y x64 por los valores de tu entorno de ejecución PHP. No mezcles archivos thread-safe y no thread-safe, archivos de 32 y 64 bits, o archivos construidos para otra versión menor de PHP.

Carga los controladores en Linux y macOS

Instala los controladores usando PIE. Para más información, consulta el tutorial de instalación de Linux y macOS. PIE instala los archivos de extensión e intenta habilitarlos utilizando las herramientas de configuración PHP de la plataforma o agregando una entrada extension= a un archivo .ini adicional o al php.ini estándar. Si PIE informa que no pudo habilitar una extensión, añade tú mismo la entrada y verifica la configuración activa.

Para una instalación manual, selecciona los archivos precompilados .so que coincidan con tu versión de PHP, arquitectura, modo de seguridad para subprocesos y bibliotecas nativas del sistema operativo. Revisa los requisitos predefinidos de Linux y macOS; usa PIE si no encajan con tu entorno.

Por ejemplo, los archivos PHP 8.4 sin seguridad para subprocesos se designan como SQLSRV_8.4_NTS.so y PDO_SQLSRV_8.4_NTS.so. Colócalos en el directorio devuelto por php -i | grep extension_dir. Renombralos a sqlsrv.so y pdo_sqlsrv.so para usar las siguientes entradas, o utiliza los nombres exactos de los archivos de los paquetes en las entradas. Añade las entradas a tu configuración activa de PHP en el orden de carga descrito en esta sección:

extension=sqlsrv.so
extension=pdo_sqlsrv.so

Los Objetos de Datos PHP (PDO) deben cargarse antes de PDO_SQLSRV. PHP lee php.ini antes de analizar archivos .ini adicionales por orden alfabético. Si su distribución carga pdo.so desde un archivo analizado, coloque la entrada PDO_SQLSRV en un archivo analizado posterior, como 30-pdo_sqlsrv.ini cuando PDO usa 10-pdo.ini. En ese caso, no pongas la entrada PDO_SQLSRV en php.ini.

Elegir las entradas de extensión

Utiliza entradas que coincidan con cómo se instalaron los controladores:

Plataforma y método Entrada SQLSRV entrada de PDO_SQLSRV
Windows con PIE extension=php_sqlsrv.dll extension=php_pdo_sqlsrv.dll
ZIP publicado para Windows Nombre exacto de la DLL versionado, como extension=php_sqlsrv_85_ts_x64.dll Nombre exacto de la DLL versionado, como extension=php_pdo_sqlsrv_85_ts_x64.dll
Linux o macOS con PIE extension=sqlsrv.so extension=pdo_sqlsrv.so
Archivo comprimido publicado para Linux o macOS, archivos cuyo nombre ha cambiado extension=sqlsrv.so extension=pdo_sqlsrv.so
Archivo comprimido publicado para Linux o macOS, archivos originales Nombre de archivo exacto del archivo comprimido, como extension=SQLSRV_8.4_NTS.so Nombre de archivo exacto del archivo comprimido, como extension=PDO_SQLSRV_8.4_NTS.so

No configure un nombre corto y un nombre versionado para la misma extensión. PHP puede informar de que un módulo ya está cargado, o puede seguir cargando un archivo antiguo tras una actualización.

Reinicia PHP para cargar los controladores

Reinicia el proceso tras cambiar un archivo de extensión o un archivo de configuración. Reinicia el servidor web, PHP-FPM, los trabajadores de cola y otros procesos PHP de larga duración que cargan el driver.

Las extensiones SQLSRV y PDO_SQLSRV pueden cargarse de forma independiente, pero instala y verifica ambas cuando tu aplicación use ambos controladores. PDO está integrado en muchos paquetes PHP. Si PDO no está integrado, habilite la extensión PDO antes de PDO_SQLSRV.

Verifica los controladores cargados

Para el tiempo de ejecución de línea de comandos, ejecuta:

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

En Linux o macOS, utiliza:

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

Para un servidor web, restrinja el acceso a páginas de diagnóstico antes de crear una página temporal que contenga <?php phpinfo(); ?>. Confirma el archivo de configuración cargado, extension_dir y las secciones sqlsrv y pdo_sqlsrv separadas. Elimina la página tras la verificación.

También haz una comprobación a nivel PHP para que la verificación cubra ambas APIs y no solo los nombres de los módulos. Guarda 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);

Ejecuta el programa con cada ejecutable PHP que utilice tu aplicación:

php verify-php-drivers.php

Resultado esperado:

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

Para un entorno de ejecución web, coloca temporalmente el archivo en la raíz del documento y accede a él desde un navegador. Quítelo después de verificarlo. Este programa no abre una conexión a la base de datos ni imprime valores de configuración.

Borra verify-php-drivers.php después de terminar las comprobaciones de CLI y runtime web.

Solucionar problemas de carga de controladores

Síntoma Causa que se debe comprobar Acción correctiva
Unable to load dynamic library Nombre de archivo, extension_dir, versión menor de PHP, arquitectura o modo de seguridad para subprocesos incorrectos Compare php -i con el archivo de controlador seleccionado y use temporalmente una ruta absoluta para aislar los errores de ruta
The specified module could not be found en Windows La DLL del controlador o una de sus dependencias no está disponible Confirma que la DLL está en extension_dir, instala el entorno de ejecución Visual C++ correspondiente e inspecciona cualquier dependencia DLL que falte
undefined symbol o error de biblioteca compartida en Linux o macOS Desajuste entre extensiones y compilaciones de PHP, o falta de dependencia de ODBC Vuelva a compilar con el php-config previsto y, a continuación, inspeccione la biblioteca notificada como ausente
Module "sqlsrv" is already loaded Entradas duplicadas o dos archivos escaneados Busque en el php.ini cargado y en el directorio de análisis, y luego mantenga una entrada
could not find driver de PDO PDO_SQLSRV no está cargado, o PDO se carga después Revisa php --ri pdo_sqlsrv y mueve la entrada PDO_SQLSRV después de PDO
La CLI funciona, pero las peticiones web fallan Configuración SAPI diferente o un proceso que no se reinició Compara los valores de configuración de CLI y de phpinfo(), edita la configuración web y reinicia el proceso web
El ExtensionVer antiguo permanece tras una actualización La configuración aún nombra un archivo versionado anterior Sustituye la entrada antigua por el archivo instalado por el método seleccionado, elimina duplicados y reinicia todos los procesos PHP

PHP se encarga del descubrimiento de extensiones y del orden de carga. PIE o una copia manual proporciona el archivo de extensión. El cargador del sistema operativo resuelve dependencias nativas. El controlador de Microsoft ODBC controla el protocolo de base de datos tras la carga de la extensión.

Contenido relacionado

  • Última actualización el