Skip to content

About

Run PHP and Composer on macOS without installing PHP: a ready-to-use Docker image with common extensions, used through simple php and composer shell commands. A clean alternative to Homebrew PHP.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

🐘 PHP on your Mac β€” without installing PHP

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

Why use this instead of brew install php?

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.

What's inside

  • PHP 8.5 CLI, based on the official php:8.5-cli-alpine image (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, redis
    Web & networking curl, openssl, sockets, event
    Text & internationalization mbstring, intl, iconv, ctype
    XML & data dom, simplexml, xml, xmlreader, xmlwriter, xsl, json, soap
    Files & compression zip, zlib, fileinfo
    Images gd, exif
    Performance & 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.


Requirements

You only need a Docker runtime installed and running. Any of these works:

To check that Docker is ready:

docker info

If it prints information about your Docker setup and no error, you're ready.


Installation (about 3 minutes)

1. Get the files

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-cli

2. Build the image

chmod +x build.sh
./build.sh

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

3. Add the php and composer commands to your shell

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_profile instead.

4. Reload your shell

source ~/.zshrc

Or just open a new terminal window.

5. Try it

php -v
composer --version
php -m        # list every loaded extension

πŸŽ‰ That's it. php and composer now work in any folder.


Everyday usage

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/phpunit

Piping works too:

echo '<?php echo 2 + 2, PHP_EOL;' | php

How it works

Each time you type php or composer, the shell function:

  1. starts a temporary container from the php85-cli:custom image,
  2. shares your current folder with it (as /app),
  3. runs the command inside it, and
  4. 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.


Good to know (limitations and tips)

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:8000

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


Customizing

All settings are at the top of build.sh.

Add or remove extensions

Edit the PHP_EXTENSIONS list and rebuild:

PHP_EXTENSIONS="
  ...
  gd
  imagick
  xdebug
"
./build.sh

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

Use a different PHP version

Change BASE_IMAGE in build.sh, for example:

BASE_IMAGE="php:8.4-cli-alpine"

Use a different image name

Pass the name as the first argument:

./build.sh php84-cli:custom

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


Updating

To get the latest PHP 8.5 patch release, Composer and extensions, rebuild:

./build.sh

The script always pulls the newest base image (--pull).


Uninstalling

  1. Delete the two functions (between the docker-php-cli comments) from ~/.zshrc, then open a new terminal.

  2. Remove the image:

    docker rmi php85-cli:custom

Nothing else was installed on your Mac.


Troubleshooting

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.

Project files

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

About

Run PHP and Composer on macOS without installing PHP: a ready-to-use Docker image with common extensions, used through simple php and composer shell commands. A clean alternative to Homebrew PHP.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages