You must enable the openssl extension to download files via https

You must enable the openssl extension to download files via https

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

Stefan Bogdanescu

Founder & Senior Architect

The OpenSSL Extension Misconfiguration Trap

When setting up a new Zend Framework 2 project using the skeleton application, the standard workflow involves running php composer.phar install within the directory. This command triggers Composer to download dependencies from its default repositories, which are hosted over HTTPS. If your environment returns the error "You must enable the openssl extension to download files via https," the issue isn't a network problem or a firewall blocking traffic; it is a specific PHP configuration failure.

This error occurs because PHP's internal HTTP client relies on the OpenSSL extension to establish secure SSL/TLS connections. When you run Composer, it attempts to fetch packages from packagist.org. If the openssl extension is either missing or not loaded into your current PHP runtime, the underlying cURL library used by Composer cannot negotiate a secure connection. Consequently, the request fails immediately before any data transfer occurs, triggering this specific exception.

The first step in resolving this is verifying that the extension file exists on your system and that it has been successfully loaded. In many Windows environments, particularly those using WAMP or XAMPP, the php.ini file might contain the line extension=php_openssl.dll. However, the mere presence of this line does not guarantee success. You must confirm that PHP is actually loading the file at runtime.

Run the following command in your terminal:

php -m | grep openssl

If this returns no output, the extension is disabled despite being listed in your configuration files. This often happens because multiple php.ini files exist in different directories, and Composer might be invoking a PHP binary that reads a different configuration than the one you edited manually. For instance, on Windows, there are often php.ini-development, php.ini-production, and a default php.ini. Ensure you are editing the active file used by your specific PHP executable.

If the extension is missing from your active php.ini, add or uncomment the line:

extension=php_openssl.dll

After making changes, restart your web server or CLI tools to ensure the new configuration takes effect. You can verify the fix by running a simple test script:

<?php
echo "OpenSSL Version: " . openssl_version() . "\n";
echo "Library Version: " . openssl_libversion() . "\n";
?>

If this script executes without error and prints version numbers, the extension is loaded. Run composer install again in your project directory to see if the HTTPS connection succeeds now.

There are scenarios where enabling the extension via php.ini isn't enough. On some systems, you may need to explicitly load the shared library using -d extension=php_openssl.dll when invoking PHP directly, especially if you are using a custom setup or a specific PHP-FPM pool configuration. Additionally, ensure that your OpenSSL library binaries (the .dll files) are actually present in the ext directory and that there are no permission issues preventing PHP from loading them.

In production environments or containerized setups like Docker, this issue frequently arises because the base image might not include the OpenSSL development libraries or the extension binaries by default. When building an image based on php:7.x-apache, you must ensure the openssl package is installed and that the corresponding PHP extension is enabled in the resulting container's configuration.

Understanding the root cause here prevents a common class of deployment failures. Many developers assume that if SSL works in their web browser, it will work for CLI tools like Composer. However, CLI tools use the system PHP installation directly, which must be explicitly configured to handle secure protocols. By ensuring the OpenSSL extension is active, you guarantee that your build tools can communicate securely with modern package registries.

For those managing large-scale applications or maintaining legacy codebases, this distinction between browser-based SSL and CLI-based SSL remains a critical architectural detail. If you are integrating Composer into a CI/CD pipeline, failing to enable the OpenSSL extension in your build agent's PHP configuration will cause builds to fail silently until you inspect the logs for this specific error message. Addressing it early saves significant debugging time later in the development lifecycle.

Our network