Solving the Missing PHP Extension Error: Installing Laravel on macOS

Dealing with dependency errors during local development setup can be incredibly frustrating, especially when you’ve followed guides that seem tailored for different operating systems. The scenario you've described—where Composer demands a missing PHP extension like zip when installing tools like laravel/installer, coupled with difficulties using Homebrew to install the required package—is a classic symptom of environment configuration issues on macOS.

As a senior developer, I can assure you that this problem rarely has a single, universally applicable fix; it usually stems from how PHP was compiled or installed on your specific system. Let's dive into why this happens and how we can reliably resolve it so you can start building with Laravel without further hindrance.

Understanding the Composer Dependency Failure

When you run composer global require "laravel/installer", Composer doesn't just install files; it checks the dependencies required by the package. In this case, laravel/installer requires the PHP zip extension to function correctly. When Composer checks your system and cannot find this extension compiled into your active PHP installation (which you noted is PHP 7.3.0beta2), it throws an error because the prerequisite is missing.

The failure of brew install php7.2-zip further points to a specific macOS/Homebrew dependency issue. Homebrew manages packages, but sometimes extensions need to be built against the exact version of PHP currently active in your environment. If the necessary compilation tools or dependencies for that specific PHP version are missing, Homebrew cannot find or build the extension correctly.

The Developer Solution: Fixing the PHP Environment

Since direct package installation via Homebrew failed, we need to focus on ensuring your current PHP setup is complete and properly configured to support Composer's needs.

1. Verify the Actual PHP Path and Installation

Before attempting further installs, confirm exactly which PHP executable Composer is using and where it expects extensions to reside. Use the command you already ran:

php --ini

Reviewing this output helps pinpoint if the system is pointing to a freshly installed version or an older, potentially incomplete build. If the path points to /usr/local/php5/... (as seen in your output), it suggests that the PHP installation being used by the command line might be separate from what Homebrew manages, which complicates dependency resolution.

2. Rebuilding and Ensuring Extension Support

If you are using Homebrew for PHP management, the most robust solution is often to ensure all necessary build tools are present and then attempt a complete reinstallation or link of the required components. While direct extension installation can be tricky on macOS, ensuring the core environment is sound is key.

For many complex dependencies, especially when dealing with framework setups like those found on laravelcompany.com, running a clean install within a controlled container environment often bypasses these system-level conflicts entirely.

3. The Recommended Alternative: Docker for Pristine Environments

While debugging local system issues is valuable, I strongly recommend adopting a containerized approach for initial Laravel setup on macOS. Using Docker (or tools like Laravel Sail) provides an isolated environment where you control the exact PHP version and all necessary extensions from scratch. This eliminates dependency conflicts related to Homebrew, system paths, and missing compilation flags.

If you must stick to a local installation, after confirming your PHP installation path, ensure you are using the specific command provided by your PHP manager (e.g., if you installed PHP via MAMP or another method, use that tool's extension management methods) rather than relying solely on Homebrew formulae for core extensions in complex scenarios.

Conclusion

The missing ext-zip error is a dependency resolution failure rooted in the interaction between Composer and your local PHP environment on macOS. While trying to manually install system packages can lead to further dead ends, shifting focus to ensuring a clean, reproducible environment—like using Docker—is often the fastest and most reliable path forward for modern PHP development. By isolating dependencies, you ensure that your project setup is robust, regardless of underlying operating system quirks.