Falling Out with Brew as My Package Manager

A few months ago, I wanted to update to the all new PHP 8.1 on my Mac. The installation was smooth until I wanted to add a couple of PHP 8.1 extensions, specifically xdebug.

Ever since brew migrated to Homebrew-core, it stopped doing PECL's role. That means installing xdebug is only through pecl install xdebug. Ok, no problem. I try the command and it attempts to install then, another bummer: 

........

Build process completed successfully
Installing '/usr/local/Cellar/php/8.1.0_1/pecl/20210902/xdebug.so'

Warning: mkdir(): File exists in System.php on line 294

Warning: mkdir(): File exists in /usr/local/Cellar/php/8.1.0_1/share/php/pear/System.php on line 294
ERROR: failed to mkdir /usr/local/Cellar/php/8.1.0_1/pecl/20210902

Other instances I would update my PHP version with Homebrew and npm suddenly stops working, and zsh would yell at me that it is not installed.

I have had to change my package manager for node and use nvm to resolve this, but that's a topic for another day. So how did I resolve this issue with xdebug?

Warning: mkdir(): File exists in System.php on line 294

Warning: mkdir(): File exists in /usr/local/Cellar/php/8.1.0_1/share/php/pear/System.php on line 294
ERROR: failed to mkdir /usr/local/Cellar/php/8.1.0_1/pecl/20210902

Change xdebug installation path by Homebrew

• Problem
• • pecl install xdebug uses /usr/local/Cellar/php/8.1.0_1/pecl from Homebrew to install xdebug. If we visit the 8.1.0_1 directory, we will find that its PECL is a symlink to /usr/local/lib/php/pecl:

• $ ls -al /usr/local/Cellar/php/8.1.0_1
  total 96
  drwxr-xr-x  15 bryce  admin    510 Dec  7 00:53 .
  drwxr-xr-x   3 bryce  admin    102 Dec  7 00:54 ..
  drwxr-xr-x   3 bryce  admin    102 Dec  7 00:53 .brew
  -rw-r--r--   1 bryce  admin   5098 Dec  7 00:53 INSTALL_RECEIPT.json
  -rw-r--r--   1 bryce  admin   3204 Nov 23 21:56 LICENSE
  -rw-r--r--   1 bryce  admin  14496 Nov 23 21:56 NEWS
  -rw-r--r--   1 bryce  admin   5162 Nov 23 21:56 README.md
  drwxr-xr-x  12 bryce  admin    408 Dec  7 00:53 bin
  -rw-r--r--   1 bryce  admin    577 Dec  7 00:53 homebrew.mxcl.php.plist
  -rw-r--r--   1 bryce  admin    266 Dec  7 00:53 homebrew.php.service
  drwxr-xr-x   3 bryce  admin    102 Dec  7 00:52 include
  drwxr-xr-x   4 bryce  admin    136 Dec  7 00:52 lib
  lrwxr-xr-x   1 bryce  admin     23 Dec  7 00:53 pecl -> /usr/local/lib/php/pecl
  drwxr-xr-x   3 bryce  admin    102 Dec  7 00:52 sbin
  drwxr-xr-x   4 bryce  admin    136 Dec  7 00:52 share

   
  • which pecl shows /usr/local/bin/pecl which is a symlink to /usr/local/Cellar/php/8.1.0_1/bin/pecl.
• Solution

Since Homebrew is no longer doing PECL's work, we can delete the PECL in 8.1.0_1 symlinked to /usr/local/lib/php/pecl:

$ rm /usr/local/Cellar/php/8.1.0_1/pecl

Re-install xdebug

Before the installation, let's take a look at our PHP configuration:

$ php --ini
Configuration File (php.ini) Path: /usr/local/etc/php/8.1
Loaded Configuration File:         /usr/local/etc/php/8.1/php.ini
Scan for additional .ini files in: /usr/local/etc/php/8.1/conf.d
Additional .ini files parsed:      /usr/local/etc/php/8.1/conf.d/ext-opcache.ini

Ok, now run the installation command:

$ pecl install xdebug

You should see a success message like the following:

Build process completed successfully
Installing '/usr/local/Cellar/php/8.1.0_1/pecl/20210902/xdebug.so'
install ok: channel://pecl.php.net/xdebug-3.1.2
Extension xdebug enabled in php.ini

Configure xdebug

If we run the configuration command again we should now get a warning:

$ php --ini
PHP Warning:  Failed loading Zend extension 'xdebug.so' (tried: /usr/local/lib/php/pecl/20210902/xdebug.so (dlopen(/usr/local/lib/php/pecl/20210902/xdebug.so, 9): image not found), /usr/local/lib/php/pecl/20210902/xdebug.so.so (dlopen(/usr/local/lib/php/pecl/20210902/xdebug.so.so, 9): image not found)) in Unknown on line 0

Why are we seeing this warning just after installing xdebug? 

Our PHP configuration is pointing to the wrong location of Zend extension xdebug.so. To fix this, open the /usr/local/etc/php/8.1/php.ini config file:

1. Edit the entry that says zend_extension="xdebug.so" and put the value seen in the success message (Install field) "/usr/local/Cellar/php/8.1.0_1/pecl/20210902/xdebug.so"
2. Add other entries to customize xdebug:

;XDebug
zend_extension="/usr/local/Cellar/php/8.1.0_1/pecl/20210902/xdebug.so"
xdebug.mode=coverage
xdebug.client_port=9003
xdebug.output_dir="/Users/bryce/xdebugtmp/"

Because I am using PHPUnit code coverage I had to put xdebug code to coverage. Remember also setting an output directory that exists.

If we run php --ini we won't see any warnings but if there are, xdebug will explain what config entries are incorrect.

When you now check your PHP version it wil also show the xdebug version installed:

$ php -v
PHP 8.1.0 (cli) (built: Dec  6 2021 21:49:43) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.0, Copyright (c) Zend Technologies
    with Zend OPcache v8.1.0, Copyright (c), by Zend Technologies
    with Xdebug v3.1.2, Copyright (c) 2002-2021, by Derick Rethans

Conclusion

I used to think I could totally rely on Homebrew for all my package dependencies but that's not the case now.

There are many caveats while working with it and it can definitely slow down your development as a beginner or an expert.