phpctl 🐳 A Docker-based development environment for PHP 🐘 Heavily inspired by opencodeco/hfctl.

Introduction

Frictionless PHP Development! Seamlessly run and switch between different versions of PHP, with different installed extensions, thanks to the power of containers. Take the advantage of goodie commands like phpctl create to start a new project, phpctl repl to start a REPL, phpctl init to initialize a new configuration file and a lot more.

Getting started

Tip

Pro-tip: use it with stack to spin up infrastructure components like MySQL, Redis, RabbitMQ etc.

Requirements

• Bash
• Git
• Docker

Install

You can install with default installer script for a system-wide (at /usr/local/bin), run:

wget -q https://phpctl.dev/phpctl-installer.sh && \
bash phpctl-installer.sh && rm phpctl-installer.sh

Tip

You can also pass an argument to install at a custom location (e.g. ~/bin), but you have to make sure that folder is in your $PATH variable.

bash phpctl-installer.sh ~/bin

Homebrew

brew install opencodeco/phpctl/phpctl

Or add the oppencodeco tap with brew tap opencodeco/phpctl and then brew install phpctl

Update

You can re-run the installer or use the self-update command:

phpctl self-update

For those using Homebrew brew upgrade opencodeco/phpctl/phpctl or when run brew update

Usage

Then you can use phpctl or pctl with a subcommand:

phpctl <command> [arguments]

For example

phpctl php -m # To show built-in modules

Or

phpctl sh echo 'Hello, World!' # To run arbitrary sh commands inside the container

Command list

Developing

Command	Description
php	Runs PHP commands (phpctl php -v or phpctl php -m).
composer	Runs Composer commands (phpctl composer install or pctl composer validate).
server [port] [directory]	Runs PHP's built-in web-server (default port is 80 and default directory is current .).
sh [commands]	Starts an interactive Shell session or runs sh commands.
repl	Starts a PHP REPL session (powered by PsySH).
bundle	Bundles a project into an image and ships it as a single binary file.

Tools

Command	Description
phpunit	PHPUnit is a programmer-oriented testing framework for PHP.
php-cs-fixer	PHP Coding Standards Fixer (PHP CS Fixer) fixes your code to follow standards.
phpstan	PHPStan finds bugs in your code without writing tests. It's open-source and free.
infection	Infection is a Mutation Testing Framework.
pest	Pest is a testing framework with a focus on simplicity.
pint	Pint is an opinionated PHP code style fixer for minimalists.
box	Box: fast, zero config application bundler with PHARs.
exakat	Exakat is a real time customizable static analyzer engine that analyse and fix code.
frankenphp	FrankenPHP: the Modern PHP App Server, written in Go.
rector	Rector is a tool that you can run on any project to get an instant upgrade or automated refactoring.
watchr	watchr: command-line utility to explore and validate domain names and certificates.

Scaffolders

Command	Description
create [framework] [dir]	Creates a new project using the given framework (or package).
init [skeleton]	Initializes a skeleton configuration.

Skeletons

• phpunit
• php-cs-fixer
• phpstan
• infection
• box

Helpers

Command	Description
help or man	Displays a help message.
self-update	Updates phpctl iself.
doctor	Inspects the current PHP_VERSION and PHPCTL_IMAGE.
build	Builds the current Dockerfile (useful for custom images).
images	Shows local phpctl images.

The .phpctlrc file

You can also add a .phpctlrc file at project's root directory with some overrides like:

Environment variables

Variable	Description
PHP_VERSION	Values can be 82 and 83
PHPCTL_IMAGE	Use to name your own custom image

For example:

PHP_VERSION=83

Docker behaviour

Run options

You can also provide any additional Docker run arguments using the args variable.

For example, suppose you want to bind the 9501 port from the running phpctl container to your host, you can add the following to your .phpctlrc file:

args=(-p 9501:9501)

Build options

You can also provide build options to the build command using the build variable:

build=(--build-arg APP_ENV=dev --label phprocks)

Podman

You can use Podman instead of Docker by setting the PHPCTL_RUNTIME variable to podman in your environment variables or at .phpctlrc file.

PHPCTL_RUNTIME=podman phpctl php -v

Host user

By default, phpctl creates an user considering host user. You can change from root to host user through PHPCTL_USER variable.

PHPCTL_USER=your_user phpctl sh whoami

The phpctl.ini file

You can also add a phpctl.ini file at project's root directory to set any php.ini directive.

memory_limit = 1337M

$ phpctl php -i | grep memory_limit
memory_limit => 1337M => 1337M

Modules

For the default Docker image we have the following modules installed (click to expand).

[PHP Modules]
Core
ctype
curl
date
dom
fileinfo
filter
hash
iconv
igbinary
json
libxml
mbstring
mongodb
msgpack
mysqlnd
openssl
pcntl
pcov
pcre
PDO
pdo_mysql
Phar
posix
random
rdkafka
readline
redis
Reflection
session
SimpleXML
sockets
sodium
SPL
sqlite3
standard
swoole
tokenizer
xml
xmlreader
xmlwriter
zip
zlib

You can always use your custom image with the PHPCTL_IMAGE variable, but feel free to ask for more essential extensions in the issues.

Why it exists?

Tip

After some years struggling with different PHP distributions into different operating systems, dealing with different PHP versions and sets of extensions, I came out with phpctl to use the power of containers to seamlessly run PHP 🐘 for developement environments.

Contributing

Click here to read the contributing guidelines.