[Microsoft][ODBC Driver 17 for SQL Server] SSL Provider: [error:0A000102:SSL routines::unsupported protocol] in PHP Laravel on macOS using Brew

[Microsoft][ODBC Driver 17 for SQL Server] SSL Provider: [error:0A000102:SSL routines::unsupported protocol] in PHP Laravel on macOS using Brew

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

Stefan Bogdanescu

Founder & Senior Architect

Fixing the "Unsupported Protocol" SSL Error on macOS with PHP and SQL Server

Encountering the [Microsoft][ODBC Driver 17 for SQL Server] SSL Provider: [error:0A000102:SSL routines::unsupported protocol] error in a Laravel application on macOS is a specific friction point caused by a mismatch between OpenSSL versions. This issue typically surfaces after updating Homebrew packages, where the default OpenSSL 3 installation replaces the legacy OpenSSL 1.1 that many Windows-specific ODBC drivers expect.

The core of the problem lies in how the Microsoft SQL Server driver interacts with the underlying SSL library. The msphpsql extension (often bundled as pdo_sqlsrv) relies on specific SSL functions to encrypt the connection. When Homebrew upgrades OpenSSL to version 3, it enforces modern security defaults that can be incompatible with older ODBC drivers designed for earlier versions. Switching back to OpenSSL 1.1 might resolve the protocol error but introduces a different set of vulnerabilities and compatibility risks, creating a stalemate where neither option works cleanly.

Verifying Your OpenSSL Configuration

To understand exactly which library your PHP installation is using, you need to inspect the build flags. Run the following command in your terminal:

php -i | grep openssl

Look for the openssl.cafile or openssl.version entries. More critically, check the underlying library path:

brew --prefix openssl
ls -la /usr/local/bin/openssl

If your system is using the default Homebrew OpenSSL 3 (often located at /opt/homebrew/opt/openssl@3 on Apple Silicon or /usr/local/opt/openssl@3 on Intel), the ODBC driver will likely fail to initialize the SSL handshake because it expects the legacy API surface.

Resolving the Mismatch Without Rolling Back Entirely

The most robust solution is not to downgrade your system-wide OpenSSL but to isolate the environment for the PHP extension. Since you are using homebrew-php, you can force that specific PHP binary to use a compatible SSL library or configure the driver to bypass strict SSL checks if encryption is not strictly required for your security posture.

However, the preferred architectural fix involves ensuring the ODBC driver itself is compiled against the correct libraries or linking them explicitly.

Option 1: Force OpenSSL 3 Compatibility (Recommended)

If you are comfortable updating the driver logic, you must ensure the pdo_sqlsrv extension can handle OpenSSL 3. The error suggests the driver is calling an unsupported function. You may need to update the ODBC Driver version itself, as Microsoft frequently patches these issues in newer releases of the Microsoft.OdbcDriver17.

Check your current driver version:

php -r "echo 'SQL Server Driver Version:' . SQLSRV_VERSION();"

If you have an older PHP version (like 8.2), you might be limited to a specific driver version that hasn't patched this OpenSSL 3 bug yet. In this case, upgrading PHP to a version where the pdo_sqlsrv extension is updated for OpenSSL 3 compatibility is often necessary.

Option 2: Configure Laravel Connection Settings

If updating packages immediately isn't feasible, you can attempt to configure the connection string to use a TLS version that both sides agree upon, or disable SSL verification temporarily for testing purposes (never in production without strict controls).

In your config/database.php file, modify the sqlsrv connection array:

'sqlsrv' => [
    'driver' => 'sqlsrv',
    'url' => env('DATABASE_URL'),
    'host' => env('DB_HOST', 'localhost'),
    'port' => env('DB_PORT', 1433),
    'database' => env('DB_DATABASE', 'forge'),
    'username' => env('DB_USERNAME', 'forge'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8',
    'prefix' => '',
    'prefix_indexes' => true,
    'strict' => true,
    'engine' => null,
    // Attempt to disable strict SSL enforcement or specify a TLS version
    'options' => [
        'Encrypt' => 1, 
        'TrustServerContext' => false, // Set to true only if using Azure with built-in cert
        'ConnectionTimeout' => 30,
        'LoginTimeout' => 30,
        'MultipleActiveResultSets' => false,
        'PDOAttrColumnCaseSensitivity' => -1,
        // Explicitly set SSL context to avoid OpenSSL 3 defaults if needed
        'SSLProvider' => '', 
    ],
],

Note that the Encrypt option is crucial. Setting it to 0 disables encryption entirely, which resolves the protocol error but exposes data in transit. Setting it to 1 requires the driver and OpenSSL versions to be compatible. If you must use Encrypt => 1, ensure your openssl.cnf file points to a certificate authority that the legacy driver recognizes.

The Trade-Off: Security vs. Compatibility

The decision here is between maintaining security via OpenSSL 3 (which requires newer drivers) and ensuring compatibility via OpenSSL 1.1 (which reverts to legacy security models). For local development on macOS, using brew install openssl@1.1 alongside your main installation allows you to explicitly link the PHP build to the older library if necessary, though this is often a stopgap measure until Microsoft releases an ODBC driver patch that supports OpenSSL 3 natively.

Always verify the exact version of the msphpsql extension installed via composer show phpoffice/phpspreadsheet or direct installation methods, as third-party wrappers sometimes bundle older drivers that inherit these SSL incompatibilities.

Our network