Controladores de Microsoft para PHP para SQL Server

Descargar controlador PHP

Los controladores de Microsoft para PHP para SQL Server son extensiones de PHP que puedes usar para leer y escribir datos en el Microsoft SQL Motor de base de datos desde scripts PHP. Las dos extensiones utilizan el mismo Microsoft ODBC Driver for SQL Server, pero ofrecen diferentes API de PHP y opciones específicas del controlador:

• SQLSRV expone una API procedural (sqlsrv_*funciones) adaptada a las características de SQL Server.
• PDO_SQLSRV implementa la interfaz PHP Data Objects (PDO). Puedes mantener las llamadas PDO en el código de base de datos existente, pero revisa sus consultas y ajustes específicos del controlador antes de cambiar de base de datos.

Ambos controladores se conectan a Azure SQL Database, SQL database en Microsoft Fabric, Azure SQL Managed Instance y todas las versiones y ediciones compatibles de SQL Server, incluidas las ediciones Express. Ambos drivers aceptan flujos PHP como parámetros de entrada. SQLSRV soporta recuperar grandes valores binarios y de caracteres como flujos. No des por hecho que PDO_SQLSRV tiene el mismo comportamiento de transmisión de salida.

Elija el punto de partida.

• Para verificar tu instalación y ejecutar una consulta parametrizada usando SQLSRV o PDO_SQLSRV, empieza con Quickstart: Connect y consulta con los controladores de Microsoft para PHP.
• Para instalar el controlador en Linux o macOS, empieza con el tutorial de instalación para Linux y macOS y descarga los controladores de Microsoft para PHP para SQL Server.
• Para conectarte a Azure SQL con autenticación sin contraseña, empieza con Connect usando las opcionesde autenticación y conexión de Microsoft Entra.
• Para hacer que una app existente sea resistente a fallos transitorios, ve a Idle connection resiliency.
• Para decidir entre SQLSRV y PDO_SQLSRV, consulta Resumen de los controladores de Microsoft para PHP para SQL Server y Comparando funciones de ejecución.
• Para diagnosticar un problema de instalación, conexión o consulta, ve a Resolución de problemas, Gestión de errores y advertencias, y Actividad de registro.
• Para que una app existente sea más rápida, ve a Ajuste de Rendimiento.

Línea base de producción para Azure SQL

Este PDO_SQLSRV ejemplo lee el servidor y la base de datos a partir de variables de entorno y se conecta con una identidad gestionada. Construye un nombre de fuente de datos (DSN) y habilita la Seguridad de la Capa de Transporte (TLS) con validación de certificados. Lee estos valores desde la configuración de la aplicación de confianza, no desde los parámetros de la solicitud web. Ejecuta el programa en un host con un punto final de identidad gestionada después de conceder a la identidad acceso a la base de datos.

Las funciones auxiliares pueden realizar hasta tres intentos de conectar o ejecutar la consulta de solo lectura cuando ocurre un error listado. Esperan más tiempo entre intentos, un patrón de reintentos llamado backoff exponencial. Si un error de consulta requiere una nueva conexión, el asistente de consulta lanza la excepción para que el código que llama la gestione.

Utiliza una versión de PHP compatible, la extensión PDO_SQLSRV y el controlador ODBC 18 de Microsoft para SQL Server. Para los valores de autenticación admitidos, consulte Conectarse mediante la autenticación de Microsoft Entra. No reutilices el asistente de consulta para escrituras o transacciones de múltiples sentencias sin diseñar una política de reintentos específica para la aplicación: un error no siempre te dice si una escritura se ha confirmado.

<?php
declare(strict_types=1);

// Transient errors that require a fresh connection to recover. SQLSTATE values
// starting with '08' cover ODBC connection-established and connection-broken
// states (for example, 08001, 08S01).
const CONNECT_RETRY_SQLSTATE_PREFIX = '08';

// SQL Server error codes that are transient regardless of when they surface:
// 1205 (deadlock victim), 1222 (lock request timeout), and the Azure SQL
// throttling, mid-query failover, and "database not currently available"
// codes that arrive with SQLSTATE HY000.
const TRANSIENT_SERVER_ERROR_CODES = [1205, 1222, 40501, 40613, 40197, 10928, 10929, 49918];

// This read helper retries only the listed errors on the same connection.
// Other errors propagate; the caller must decide whether to reconnect.
const RETRYABLE_READ_ERROR_CODES = [1205, 1222, 40501, 10928, 10929];

/**
 * Open a connection, retrying transient failures with exponential backoff.
 */
