Introduction

PHP is a general-purpose scripting language mainly known for web development.
However, PHP code does not run on its own. The Zend Engine compiles and
executes code, yet it still needs a host layer that feeds it the script, collects the output, and describes the environment. That layer is called a SAPI (Server Application Programming Interface).

PHP can run in different environments, and each one has its own SAPI:

  • cli -> Command line
  • fpm-fcgi -> PHP-FPM (FastCGI Process Manager)
  • cgi-fcgi -> CGI / FastCGI
  • apache2handler -> Apache module
  • embed -> PHP embedded in another C program
  • phpdbg -> The interactive debugger
  • cli-server -> PHP's built-in development server

This post focuses on the CLI SAPI, which lets you runs PHP scripts directly from the terminal without a web server.
The PHP command line interface (CLI) is a powerful tool for developers, and mastering it can significantly enhance your productivity.

What Makes The Cli Sapi Different

First, there’s no web server, so there’s no HTTP request.

Arguments arrive in $argv (the script name is at index 0) and $argc. STDIN, STDOUT and STDERR are already defined as stream constants.

A few INI defaults are overridden because the usual web settings don’t make sense in a terminal. CLI also looks for php-cli.ini before php.ini, which is why CLI and FPM often end up with different configurations.

The working directory is not changed to the script's directory. Relative paths resolve against where you launched the process, so use __DIR__ for paths relative to the script.

Exit codes also matter because shells, cron and CI act on them. exit(n) returns n to the shell, exit("message") prints the message and returns 0, and an uncaught fatal error returns 255.

How It Works

When you invoke PHP from the command line, the CLI SAPI starts the Zend Engine, loads configuration from php.ini or command-line overrides, processes the arguments, and runs the given script or code.

Usage

The CLI SAPI is useful for:

  • Run scripts without a web server
  • Test code snippets quickly
  • Automate routine tasks
    • Database migrations and data imports
    • Report generation and log processing
    • Cleanup and maintenance jobs
  • Debug applications (with phpdbg or Xdebug)
  • Administer servers (deployment and maintenance scripts)
  • Use an interactive shell (REPL)
  • Manage dependencies (e.g., Composer)
  • Run framework commands and a development server
  • Inspect and override INI settings

Common Commands From The Terminal

Interactive Shell

php -a # starts an interactive php shell (REPL) # Example php -a php > echo password_hash("pass", PASSWORD_DEFAULT);

Syntax Check (Lint)

php -l <file> # checks a php file for syntax errors without executing it # Example php -l script.php

Built-in Development Server

php -S <address>:<port> # starts php’s built-in web server # Example php -S localhost:8000

Execute a PHP File

php -f <file> # executes a php file # Example php -f migrate.php

Run PHP Code Directly

php -r <code> # runs php code without creating a file # Example php -r 'echo bin2hex(random_bytes(16));'

Show PHP Version

php -v # displays the current php version # Example php -v

Show Full PHP Information

php -i # displays detailed php configuration # Example php -i | grep "Loaded Configuration File"

Show Loaded Modules

php -m # lists all compiled and loaded php modules # Example php -m | grep -i redis

Define / Override INI Setting

php -d setting=value # temporarily sets or overrides a php configuration value # Example php -d memory_limit=1G -d max_execution_time=0 import-data.php

Set Document Root for Built-in server

php -S <address>:<port> -t <docroot> # starts the built-in server with a specific document root # Example php -S 0.0.0.0:8000 -t public

Show Loaded INI Files

php --ini # shows which php.ini and scanned .ini files are loaded # Example php --ini

Reflection Information

php --ri <extension> # shows the configuration of one extension php --rf <function> # shows reflection info for a function php --rc <class> # shows reflection info for a class php --re <extension> # shows everything an extension provides # Examples php --ri pdo_mysql php --rf array_map php --rc DateTime

Use a Router Script with the Built-in Server

php -S <address>:<port> <router> # sends every request through a router script # Example php -S localhost:8000 -t public public/index.php

Strip Comments and Whitespace

php -w <file> # prints the source with comments and whitespace removed # Example php -w foo.php

Show Help

php -h # lists all available command-line options # Example php -h

“I’m not a real programmer. I throw together things until it works then I move on. The real programmers will say Yeah it works but you’re leaking memory everywhere. Perhaps we should fix that. I’ll just restart Apache every 10 requests.”

— Rasmus Lerdorf