Run php and composer in your Mac terminal exactly as if they were installed,
except they live inside a small Docker image. No Homebrew, no version
conflicts, no leftover config files scattered across your system.
$ php -v
PHP 8.5.x (cli) ...
$ composer install
Installing dependencies from lock file ...| Homebrew PHP | This project | |
|---|---|---|
| Installs files on your Mac | Many (PHP, libraries, config, extensions) | None, only one Docker image |
Extensions such as redis, intl, pgsql |
Install through pecl, which sometimes breaks after upgrades |
Already built in |
| Upgrading PHP | Can break extensions and linked libraries | Rebuild the image in about a minute |
| Same setup on every machine | Hard | One script gives the same result everywhere |
| Removing it | Uninstall each piece and clean up leftovers | Delete one image and two shell functions |
It suits you if you:
- write PHP or Laravel code and want a clean Mac,
- need PHP now and then for a script or a Composer package,
- have had Homebrew PHP break after a
brew upgrade, - want your whole team to use the same PHP and extensions.
-
PHP 8.5 CLI, based on the official
php:8.5-cli-alpineimage (small and fast) -
Composer 2
-
git, unzip and bash, which Composer needs to fetch packages
-
Common extensions, already installed:
Category Extensions Databases pdo_mysql,mysqli,pdo_pgsql,pgsql,redisWeb & networking curl,openssl,sockets,eventText & internationalization mbstring,intl,iconv,ctypeXML & data dom,simplexml,xml,xmlreader,xmlwriter,xsl,json,soapFiles & compression zip,zlib,fileinfoImages gd,exifPerformance & testing apcu(in-memory cache),pcov(code coverage for PHPUnit/Pest)Math & misc bcmath,gmp,pcntl,tokenizer,filter,hash,pcre
It works on both Apple Silicon (M1/M2/M3/M4β¦) and Intel Macs.
You only need a Docker runtime installed and running. Any of these works:
- Docker Desktop
- OrbStack, a fast and lightweight option
- Colima
To check that Docker is ready:
docker infoIf it prints information about your Docker setup and no error, you're ready.
Clone or download this repository and open a terminal in its folder:
git clone https://github.com/aln-1/docker-php-cli.git
cd docker-php-clichmod +x build.sh
./build.shThe script builds the image and then checks it: it prints the PHP version, the Composer version, the git, unzip and bash versions, and confirms that every listed extension is present. It should end with:
All configured extensions are present.
The first build takes a few minutes because some extensions are compiled. Later builds are faster.
macOS uses zsh by default. Open your shell configuration file:
open -e ~/.zshrc(If the file doesn't exist yet, run touch ~/.zshrc first.)
Paste these two functions at the end of the file and save it:
# --- PHP & Composer via Docker (docker-php-cli) ---
php() {
local tty_flag=""
if [ -t 0 ] && [ -t 1 ]; then
tty_flag="-it"
fi
docker run --rm $tty_flag \
-v "$(pwd)":/app \
-w /app \
php85-cli:custom php "$@"
}
composer() {
local tty_flag=""
if [ -t 0 ] && [ -t 1 ]; then
tty_flag="-it"
fi
docker run --rm $tty_flag \
-v "$(pwd)":/app \
-v "${COMPOSER_HOME:-$HOME/.composer}:/tmp" \
-w /app \
php85-cli:custom composer "$@"
}
# --- end docker-php-cli ---Still using bash? Put the same functions in
~/.bash_profileinstead.
source ~/.zshrcOr just open a new terminal window.
php -v
composer --version
php -m # list every loaded extensionπ That's it. php and composer now work in any folder.
Use them exactly as you would a normal PHP installation:
# Run a script
php hello.php
# Quick one-liner
php -r 'echo "Hello from Docker!\n";'
# Interactive shell
php -a
# Start a new Laravel project
composer create-project laravel/laravel my-app
cd my-app
php artisan --version
# Install a project's dependencies
composer install
composer require guzzlehttp/guzzle
# Run tests
php vendor/bin/phpunitPiping works too:
echo '<?php echo 2 + 2, PHP_EOL;' | phpEach time you type php or composer, the shell function:
- starts a temporary container from the
php85-cli:customimage, - shares your current folder with it (as
/app), - runs the command inside it, and
- removes the container when the command finishes (
--rm).
Your files stay on your Mac, and the container only exists while the command runs.
composer also shares ~/.composer (or $COMPOSER_HOME, if you set it) with
the container. That keeps Composer's download cache, global packages and auth
settings between runs, so later installs are much faster.
The function checks whether you're in an interactive terminal: if so, you get
colors and prompts (-it), and if not (in a pipe or script), it still works
cleanly.
Only the current folder is visible.
The container sees the folder you are in and everything below it. Paths outside
it, such as php ../other/script.php or php /Users/me/Desktop/x.php, won't work.
cd into the right folder first, or run from a parent folder that contains
everything you need.
Connecting to a database running on your Mac.
Inside the container, localhost means the container itself, not your Mac.
Use host.docker.internal as the database host instead, for example
DB_HOST=host.docker.internal in a Laravel .env file.
The built-in web server (php -S, php artisan serve).
The functions don't publish any network ports, so a server started this way
isn't reachable from your browser. For web development, use a dedicated setup
such as Laravel Sail or Docker Compose, or run a one-off command with a
published port:
docker run --rm -it -p 8000:8000 -v "$(pwd)":/app -w /app \
php85-cli:custom php -S 0.0.0.0:8000Then open http://localhost:8000.
Startup time.
Each command starts a fresh container, which adds a fraction of a second. You
won't notice it for most work. It is more noticeable in tight loops that call
php thousands of times.
Docker must be running.
If you see Cannot connect to the Docker daemon, start Docker Desktop, OrbStack
or Colima first.
All settings are at the top of build.sh.
Edit the PHP_EXTENSIONS list and rebuild:
PHP_EXTENSIONS="
...
gd
imagick
xdebug
"./build.shExtensions are installed with docker-php-extension-installer, which lists all supported extensions. The build fails with a clear message if one of the extensions is missing.
Change BASE_IMAGE in build.sh, for example:
BASE_IMAGE="php:8.4-cli-alpine"Pass the name as the first argument:
./build.sh php84-cli:customIf you rename the image, also change php85-cli:custom in both shell functions
to the new name.
π‘ Tip: you can keep several PHP versions side by side by building them under different names and adding extra functions such as
php84()that use the matching image.
To get the latest PHP 8.5 patch release, Composer and extensions, rebuild:
./build.shThe script always pulls the newest base image (--pull).
-
Delete the two functions (between the
docker-php-clicomments) from~/.zshrc, then open a new terminal. -
Remove the image:
docker rmi php85-cli:custom
Nothing else was installed on your Mac.
| Problem | Fix |
|---|---|
command not found: php |
Run source ~/.zshrc or open a new terminal. Check that the functions are in ~/.zshrc. |
Unable to find image 'php85-cli:custom' |
The image hasn't been built yet. Run ./build.sh. |
Cannot connect to the Docker daemon |
Start Docker Desktop, OrbStack or Colima. |
Could not open input file |
The file is outside the current folder. cd closer to it (see Good to know). |
A php from Homebrew still runs |
Check with type php. It should say php is a shell function. Remove the other PHP with brew uninstall php, or make sure the functions are loaded last in ~/.zshrc. |
MISSING extension: β¦ during build |
That extension couldn't be installed for this PHP version. Remove it from PHP_EXTENSIONS or choose another PHP version. |
| File | Purpose |
|---|---|
build.sh |
Builds the image and checks that PHP, Composer, the tools and every extension work |
Dockerfile |
Image recipe: base PHP image, tools, extensions and Composer |
README.md |
This guide |