phpmon

All stable and supported PHP versions are also supported by PHP Monitor. However, depending on which version of Valet you have installed, which versions of PHP that are made available for switching purposes may differ.

Note
If you have versions of PHP installed that can be detected by PHP Monitor but is not supported by the currently active version of Valet, you will be alerted by an item in the menu with an exclamation mark emoji. (⚠️)

Backports that are installable via PHP Monitor’s PHP Version Manager functionality are subject to availability via this tap.

PHP extensions that are installable via PHP Monitor’s PHP Extension Manager functionality are subject to availability via this tap.

For maximum compatibility with older PHP versions, you may wish to keep using Valet 2 or 3. For more information, please see SECURITY.md to find out which versions of PHP are supported with different versions of Valet.

Assuming you have installed the php formula, the latest stable version of PHP is installed. At the time of writing, this is PHP 8.3.

You can install other supported versions of PHP via PHP Monitor’s PHP Version Manager. (You can manually install or upgrade PHP versions too, but this is not recommended.)

Please keep in mind that installing or updating PHP versions, even when done via PHP Monitor’s PHP Version Manager, may cause other required formula dependencies (required software needed to keep those PHP versions functional) to be upgraded. It might not be very transparent when this happens, but this is likely the cause if installing a PHP version takes longer than expected: usually other dependencies are also being installed.

Additionally, upgrading one specific version of PHP may also cause other installed versions of PHP to also be updated in one go, if the dependencies for that one version also apply to the other (newer) version(s) of PHP. It’s a bit tricky to manage PHP versions via Homebrew, and even PHP Monitor may encounter some difficulties.

If you encounter a strange scenario or a malfunction, please open an issue on the issue tracker and get in touch. I’d like to keep enhancing this process to make it as foolproof as possible.

Note: Using PHP Monitor when managing PHP versions may cause temporary alias conflicts while the core tap alias and the tap’s alias refer to a different version of PHP, but this is generally speaking a minor inconvenience, since this normally only applies when a new PHP version releases.

If you are running macOS Ventura or newer, there’s an option in the Settings menu that you can select: “Start PHP Monitor at login”.

If you are on an older version of macOS, you can do this by dragging PHP Monitor.app into the Login Items section in System Preferences > Users & Groups for your account.

Super convenient!

The services manager is disabled, and all other obvious Laravel Valet integrations (configuration finder, domains list, Fix My Valet) are also disabled.

(Most other features remain available.)

If you want to set up your computer for the very first time with PHP Monitor, here’s how I do it.

I have also created a video tutorial which may be easier to follow. If you just want the terminal commands, keep reading.

Install Homebrew first. Follow the instructions there first!

Then, you’ll need to set up your PATH.

nano .zshrc

Make sure the following line is not in the comments:

# on an Intel Mac
export PATH=$HOME/bin:/usr/local/bin:$PATH

If you’re on an Apple Silicon-based Mac, you’ll need to add:

# on an M1 Mac
export PATH=$HOME/bin:/opt/homebrew/bin:$PATH

and add the following to your .zshrc file, but add this BEFORE the homebrew PATH additions:

export PATH=$HOME/bin:~/.composer/vendor/bin:$PATH

If you’re adding composer and Homebrew binaries, ensure that Homebrew binaries are preferred by adding these to the path last. On my system, that looks like this:

export PATH=$HOME/bin:/usr/local/bin:$PATH
export PATH=$HOME/bin:~/.composer/vendor/bin:$PATH
export PATH=$HOME/bin:/opt/homebrew/bin:$PATH

If you are not on Apple Silicon, you should remove the third line.

Install the php and composer formulae:

brew install php composer

Make sure PHP is linked correctly:

which php

should return: /usr/local/bin/php (or /opt/homebrew/bin/php if you are on Apple Silicon)

If you don’t need Laravel Valet, you can stop here. PHP Monitor will work like this in Standalone Mode.

If you’d like to have Valet as well, continue and install Valet with Composer, like this.

composer global require laravel/valet

For optimal results, you should lock your PHP platform for global dependencies to the oldest version of PHP you intend to run. If that version is PHP 7.0, your ~/.composer/composer.json file could look like this (please adjust the version accordingly!):

{
    "require": {
        "laravel/valet": "^3.0",
    },
    "config": {
        "platform": {
            "php": "7.0"
        }
    }
}

Run composer global update again. This ensures that when you switch to a different global PHP version, Valet won’t break. If it does, PHP Monitor will let you know what you can do about this.

Then, install Valet:

valet install

This should install dnsmasq and set up Valet. Great, almost there!

valet trust

Finally, run PHP Monitor. Since the app is notarized and signed with a developer ID, it should work. You will need to approve the initial launch of the app, but you should be ready to go now.

PHP Monitor will check if an update is available every time you start the app.

You can disable this behaviour by going to Preferences (via the PHP Monitor icon in the menu bar) and unchecking “Automatically check for updates”. (You can always check for updates manually.)

The easiest way is to simply use the built-in PHP Version Manager, which will allow you to upgrade your PHP versions with one click.

