Requisitos del sistema para los controladores de Microsoft para PHP para SQL Server

Descargar controlador PHP

Este artículo enumera los componentes que debes instalar en tu sistema para acceder a datos en SQL Server o Azure SQL Database utilizando el controlador SQLSRV o PDO_SQLSRV.

Para más información sobre los ciclos de vida de soporte y los requisitos de los controladores PHP, consulte la matriz de soporte. Los controladores SQLSRV y PDO_SQLSRV en cada versión tienen los mismos requisitos de PHP, sistema operativo, arquitectura, seguridad de hilos y ODBC.

Cómo encaja la pila de controladores

Una aplicación PHP no se conecta directamente al servidor de la base de datos. Cada capa debe ser compatible con la capa contigua:

SQLSRV y PDO_SQLSRV proporcionan diferentes APIs PHP sobre el mismo controlador ODBC. Instala ambos cuando tu aplicación use ambas APIs. Instalar una extensión no instala ni habilita automáticamente la otra.

Las extensiones pueden instalarse de forma independiente. PDO_SQLSRV también requiere que PDO se cargue antes de PDO_SQLSRV.

Elige un conjunto compatible

Antes de descargar o compilar un controlador, completa estas comprobaciones:

1. Identifica cada entorno de ejecución de PHP que ejecute la aplicación. Una tarea programada, un proceso en línea de comandos, un sitio IIS, un módulo Apache y un grupo PHP-FPM pueden usar diferentes ejecutables y archivos de configuración de PHP.

2. Ejecuta el siguiente comando con cada ejecutable de PHP:

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

   En Linux o macOS, utiliza:

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

   El file comando informa de la arquitectura del ejecutable. Si informa de un ejecutable universal de macOS, seleccione explícitamente la arquitectura prevista, como arch -arm64 php --version o arch -x86_64 php --version. Usa la misma selección de arquitectura al construir, cargar y probar las extensiones.

3. Seleccione una versión de controlador PHP que soporte la versión menor de PHP, el sistema operativo y el destino de la base de datos.

4. Selecciona una versión compatible del controlador Microsoft ODBC desde la tabla de compatibilidad de este artículo.

5. Haz coincidir el archivo de extensión o la compilación PIE con la arquitectura PHP y el modo de seguridad de hilos. No copies una extensión de otra instalación PHP a menos que todos estos valores coincidan.

6. Configura y verifica por separado los entornos de ejecución de la CLI y del servidor web. Un comando exitoso php -m solo demuestra que el entorno de ejecución de la CLI cargó la extensión.

PHP

Descarga binarios PHP desde la web de PHP. Elige una versión de PHP que aparece en soporte de versiones PHP.

• Activa el archivo del driver que coincida con tu versión de PHP. Para nombres de archivos, véase Versiones de controladores. Descarga los archivos de Descargar los controladores de Microsoft para PHP para SQL Server. Para las instrucciones de configuración, consulte Cargar los controladores de Microsoft para PHP para SQL Server.

• Elige un servidor web y un método de integración de PHP soportado por PHP y tu framework de aplicaciones. Sigue la documentación de instalación de PHP y las instrucciones de despliegue de tu framework para configurar el servidor web para que ejecute PHP. Verifica la carga de extensiones en el runtime del servidor web por separado de la CLI.

Seguridad de subprocesos y arquitectura

El archivo de compilación de PHP y el archivo de extensión deben coincidir en ambos valores.

La CLI puede usar una compilación de PHP segura para hilos o no segura para hilos. Selecciona la extensión por el valor reportado, sin asumir que todas las compilaciones de CLI no son seguras para hilos.

Controlador ODBC

Instala un controlador Microsoft ODBC compatible para SQL Server en el ordenador que ejecute PHP. Descarga el controlador desde Download ODBC Driver for SQL Server.

Si está descargando la versión de Windows del controlador en una versión de 64 bits de Windows, el instalador de ODBC 64 bits instala los controladores ODBC de 32 bits y de 64 bits. Si usa una versión de Windows de 32 bits, use el instalador de ODBC x86. En plataformas que no son de Windows, solo están disponibles las versiones de 64 bits del controlador.

La tabla incluye combinaciones históricas para la planificación de actualizaciones. Utiliza la versión actual del controlador PHP y sus versiones ODBC listadas para una nueva instalación. La compatibilidad con una versión anterior no extiende su ciclo de soporte de soporte. Revisa tanto el ciclo de vida del soporte del controlador PHP como las versiones compatibles con PHP.

Una celda vacía no significa necesariamente que el controlador PHP rechace necesariamente esa versión ODBC. Las características individuales pueden requerir versiones ODBC más recientes que la combinación base.

Si usa el controlador SQLSRV, sqlsrv_client_info devuelve información sobre qué versión de SQL Server Microsoft ODBC Driver for SQL Server que utiliza los Controladores de Microsoft para PHP para SQL Server. Si está usando el controlador PDO_SQLSRV, puede usar PDO::getAttribute para detectar la versión.

SQL Server

Para las versiones compatibles de SQL Server, véase Versiones de base de datos soportadas.

Evalúa el soporte del destino por separado para SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, base de datos SQL en Microsoft Fabric y Warehouse en Microsoft Fabric. Los requisitos de instalación son requisitos del lado del cliente y no establecen que todos los métodos de autenticación, opción de conexión, función Transact-SQL (T-SQL) o tipo de dato estén disponibles en cada sistema de destino. Utiliza la matriz de soporte y la documentación del producto objetivo para el escenario que utiliza tu aplicación.

