Microsoft PHP SQL 驱动在 Docker 中的架构兼容性问题解决方案

在基于 Docker 的 PHP 开发环境中使用 Microsoft 官方提供的 PHP SQL 驱动（msphpsql）时，开发者可能会遇到两种常见的架构兼容性问题。本文将深入分析这些问题产生的原因，并提供完整的解决方案。

问题背景分析

当在 Docker 容器中部署 PHP 应用并尝试连接 SQL Server 数据库时，使用 Microsoft 官方 PHP SQL 驱动可能会遇到以下两种错误：

1. ARM64 架构错误：表现为"PHP Fatal error: Unsupported processor architecture"错误
2. AMD64 架构错误：表现为"SQLSTATE[IMSSP]: This extension requires the Microsoft ODBC Driver for SQL Server"错误

这些问题的根源在于驱动与不同处理器架构之间的兼容性问题，以及 ODBC 驱动安装配置不当。

详细解决方案

1. 基础环境准备

首先确保 Dockerfile 中已正确设置基础环境：

FROM ubuntu:22.04
ENV DEBIAN_FRONTEND=noninteractive
ENV ACCEPT_EULA=Y

2. 安装必要依赖

安装 PHP 8.2 和基础开发工具：

RUN apt-get update && apt-get install -y \
    php8.2-cli \
    php8.2-dev \
    unixodbc \
    unixodbc-dev \
    gnupg \
    curl

3. 安装 Microsoft ODBC 驱动

针对不同架构需要采用不同的安装方式：

# 添加 Microsoft 软件源
RUN curl https://packages.microsoft.com/keys/microsoft.asc | tee /etc/apt/trusted.gpg.d/microsoft.asc \
    && curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | tee /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update

4. 安装 SQL Server 工具

RUN apt-get install -y msodbcsql18 mssql-tools18

5. 安装 PHP SQL 驱动

RUN pecl install sqlsrv-5.12.0 \
    && pecl install pdo_sqlsrv-5.12.0 \
    && echo "extension=sqlsrv.so" > /etc/php/8.2/mods-available/sqlsrv.ini \
    && echo "extension=pdo_sqlsrv.so" > /etc/php/8.2/mods-available/pdo_sqlsrv.ini \
    && phpenmod sqlsrv pdo_sqlsrv

6. OpenSSL 兼容性配置

SQL Server 连接需要特定版本的 OpenSSL：

RUN wget -O ~/openssl-1.1.1f.tar.gz https://www.openssl.org/source/openssl-1.1.1f.tar.gz \
    && mkdir -p /opt/openssl \
    && tar xfvz ~/openssl-1.1.1f.tar.gz --directory /opt/openssl \
    && cd /opt/openssl/openssl-1.1.1f \
    && ./config --prefix=/opt/openssl --openssldir=/opt/openssl/ssl \
    && make install

7. 环境变量配置

设置必要的环境变量：

ENV LD_LIBRARY_PATH=/opt/openssl/lib:$LD_LIBRARY_PATH
ENV OPENSSL_CONF=/opt/openssl/ssl/openssl.cnf

架构兼容性关键点

1. ARM64 架构：确保使用支持 ARM64 的 ODBC 驱动版本
2. AMD64 架构：验证 ODBC 驱动是否正确安装并配置
3. 多阶段构建：建议使用多阶段构建减少最终镜像大小
4. 版本匹配：保持 PHP 驱动与 ODBC 驱动版本兼容

验证步骤

构建完成后，可通过以下命令验证安装是否成功：

php -i | grep sqlsrv
php -r "new PDO('sqlsrv:server=localhost;Database=test', 'user', 'password');"

总结

通过上述步骤，可以解决 Microsoft PHP SQL 驱动在 Docker 环境中的架构兼容性问题。关键在于正确安装对应架构的 ODBC 驱动，配置适当版本的 OpenSSL，并确保环境变量设置正确。这种方法适用于大多数基于 Ubuntu 的 PHP 容器环境，能够稳定连接 SQL Server 数据库。