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 (SAPI) de servidor PHP puede usar un ejecutable y una configuración diferentes:

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 cargado php.ini.
• El directorio de análisis adicional .ini.
• El directorio de la extensión.
• El modo de seguridad de 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, elimina cualquier entrada existente de SQLSRV y PDO_SQLSRV del archivo activo php.ini, y luego añade:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

Utiliza solo un registro por conductor. Reinicia el proceso PHP tras cambiar su configuración.

Para una instalación ZIP, copia las bibliotecas de enlace dinámico (DLLs) que coincidan con la versión menor de PHP, la arquitectura y el modo de seguridad de hilo 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

Añade ambos nombres de archivo a los php.ini utilizado por el proceso 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 añadiendo una entrada extension= a un archivo adicional .ini o al estándar php.ini. 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 nombran 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 escanear archivos adicionales .ini en orden alfabético. Si tu distribución carga pdo.so desde un archivo analizado, coloca 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.

Elige las extensiones

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

No configure un nombre corto y un nombre con versión 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á compilado de forma nativa, activa 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 del controlador

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 ODBC de Microsoft controla el protocolo de base de datos tras la carga de la extensión.

Contenido relacionado

• Instala los controladores PHP para SQL Server en Windows
• Requisitos del sistema para los controladores Microsoft para PHP en SQL Server
• Actualizar los controladores PHP para SQL Server
• Referencia de API del controlador SQLSRV
• Referencia del controlador PDO_SQLSRV