How to Install/Upgrade PHP 8.3 on MacOS with Homebrew

With a handful of new features such as typed class constants, granular Exceptions in the DateTime extension, the new json_validate function, functionality changes and improvements, and deprecations, PHP 8.3 is 2023’s major update to PHP. This article explains how to install or upgrade to PHP 8.3 on macOS using Homebrew.

Shivam Mathur maintains two Brew taps, shivammathur/php and shivammathur/extensions that contain precompiled PHP 8.3 packages (bottles) which are kept up to date, making it convenient to install PHP 8.3 and several PHP core and PECL extensions using Homebrew.

---

Quick-Start

In the macOS terminal, run the following commands to quickly install PHP 8.3 using Homebrew. Homebrew must be installed first.

For detailed steps, see jump to the Detailed Installation/Upgrade guide.

# Add the PHP and PHP Extension taps
brew tap shivammathur/php
brew tap shivammathur/extensions

# Install PHP 8.3
brew install shivammathur/php/[email protected]

# Link PHP 8.3 CLI executable as `php`
brew link --overwrite --force shivammathur/php/[email protected]

# Test installation
php -v

---

Detailed Installation/Upgrade guide to install PHP 8.3 on macOS

1. Prerequisites

Make sure to have Homebrew installed. This was tested on macOS macOS Monterey, Ventura, and Sonoma.

Installing the PHP 8.3 as shown in the rest of the article requires Homebrew and the two Homebrew taps maintained by Shivam Mathur.

2. List and keep note of existing PHP packages

When upgrading an existing PHP version, the following command lists all Brew packages, filters them for PHP-related words, and saves them to a packages.txt file. This file can then come in handy later to install the same set of PHP packages for PHP 8.3.

This step is not necessary when installing PHP on a new system.

brew list --full-name | grep -E "php|shivammathur/extensions" | tee packages.txt

3. Add New Taps to Homebrew

brew tap shivammathur/php
brew tap shivammathur/extensions

4. Install PHP 8.3

brew install shivammathur/php/[email protected]
brew link --force --overwrite shivammathur/php/[email protected]

This install PHP with several core extensions. It is not possible to customize the list of extensions included without recompiling PHP.

5. Additional PHP Extensions

The shivammathur/extensions tap contains several PECL extensions ready to install.

# Install xdebug for PHP 8.3
brew install shivammathur/extensions/[email protected]

See the complete list of available extensions here. For convenience, some of the most popular PECL extensions are listed below:

Extension	Name
Xdebug	shivammathur/extensions/[email protected]
APCu	shivammathur/extensions/[email protected]
IMAP	shivammathur/extensions/[email protected]
PCOV	shivammathur/extensions/[email protected]
Redis	shivammathur/extensions/[email protected]
Swoole	shivammathur/extensions/[email protected]
YAML	shivammathur/extensions/[email protected]

6. Web Server Integrations

If PHP is integrated with a web server, restart/reload the web server to reload the changes with the new PHP FPM version.

• Apache: brew services restart httpd
• Nginx: brew services restart nginx
• Caddy: caddy reload

7. Test PHP 8.3 Installation

Running php -v in the terminal should show something like this:

8. Migrate Configuration

This step only applies when updating to PHP 8.3 from an older PHP version

The configuration files for the PHP 8.3 are located at /opt/homebrew/etc/php/8.3. Existing PHP installations should also be in the /opt/homebrew/etc/php directory.

Do not copy existing PHP INI files to /opt/homebrew/etc/php/8.3. While it may work when upgrading from PHP 8.2 or a recent version, manually copying the INI directives is recommended.

See What’s new and changed in PHP 8.3 to see the deprecated INI directives and the new INI directive added in PHP 8.3.

9. Remove old PHP Versions

This step only applies when updating to PHP 8.3 from an older PHP version

To remove old PHP versions, run brew uninstall with the PHP package name and version.

PHP installed from Brew’s core packages

brew uninstall [email protected]

PHP installed from shivammathur/php tap

brew uninstall shivammathur/php/[email protected]