Using Sqlsrv for PHP 8.2

Using Sqlsrv for PHP 8.2

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Resolving the PHP 8.2 and SQLSRV Extension Path Mismatch on Ubuntu

When integrating Microsoft's SQL Server drivers into a modern PHP environment, you often encounter a specific friction point involving shared object file paths. This issue is particularly prevalent when upgrading to PHP 8.2 on legacy distributions like Ubuntu 20.04. The core problem stems from how the sqlsrv package manages its installation directory relative to the actual PHP binary version in use.

The error message PHP Startup: Unable to load dynamic library 'sqlsrv.so' (tried: /usr/lib/php/20220829/sqlsrv.so ...) is a clear indicator that the PHP runtime is looking for the extension in a directory corresponding to its internal version string (20220829), but the package installer has placed the library in an older directory structure (20210902). This discrepancy usually occurs because the php-sqlsrv package on Ubuntu repositories often defaults to the version of PHP headers it was originally compiled against or targets a generic path that doesn't align with a specific minor release's internal date-based naming convention.

Simply moving the .so files from /usr/lib/php/20210902/ to /usr/lib/php/20220829/ is frequently a trap rather than a solution. While this might satisfy the loader at startup, it introduces significant runtime instability. If your application loads multiple PHP modules—such as pdo_sqlsrv, mbstring, or standard core extensions—that are also installed in the older directory structure, you risk triggering the specific error mentioned in your troubleshooting log: attempting to load two different versions of the same library or conflicting internal states. This creates a scenario where the extension appears loaded but fails silently during execution, leading to cryptic "function not found" errors later on.

The most robust resolution involves aligning the PHP configuration (php.ini) to explicitly point to the correct location of the shared object, rather than relying on the automatic loader to guess the path based on the binary's directory structure. You can achieve this by ensuring the extension_dir directive in your active php.ini file points specifically to /usr/lib/php/20210902.

To implement this safely:

  1. Verify the exact PHP version string used by your server or CLI. Run php -v and note the version number (e.g., 8.2.x).
  2. Identify the directory containing the compiled extension. In this specific case, that is /usr/lib/php/20210902.
  3. Locate your active php.ini file. For Ubuntu 20.04 with PHP 8.2 installed via packages, this is typically located at /etc/php/8.2/cli/php.ini or /etc/php/8.2/apache2/php.ini. Note that the directory name in the config path (e.g., 8.2) does not always match the internal date string used by the shared object files.
  4. Add or uncomment the line extension=sqlsrv.so and ensure extension_dir="/usr/lib/php/20210902" is set correctly within that file.

If you are managing a production environment where directory pollution is a concern, another approach is to compile the extension against your specific PHP headers. This ensures the .so file is generated directly into the correct versioned directory (e.g., /usr/lib/php/20220829). However, this requires having the Microsoft ODBC driver SDK installed and php-dev packages matching your system's architecture.

It is also worth noting that if you are using Laravel or a similar framework, ensuring the correct PHP version is loaded for the web server (Apache/Nginx) versus the CLI tool is critical. Misconfigurations here can lead to situations where the database connection works in Tinker but fails on your application routes. For more details on managing multi-version PHP setups and extension loading strategies, resources like https://laravelcompany.com often provide context on maintaining clean dependency trees in modern stacks.

By explicitly defining the extension_dir to match where the package manager actually placed the files, you bypass the need to manually move binaries and avoid the risk of loading conflicting library versions. This approach keeps your system state consistent and ensures that the PHP startup process finds exactly what it expects without ambiguity.

Our network