Resolving PHP Library Loading Errors After Installing Node.js via Homebrew on macOS

Problem Phenomenon and Background Analysis

On macOS Mojave systems, users frequently encounter runtime errors in their PHP environment after installing Node.js through the Homebrew package manager. When executing the php -v command, the system reports an error: dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.62.dylib, indicating that the specified dynamic library file cannot be found. This type of error typically stems from dependency conflicts between software packages, particularly when using package managers like Homebrew where different packages may have incompatible version requirements for shared libraries.

In-depth Error Mechanism Analysis

dyld (dynamic linker) is the core component responsible for loading shared libraries in macOS systems. When the PHP executable starts, dyld searches for and loads its dependent shared libraries according to predefined paths. The error message indicates that the system cannot find the specific version of the ICU (International Components for Unicode) library file libicui18n.62.dylib at the path /usr/local/opt/icu4c/lib/.

The ICU library provides internationalization and localization support for software, including character encoding conversion, date-time formatting, and other functionalities. Both PHP and Node.js may depend on the ICU library, but each might require different versions. When installing new software packages through Homebrew, the package manager may automatically upgrade shared libraries to newer versions, causing existing software to be unable to find the older version library files they depend on.

Systematic Solution Approach

Based on problem analysis, we provide the following systematic resolution steps:

Upgrade Related Software Packages

First attempt to upgrade the icu4c library to the latest version to ensure the system has a complete dependency environment:

brew upgrade icu4c

If the problem persists, consider upgrading all software packages installed via Homebrew:

brew upgrade

Note: This operation will upgrade all installed Homebrew software packages, including PHP and other potentially affected programs. If you wish to upgrade only specific packages, use the brew upgrade <package_name> command to specify particular package names.

Clean System Cache

After completing the upgrade, perform cleanup operations to remove old version files and caches:

brew cleanup

This command will delete all old version installation files from the Homebrew cache, freeing disk space and ensuring the system uses the latest library files.

Supplementary Solutions

In some special cases where upgrade operations cannot resolve the problem, version switching might be necessary. Use brew info icu4c to view installed version information, then employ brew switch icu4c <version> to switch to a specific version. This approach is suitable for scenarios requiring maintenance of specific library version compatibility.

Preventive Measures and Best Practices

To prevent similar issues from recurring, developers are advised to:

• Regularly run brew update && brew upgrade to maintain software packages in their latest state
• Check potential dependency impacts before installing new software packages
• Consider using virtual environments or container technologies to isolate dependency environments for different projects
• Perform comprehensive dependency compatibility testing before deploying critical projects

Technical Principle Extension

From reference cases, it's evident that similar problems occur not only in PHP environments but also in projects like React Native. This reflects the complexity of dependency management in modern software development. Dynamic library version management requires balancing the introduction of new features with backward compatibility, and developers should establish robust dependency monitoring and version control mechanisms.