Resolving PHP Extension Errors in Vagrant Magento 2.0.2 Environments
When attempting to install Magento 2.0.2 via Composer within a Vagrant environment running Ubuntu, you may encounter an error indicating that the ext-gd extension is missing. The error message explicitly lists several .ini files where extensions should be verified: /etc/php5/cli/php.ini, /etc/php5/cli/conf.d/05-opcache.ini, and others like 20-curl.ini. Even if you believe you have installed the necessary packages, such as php5-cli and php5-curl, Composer will still fail with a dependency resolution error stating that the requested PHP extension is missing from your system.
The core issue lies in understanding how PHP manages extensions on Ubuntu systems. Installing a package like php5-curl via apt-get typically installs the shared object file (.so) and places it in /usr/lib/php/..., but it does not automatically enable the extension for CLI execution unless explicitly configured. The error message provides a list of .ini files used by PHP in CLI mode, but these are often generated dynamically or managed through drop-in configuration directories rather than a single monolithic file.
To resolve this, you must ensure that the extension is both present and enabled in the active configuration. On Ubuntu systems using PHP 5 (as indicated by the /etc/php5/ path in the error), extensions are usually managed under /etc/php5/cli/conf.d/. If the gd.ini file exists there but is commented out, you need to uncomment it. Alternatively, if the file doesn't exist, you may need to create it or install the development package that provides the configuration template.
Run the following commands inside your Vagrant terminal:
sudo apt-get update
sudo apt-get install php5-gd
sudo touch /etc/php5/cli/conf.d/20-gd.ini
echo "extension=gd" | sudo tee /etc/php5/cli/conf.d/20-gd.ini
After creating or modifying the configuration file, restart any running PHP services if applicable, though for CLI usage, a simple verification step is sufficient. Run php --ini to confirm that the gd extension now appears in the loaded extensions list. If it shows up under "Loaded Configuration File" and "Additional INI files", then Composer should be able to resolve the dependency correctly.
Another common pitfall is assuming that installing php5-cli and php5-curl implies all other core extensions are active. This assumption often leads developers to overlook missing dependencies like GD, which is critical for image processing features in Magento. Always verify extension availability using:
php -m | grep gd
If the command returns nothing, the extension is not loaded, regardless of whether the .so file exists on disk.
In some cases, especially with older PHP versions like 5.3 or 5.4 used by Magento 2.0.2, you might face conflicts between different PHP modules or version mismatches. Ensure that your Vagrant machine is configured to use the correct PHP binary path specified in your composer.json or project settings.
If you're managing multiple environments, consider documenting which extensions are required for each project version to avoid repetitive troubleshooting. For more complex setups involving custom themes or third-party modules, always double-check extension requirements before proceeding with installation.