nicoverbruggen/phpmon

Note If this software has been useful to you, I ask that you please star the repository, that way I know that the software is being used. Also, please consider sponsoring to support the project, as this is something I make in my free time. Thank you! ⭐️

PHP Monitor (or phpmon) is a lightweight macOS utility app that runs on your Mac, helps set up and maintain your local PHP development environment, and displays the active PHP version in your status bar.

If your Mac is not quite ready yet, PHP Monitor can guide you through that setup on first launch. It's also tightly integrated with Laravel Valet, which can be automatically installed for you by the app.

Screenshot: Showing the key functionality of PHP Monitor. You can switch between PHP versions, manage PHP installations, install extensions, manage domains, and much more.

It's super convenient to globally switch between different versions of PHP. This applies the selected version of PHP as the default on your system.

If you prefer, you can also pick a PHP version on a per-site basis (this uses Valet's site isolation feature) which is very helpful.

PHP Monitor also gives you quick access to various useful functionality (like accessing configuration files, restarting services, and more).

You can also add new domains as links, isolate sites, manage various services, and perform First Aid to fix all kinds of common PHP and Homebrew issues.

🖥 System requirements

PHP Monitor is a universal application that runs natively on Apple Silicon and Intel-based Macs.

• A user account that can administer your computer (required for setup + for some functionality, e.g. certificate generation)
• macOS 13.5 or later

If your machine is still missing Homebrew, PHP, Composer, or even Apple's Command Line Tools, PHP Monitor's onboarding wizard can guide you through the initial setup on first launch.

For more information, please see SECURITY.md to find out which version of the app is currently supported.

🚀 How to install

On first launch, PHP Monitor can guide you through installing Apple's Command Line Tools, Homebrew, configuring your PATH, installing PHP and Composer, and optionally setting up Laravel Valet as well.

Manual installation (recommended, first time only)

You can download the latest release, unzip it and place it in /Applications.

When you launch PHP Monitor for the first time on a fresh machine, the onboarding flow will guide you through whatever is still missing. Some steps still happen in Terminal or via a macOS installer window, but PHP Monitor will tell you exactly what to do.

Installation via Homebrew

Alternatively, if you prefer to install the app via Homebrew, you can also run the following:

brew tap nicoverbruggen/homebrew-cask
brew install --cask phpmon

(You may want to disable the built-in update check if you install PHP Monitor this way.)

⬆️ How to update

The recommended method of updating the app to the latest version is to use the built-in updater.

If you have a very slow internet connection, the updater may report that the download has timed out. In that case, you may wish to manually update by downloading the latest release and placing the app in /Applications.

(You may also use Homebrew to update PHP Monitor, but this will require you to approve the app every time an update is installed. If you use the built-in updater, this won't be necessary.)

✅ Supported versions of Valet

Currently, PHP Monitor is compatible with Laravel Valet v2 up to v4.

Each of these versions of Valet support slightly different PHP versions, which is why legacy versions remain supported. Please note that some features are not available in older versions of Valet, like site isolation.

⚡️ Launchers (Alfred, Raycast)

If you would like to integrate with your launcher of choice, you can also download an Alfred workflow or Raycast extension that works with PHP Monitor.

Keep in mind that third-party integrations are turned off by default, but you will be prompted to approve third-party integrations the very first time a third-party app attempts to connect with PHP Monitor.

You will only be prompted once to allow or disallow this, but you can always change your mind about this later, in Settings, by (un)checking the box next to "Allow third-party integrations".

(For more information about how this works and the potential security considerations, please consult the FAQ below.)

🔑 Is the app signed & notarized?

Yes, the app is signed and notarized, meaning all you have to do is approve its first launch.

If you also use the onboarding flow to set up your environment, macOS may additionally prompt you to complete an installer or approve administrator access for certain setup steps.

👨‍💻 Why build this?

I wanted to be able to see at a glance which version of PHP was linked, and handle dealing with Laravel Valet in a simple app without having to deal with the terminal every time.

Initially, I had an Alfred workflow for this — but it has now been replaced with this utility, which also does a good job at displaying additional information at a glance, like the current PHP version, memory limits, and more.

🐘 Why not use Laravel Herd?

Disclaimer: The author is not affiliated with Laravel or the Laravel team, nor Beyond Code, who maintain Laravel Herd. PHP Monitor is an independent project.

If you don't need to customize your local PHP setup and just want an easy and ready-to-go environment to start coding, Laravel Herd is a great alternative to PHP Monitor, since it does not rely on Homebrew. The app also offers paid features that may be useful to you or your team.

Herd may not be for everyone, which is why other solutions to run PHP locally exist. PHP Monitor preceded Herd and will remain supported. I highly recommend that you try different tools, and use what you like best.

🤬 The app won't start?!

PHP Monitor performs some integrity checks to ensure a good experience when using the app. On a fresh machine, it will first try to help you with onboarding if key dependencies are missing. After that, you'll get a message telling you that PHP Monitor won't work correctly in a variety of scenarios.

Follow instructions as specified in the alert in order to resolve any issues.

(If the app crashes at launch without showing you any of these messages, you might have a non-standard Homebrew and Valet setup. Those are not supported.)

🙋‍♂️ FAQ & Troubleshooting

If you are having issues, the first thing you should be doing is installing the latest version of PHP Monitor and Laravel Valet. This can resolve a variety of issues. To upgrade Valet, run composer global update. Don't forget to run valet install after upgrading.

If you're still having issues, here's a few common questions & answers, as well as issues and solutions:

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.4.

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 decide later that you do want the full Valet integration after all, PHP Monitor can guide you through installing Valet then too. If the rest of your system is already set up, the wizard will usually skip straight to the Valet step.

If you want to set up your computer for the very first time with PHP Monitor, the easiest way to do this now is to let PHP Monitor guide you.

On first launch, PHP Monitor can guide you through the following:

• Installing Apple's Command Line Tools & Homebrew
• Setting up your PATH so Homebrew, Composer and PHP Monitor's own helpers are available
• Installing the php and composer formulae
• Optionally installing Laravel Valet and configuring it

Depending on your setup, a few of these steps still happen outside of PHP Monitor itself.

For example, macOS may open Apple's installer window for the developer tools, and the Homebrew installation command still needs to be run in Terminal. PHP Monitor will tell you exactly what to do and when to come back.

If you don't need Laravel Valet, you can stop at that step. PHP Monitor will work like this in Standalone Mode.

If your Mac is already mostly prepared and you're only missing Valet, PHP Monitor will usually skip straight to the Valet step the next time you run setup.

If you prefer to do everything manually in Terminal, you still can. Here's the rough order:

1. Install Homebrew first. Installing this will also prompt you to install Apple's Command Line Tools if you haven't installed those yet.
2. Set up your PATH.
3. Install the php and composer formulae.
4. If you want Valet too, install it with Composer and finish the Valet setup.

If you're using zsh, PHP Monitor currently expects the following PATH entries:

export PATH=$HOME/bin:~/.config/phpmon/bin:$PATH
export PATH=$HOME/bin:~/.composer/vendor/bin:$PATH
export PATH=$HOME/bin:/usr/local/bin:$PATH # on an Intel Mac
export PATH=$HOME/bin:/opt/homebrew/bin:$PATH # on an Apple Silicon Mac

If you are not on Apple Silicon, you should remove the last line. If you are on Apple Silicon, you should remove the Intel line instead.

Install the php and composer formulae:

brew install php composer

Make sure PHP is linked correctly:

which php

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

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 8.4, your ~/.composer/composer.json file could look like this (please adjust the version accordingly!):

{
    "require": {
        "laravel/valet": "^4.9",
    },
    "config": {
        "platform": {
            "php": "8.4"
        }
    }
}

A more realistic example is locking to an earlier version of PHP 8.0, like this:

{
    "require": {
        "laravel/valet": "^4.0",
    },
    "config": {
        "platform": {
            "php": "8.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