If you want to do this manually, you can follow the instructions below.

It’s easy to make a mistake here, and end up with an unlinked version of PHP or have versions missing from PHP Monitor.

Here’s what I usually do:

• Open PHP Monitor and select First Aid & Services > Restore Homebrew Permissions.
• Close PHP Monitor after the pop-up tells you the permissions were restored.
• Run brew update-reset
• Run brew upgrade

If after this, any PHP versions are missing in PHP Monitor, please run the following for the versions that are missing:

• Run brew uninstall [email protected] (where x.x is the version)
• Run brew cleanup (if you get any permission issues you may need to manually clean up the folder)
• Run brew install [email protected] (where x.x is the version)

You may still need to run brew link php after upgrading, too.

That’s it. Now start up PHP Monitor again and you should be golden!

Try installing again using brew install php.

This should resolve the issue! If that does not fix the issue, run brew link php --force. (Afterwards, you may need to restart your terminal to make sure the new linked version is detected.)

brew install php
brew link php --force

If you’re visiting your .test domain, and you’re getting a 502 (Bad Gateway) after switching to a different PHP version, you’re dealing with a common issue.

This problem is usually resolved by upgrading Valet and running valet install again.

composer global update
valet install

If you are seeing a 502 (Bad Gateway) error after about 30 seconds or so, your request is likely timing out. You may need to solve a performance issue with your own code.

PHP Monitor tells you that a PHP installation is broken, if the configuration is causing warnings or errors when determining the version number.

Since PHP Monitor changes the linked version via Homebrew, both Valet and your terminal (CLI) should use the new PHP version.

However, this might not be the case on your system. You might have a specific version of PHP linked if that is not the case. In that case, you may need to change your .bashrc or .zshrc file where the PATH is set (depending on the terminal you use).

You can find out which version of PHP is being used by running which php.

You can find out what exactly is causing the issue by running a command. On Intel, you can run (replace 7.4 with the version that is broken):

/usr/local/opt/[email protected]/bin/php -r "print phpversion();"

On Apple Silicon, you can run (replace 7.4 with the version that is broken):

/opt/homebrew/opt/[email protected]/bin/php -r "print phpversion();"

You should see an error or a warning here in the output.

Usually this is a duplicate extension declaration causing issues, or an extension that couldn’t be loaded. You’ll have to solve that issue yourself (usually by removing the offending extension or reinstalling).

Make sure you have at least Valet 3.0 installed, since support for isolation was added in this version of Valet. (Please note that this version of Valet drops support for PHP 5.6.)

The value you provided in your .ini file is invalid. If that is the case, PHP will attempt to parse your value as bytes, which is usually unintended. (1GB will resolve to merely a few bytes, and all of your applications will run out of memory!)

You must a provide a value like so: 1024K, 256M, 1G. Alternatively, -1 is also allowed, or just an integer (which will result in N amount of bytes being the limit).

Example: Trying to use 1GB as the memory limit, for example, will result in this exclamation mark. The correct way to set a 1GB limit is by using 1G as the value. (Note: The displayed value will append B for clarity, so if you set 1G, the value reported by PHP Monitor will be 1 GB.)

(If you are using Valet, you can adjust these limits in the .conf.d/php-memory-limits.ini file. Otherwise, you may need to adjust php.ini.)

The app searches in the relevant .ini files for a specific pattern. For regular extensions:

• extension="*.so"
• ; extension="*.so"

For Zend extensions:

• zend_extension="*.so"
• ; zend_extension="*.so"