function connectWithRetry(string $dsn, array $options, int $maxAttempts = 3): PDO
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $pdo = new PDO($dsn, null, null, $options);
            error_log(sprintf('connected on attempt %d/%d', $attempt, $maxAttempts));
            return $pdo;
        } catch (PDOException $e) {
            $sqlstate = (string) $e->getCode();
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = str_starts_with($sqlstate, CONNECT_RETRY_SQLSTATE_PREFIX)
                || in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('connect failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1);
            error_log(sprintf('connect attempt %d hit transient %s/%d; retrying in %d seconds', $attempt, $sqlstate, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('connectWithRetry exhausted retries');
}

/**
 * Retry the standalone read-only query for errors that allow connection reuse.
 */
function queryWithRetry(PDO $pdo, string $sql, array $params = [], int $maxAttempts = 3): PDOStatement
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $stmt = $pdo->prepare($sql);
            $stmt->execute($params);
            return $stmt;
        } catch (PDOException $e) {
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = in_array($driverCode, RETRYABLE_READ_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('query failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1);
            error_log(sprintf('query attempt %d hit transient code %d; retrying in %d seconds', $attempt, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('queryWithRetry exhausted retries');
}

// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;

if ($server === null || $database === null) {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE in your application configuration.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';

$dsn = sprintf(
    'sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=%s;Database=%s;'
    . 'Encrypt=true;TrustServerCertificate=false;'
    . 'LoginTimeout=90;Authentication=ActiveDirectoryMsi;'
    . 'ConnectRetryCount=5;ConnectRetryInterval=15;'
    . 'MultiSubnetFailover=true;',
    $server,
    $databaseValue
);

$options = [
    PDO::ATTR_ERRMODE               => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE    => PDO::FETCH_ASSOC,
    PDO::ATTR_EMULATE_PREPARES      => false,
    PDO::SQLSRV_ATTR_QUERY_TIMEOUT  => 30,
];

$pdo = connectWithRetry($dsn, $options);
$stmt = queryWithRetry($pdo, 'SELECT name FROM sys.databases WHERE database_id > ? ORDER BY name', [1]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Utiliza estas configuraciones para los grupos de failover de Azure SQL Database y Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} selecciona explícitamente el controlador ODBC 18 en lugar de depender del descubrimiento del controlador. Instálalo antes de ejecutar el ejemplo.

• Establece SQL_DATABASE con el nombre real de la base de datos. El programa duplica las llaves de cierre y encierra el nombre entre llaves antes de colocarlo en la DSN. Escapar evita que los caracteres especiales del nombre cambien la forma en que el controlador lee los ajustes de conexión.

• ConnectRetryCount y ConnectRetryInterval controlan la resistencia de conexiones inactivas de ODBC. El tiempo de espera de consulta de la instrucción delimita la recuperación durante la ejecución. Con el tiempo de espera de consulta de 30 segundos de la muestra, ODBC podría detenerse antes de agotar los cinco intentos de reconexión. LoginTimeout=90 controla el establecimiento de la conexión, no el presupuesto de recuperación. El componente auxiliar de la aplicación reintenta ante determinados errores del servidor; no vuelve a intentar un tiempo de espera de consulta ni devuelve resultados obtenidos parcialmente.

• Activa el registro del controlador junto con las llamadas del programa error_log(). Para PDO_SQLSRV, pon pdo_sqlsrv.log_severity en php.ini o con ini_set() en tiempo de ejecución. Para SQLSRV, configure LogSeverity y LogSubsystems con sqlsrv_configure(). Para más información, consulte Actividad de registro.

  ; php.ini - enable PDO_SQLSRV driver diagnostics alongside the application-level
  ; error_log() calls in the sample. Use 1 (errors) in production; -1 (all) is
  ; useful during triage but very chatty.
  [pdo_sqlsrv]
  pdo_sqlsrv.log_severity = 1
  

• Para una identidad administrada asignada por el usuario, pasa el ID de la identidad como argumento $username de PDO (new PDO($dsn, $identityId, null, $options)). Utiliza el ID de cliente de la identidad en Azure App Service o Azure Container Instance; de lo contrario, utiliza su ID de objeto. Los controladores PHP heredan este comportamiento del controlador subyacente de Microsoft ODBC para SQL Server; para más información, consulte Uso de Microsoft Entra ID con el controlador ODBC. Utiliza el argumento del nombre de usuario del constructor PDO en lugar de incrustar el nombre de usuario en la DSN. Al pasar null como usuario (tal y como se muestra en el ejemplo), se selecciona la identidad administrada asignada por el sistema del host de Azure. Para SQLSRV (modo procedimental), pasa UID en la matriz de opciones de conexión.

• Establece MultiSubnetFailover=true cuando te conectes a un listener de un grupo de conmutación por error, a un listener de un grupo de disponibilidad o a un punto de conexión de una instancia de clúster de conmutación por error. Esta configuración mejora el rendimiento de la conexión tanto para listeners de grupos de disponibilidad de una sola subred como para los de varias subredes. Para más información, consulte Soporte para Alta Disponibilidad, recuperación ante desastres.

• Para el escalado horizontal de lectura o un secundario de solo lectura, añade ApplicationIntent=ReadOnly a la DSN.

• Utiliza el endpoint proporcionado por tu servicio SQL, incluyendo su dominio específico para la nube. Investigar las discrepancias entre nombres de certificados en lugar de desactivar la validación de certificados. Utiliza HostNameInCertificate solo cuando sepas el nombre esperado del certificado para ese endpoint.

• ODBC adquiere tokens para la identidad gestionada y la autenticación de la entidad de servicio. Con AccessToken, tu aplicación adquiere el token y lo pasa al controlador; ODBC no lo adquiere por ti. Para obtener más información, vea Uso de Microsoft Entra ID con ODBC Driver.

• Mantén la información de conexión fuera de tu código. Guárdalo en el sistema de configuración de tu aplicación y usa Azure Key Vault para los secretos.

• Con SQLSRV, se establecen las opciones de conexión en el array que se pasa a sqlsrv_connect(). Comprueba si tienes un valor de retorno false e inspecciona sqlsrv_errors() antes de decidir si quieres volver a intentarlo. Establece los tiempos de espera de las sentencias por separado con QueryTimeout. La resiliencia de la conexión inactiva demuestra la reconexión ODBC, no un bucle de reintentos a nivel de aplicación.

• Las funciones auxiliares de reintento leen $e->errorInfo[1] protegido por isset(). PDOException::$errorInfo se declara como ?array y tiene como valor predeterminado null, por lo que la comprobación defensiva recurre a un código de controlador de 0 y deja que el prefijo SQLSTATE 08 determine si se debe reintentar.

Para obtener más información sobre cada parte de esta configuración, consulte:

• Opciones de conexión
• Conéctate usando la autenticación de Microsoft Entra
• Resiliencia de la conexión en reposo
• Conexión a Microsoft Azure SQL Database
• Soporte para Alta Disponibilidad, recuperación ante desastres

Para consultar el catálogo de errores transitorios de Azure SQL, consulte Solucionar errores transitorios de conexión.

Características clave

• Dos API de PHP: SQLSRV proporciona funciones de procedimiento. PDO_SQLSRV implementa PDO. Instala una de las extensiones o ambas.
• Soporte para plataformas amplias: Funciona en Windows, Linux y macOS con versiones compatibles con PHP.
• Conexiones cifradas: Conexiones cifradas TLS mediante Encrypt=true, con la validación del certificado del servidor controlada por TrustServerCertificate.
• Autenticación Microsoft Entra ID: Identidad gestionada, principal de servicio y tokens de acceso adquiridos externamente a través del controlador subyacente Microsoft ODBC para SQL Server. La identidad administrada no usa contraseña; ActiveDirectoryServicePrincipal utiliza un secreto de cliente.
• Always Encrypted: Cifra las columnas sensibles en el cliente, con enclaves seguros para operaciones soportadas sobre datos cifrados.
• Resiliencia de conexión: La conexión inactiva incorporada se reintenta con ConnectRetryCount y ConnectRetryInterval.
• Flujos PHP: Envía grandes valores binarios y de caracteres desde parámetros de flujo con cualquiera de las APIs. Usa SQLSRV para la recuperación en streaming.
• Soporte para tipos de datos de Rich SQL Server: datetimeoffset, parámetros de valoración en tabla, nvarchar y Unicode con PDO::SQLSRV_ENCODING_UTF8.

Primeros pasos

Configuración y conexión

Authenticate

Secure

Recuperar y actualizar datos

Tipos de datos

Errores y diagnósticos

Despliegue y operación

Contenido de referencia

Tareas relacionadas

Solicitud de una característica

Para solicitar una característica, abre una incidencia en el repositorio de GitHub Microsoft Drivers for PHP for SQL Server.

Contenido relacionado

• Controladores de Microsoft para PHP para SQL Server en GitHub
• controlador ODBC de Microsoft para SQL Server
• Controladores y marcos de Microsoft SQL