Sistemas operativos

Para sistemas operativos compatibles, véase Sistemas operativos soportados.

Versiones del controlador

Cada versión de los controladores Microsoft para PHP para SQL Server incluye SQLSRV y archivos de controladores PDO_SQLSRV en variantes seguras para hilos y no para hilos. En Windows, cada variante también está diseñada para PHP de 32 y 64 bits. Haz coincidir el archivo del driver con tu versión de PHP, modo de seguridad para subprocesos y arquitectura. Para habilitar un archivo de controlador después de descargarlo, consulta Loading the Microsoft Drivers for PHP for SQL Server.

En Linux y macOS, instala los drivers con PIE, el instalador PHP para extensiones, tal y como se describe en las instrucciones de instalación de Linux y macOS. PIE sustituye el sistema de paquetes en desuso PHP Extension Community Library (PECL) y nombra la extensión instalada sqlsrv.so o pdo_sqlsrv.so. Las siguientes tablas enumeran los nombres de archivo de los paquetes binarios preconstruidos que descargas manualmente desde la página de Microsoft Drivers for PHP for SQL Server releases.

Las siguientes tablas enumeran los archivos de los paquetes de versión 5.13. En nombres de archivos, ts y TS significan seguro para hilos, y nts y NTS significan no seguro para hilos.

Archivos de controladores de Windows

El paquete Windows_5.13.xRTW.zip contiene estos archivos.

Utiliza un archivo controlador no seguro para hilos con una compilación PHP no segura para hilos, y un archivo controlador seguro para hilos con una compilación PHP segura para hilos. La interfaz de línea de comandos (CLI) puede usar cualquiera de las dos versiones. Para confirmar qué build tienes, ejecuta php -i y comprueba el valor de seguridad de subprocesos.

Archivos de controladores para Linux y macOS

Los paquetes Linux_5.13.xRTW.tar.gz y Mac_5.13.xRTW.tar.gz contienen estos archivos. El archivo de Linux contiene binarios x64, y el archivo de macOS contiene binarios Arm64.

Los archivos precompilados también deben coincidir con las bibliotecas nativas de tu sistema operativo. Los binarios de Linux 5.13.3 requieren glibc 2.38 y versiones posteriores y un entorno de ejecución de C++ que incluya GLIBCXX_3.4.32. Los binarios de macOS 5.13.3 declaran macOS 26 como su objetivo mínimo de despliegue. Estos requisitos binarios son independientes del soporte del sistema operativo para compilaciones de código fuente.

Usa PIE cuando la arquitectura del paquete o los requisitos de la biblioteca nativa no coincidan con tu instalación de PHP. PIE genera compilaciones para PHP instalado y las bibliotecas nativas. No cambies librerías del sistema manualmente para cargar una extensión preconstruida.

Copia cada archivo que necesites en tu directorio de extensiones PHP. Puedes conservar el nombre del archivo del paquete y escribir extension=SQLSRV_8.4_NTS.so, o renombrar el archivo a sqlsrv.so y escribir la forma corta extension=sqlsrv. Aplica la misma elección de nombre a PDO_SQLSRV. Para encontrar el directorio de extensiones, ejecuta php -i | grep extension_dir. Sigue las instrucciones de Cargar los controladores en Linux y macOS para habilitar las extensiones en el archivo de configuración correcto y cargar los Objetos de Datos PHP (PDO) antes de PDO_SQLSRV.

Versiones anteriores

Para los archivos de controladores incluidos en versiones anteriores a la 5.13, descarga el paquete de esa versión desde la página de versiones de Microsoft Drivers for PHP para SQL Server y lista su contenido. Las versiones anteriores a la 5.12 publican un paquete separado para cada sistema operativo y versión de PHP en lugar de un paquete único por plataforma.

Verifica el entorno seleccionado

Ejecuta estas comprobaciones después de instalar las extensiones PHP y el controlador ODBC, pero antes de configurar un servidor web:

php --version
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv

Los dos últimos comandos deben mostrar secciones separadas de información de módulo. Si alguno de los comandos indica que la extensión no está presente, termina el procedimiento de instalación y carga de la plataforma antes de probar una conexión a la base de datos.

Cree verify-php-drivers.php para comprobar ambas API de PHP sin requerir credenciales:

<?php
$failures = [];

if (!extension_loaded('sqlsrv') || !function_exists('sqlsrv_connect')) {
    $failures[] = 'SQLSRV is not loaded.';
}

if (!extension_loaded('pdo_sqlsrv') || !in_array('sqlsrv', PDO::getAvailableDrivers(), true)) {
    $failures[] = 'PDO_SQLSRV is not loaded.';
}

echo $failures === []
    ? "SQLSRV and PDO_SQLSRV are loaded." . PHP_EOL
    : implode(PHP_EOL, $failures) . PHP_EOL;

exit($failures === [] ? 0 : 1);

Ejecútalo con el ejecutable PHP que sirve a la aplicación:

php verify-php-drivers.php

Resultado esperado:

SQLSRV and PDO_SQLSRV are loaded.

Esta comprobación verifica la carga de extensiones. No verifica la conectividad ODBC, autenticación, confianza de certificados, acceso a la red o permisos de base de datos.

Borra verify-php-drivers.php después de grabar el resultado.

Diagnosticar fallos de requisitos

Contenido relacionado

• Introducción a los controladores de Microsoft para PHP para SQL Server
• Guía de programación para los controladores de Microsoft para PHP para SQL Server
• Referencia de API del controlador SQLSRV
• Referencia del controlador PDO_SQLSRV