The * is a wildcard and the name of the extension. If you’ve commented out the extension, make sure you’ve commented it out with a semicolon (😉 and a single space after the semicolon for PHP Monitor to detect it.

Since v3.4 all of the loaded .ini files are sourced to determine which extensions are enabled.

If you are using PHP Monitor on an Intel machine or on an Apple Silicon machine with Rosetta enabled, PHP Monitor expects the main Homebrew binary in /usr/local/bin/brew.

If you are using PHP Monitor on Apple Silicon without Rosetta, PHP Monitor expects the main Homebrew binary in /opt/homebrew/bin/brew.

If there’s an issue here, you’ll get an alert at launch.

Make sure that the version of Homebrew that you are running normally is the same as the one that PHP Monitor expects. If you are on M1 hardware for example, but still using Rosetta for Homebrew, you’ll need to run PHP Monitor under Rosetta as well.

PHP Monitor is a universal app and supports both architectures, so find out here how to enable Rosetta with PHP Monitor.

The app will automatically check for updates, which is the most likely culprit.

This happens at launch (unless disabled), and the app directly checks the Caskfile hosted on GitHub. This data is not, and will not be used for analytics (and, as far as I can tell, cannot).

I also can’t prevent brew from doing things via the network when PHP Monitor uses the binary.

The app includes an Internet Access Policy file, so if you’re using something like Little Snitch there should be a description why these calls occur.

You must set these presets up in a JSON file, located in ~/.config/phpmon/config.json.

You must have set up at least one valid preset for this presets to work in PHP Monitor.

Here’s an example of a working preset:

{
    "scan_apps": [],
    "services": [],
    "presets": [
        {
            "name": "Legacy Project",
            "php": "8.0",
            "extensions": {
                "xdebug": false
            },
            "configuration": {
                "memory_limit": "128M",
                "upload_max_filesize": "128M",
                "post_max_size": "128M"
            }
        }
    ],
    "export": {}
}

You can omit the php key in the preset if you do not wish for the preset to switch to a given PHP version.

Warning
You must restart PHP Monitor for these changes to be detected.

Info
Homebrew services aren’t displayed if you are using Valet in Standalone Mode.

You must set these services up in a JSON file, located in ~/.config/phpmon/config.json.

You can specify custom services in the configuration file for Homebrew services that run as your own user (not root).

Info
If your service must run as root, it cannot currently be added to PHP Monitor.

You can find out which services are available by running brew services list.

Here’s an example where we add the mailhog and mysql services to PHP Monitor:

{
    "scan_apps": [],
    "services": ["mailhog", "mysql"],
    "presets": [],
    "export": {}
}

Warning
You must restart PHP Monitor for these changes to be detected.

You must configure these custom environment variables up in a JSON file, located in ~/.config/phpmon/config.json.

PHP Monitor uses a default Shell environment, with no custom environment variables. You need to set custom environment variables manually. These are then used for e.g. Composer.

Here’s an example of a working COMPOSER_HOME environment variable which is respected:

{
    "scan_apps": [],
    "services": [],
    "presets": [],
    "export": {
        "COMPOSER_HOME": "/absolute/path/to/composer/folder"
    }
}

Warning
You must restart PHP Monitor for these changes to be detected.

When you select and right-click on a domain, you can open these directories with various applications. This can help speed up your workflow. However, for these apps to show up, they must be detected first.

The supported apps are: PhpStorm, Visual Studio Code, Sublime Text, Sublime Merge, iTerm.

All of these apps should just be detected correctly, no matter their location on your system. If you can open it using open -a "appname", the app should be detected and work. If you have renamed the app, there might be an issue getting it detected.

To see which files are checked to determine availability, see this file.

You can add your own apps by creating and editing a ~/.config/phpmon/config.json file, and make sure the scan_apps key is set:

{
    "scan_apps": ["Xcode", "Kraken"]
}

You can put as many apps as you’d like in the scan_apps array, and PHP Monitor will check for the existence of these apps. You do not need to set the full path, just the name of the app should work. Not all apps support opening a folder, though, so your success might vary.

Warning
You must restart PHP Monitor for these changes to be detected.

PHP Monitor supports third party app integrations by default, and this feature is enabled in Preferences unless you disable it.

You can grab the official Alfred workflow or Raycast extension.

If you’d like to integrate something yourself, all you need to to is use the phpmon:// protocol and ensure that third party app integrations are enabled in Preferences (in PHP Monitor).

Using app callbacks, macOS and PHP Monitor allow for the following to be called:

• phpmon://list
• phpmon://services/stop
• phpmon://services/restart/all
• phpmon://services/restart/nginx
• phpmon://services/restart/php
• phpmon://services/restart/dnsmasq
• phpmon://locate/config
• phpmon://locate/composer
• phpmon://locate/valet
• phpmon://phpinfo
• phpmon://switch/php/{version}

The composer.json file in the root of the folder (if it exists) is scanned and interpreted.

If the version is set in platform, it takes precendence.
If the version is not set in platform but it is in require (most common) then that version is used.

You’ll see a checkmark next to the version number if the currently enabled PHP version is compatible with the version required to run the site.

This is determined by evaluating the PHP requirement constraint (e.g. ^8.0, ~8.0 or a specific version: 8.0).

PHP Monitor currently checks your composer.json file to try to figure out what project you are running.

This approach is a lot faster than asking for a driver when you have many sites linked, but is slightly less reliable since the framework or type of project inferred via composer.json might not be 100% accurate.

You can always still ask Valet using the command line, should it be necessary. In my experience fetching the drivers slowed down the app unnecessarily.

You can now use First Aid & Services > Restore Homebrew Permissions to (temporarily) resolve this issue and allow for a clean and painless brew upgrade or brew cleanup process.

If you would like to know more, consult this issue for more information about why this is needed.

Please get in touch and open an issue. PHP Monitor shouldn’t crash… (unless you are actually removing PHP while the app is running, that’s considered normal behaviour!)

If you would like to report a crash, please include the associated log files so I can find out what exactly went wrong.

To find the logs, take a look in ~/Library/Logs/DiagnosticReports (in Finder) and see if there’s any (log) files that start with “PHP Monitor”.

Additionally, you can help me figure out even more information by sending me your verbose log for your latest session of PHP Monitor. Logging is disabled by default.

You can start extra verbose logging by running: touch ~/.config/phpmon/verbose and restarting PHP Monitor. You can find the latest log in: ~/.config/phpmon/last_session.log. Please attach it to the relevant bug report.