The PCRE2 Header Dilemma on macOS
When attempting to install openswoole on a modern macOS environment using Homebrew, you will inevitably hit a compilation failure if your system lacks the specific headers required by PHP's internal PCRE extension. The error message is blunt: fatal error: pcre2.h: No such file or directory. This occurs because the source code for openswoole (or any extension built against it) explicitly includes <pcre2.h>, which is distinct from the legacy <php_pcre.h> found in standard PHP installations.
The root of the confusion lies in how Homebrew manages packages versus what PHP expects to find during the build process. A common recommendation suggests running brew install pcre. However, this command often fails to resolve the issue because the pcre formula in Homebrew typically installs the legacy PCRE library (version 1), while modern PHP extensions, including those bundled with Swoole, require the PCRE2 library (version 2). The two libraries are incompatible at the header level. Installing only the legacy package leaves your system with /usr/local/Cellar/pcre/... containing php_pcre.h, but without the required pcre2.h.
To fix this, you must explicitly install the PCRE2 library via Homebrew. Run the following command to ensure the correct version is present:
brew install pcre2
Once installed, verify that the headers are accessible. The compiler needs to locate these files in its include path. By default, Homebrew installs dependencies into /usr/local/include (on Intel Macs) or /opt/homebrew/include (on Apple Silicon). If your PHP is installed via Homebrew (brew install php@7.4), it should automatically detect the new headers in the system's standard include paths during compilation.
If the error persists after installing pcre2, you must ensure that the compiler is looking in the correct directory. Sometimes, the build process for openswoole defaults to the PHP installation's internal include path rather than the global system path where Homebrew installs its dependencies. You can force the compiler to find the headers by setting the PCRE2_DIR environment variable before running your installation script or composer install command:
export PCRE2_DIR=/usr/local/include
# For Apple Silicon (M1/M2):
# export PCRE2_DIR=/opt/homebrew/include
composer install
Alternatively, you can pass the --with-pcre flag to the PHP build if you are compiling PHP from source, though this is rarely necessary for standard openswoole installations where PHP is already present. The key distinction is ensuring that the library and the header files for PCRE2 are both present and visible to the C compiler.
Another potential pitfall involves conflicting installations. If you previously installed the legacy pcre package, it might have created symlinks or left old configuration in place that confuses the build system. It is often prudent to run brew cleanup pcre before installing pcre2. This ensures no stale headers are being picked up by the compiler.
Finally, consider the context of your PHP setup. If you are using a specific PHP version via Homebrew (e.g., php@7.4), ensure that this version is aware of the system-wide PCRE2 installation. In most cases, modern Homebrew formulas respect the standard include paths automatically once pcre2 is installed. However, if you encounter issues with openswoole specifically regarding PCRE configuration, check your php.ini or extension build flags to ensure the correct library path is being linked. This situation highlights a common friction point between legacy PHP extensions and modern system libraries, where explicit installation of the versioned dependency (pcre2) is non-negotiable.
For developers managing complex PHP environments, particularly those integrating high-performance modules like Swoole, keeping your Homebrew dependencies strictly up to date and version-aligned is essential. Avoiding reliance on legacy packages prevents exactly this class of compilation errors.