DEV Community

Cover image for PHP CLI SAPI
Nima jahan bakhshian
Nima jahan bakhshian

Posted on

PHP CLI SAPI

#php #programming #webdev #cli

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);
Enter fullscreen mode Exit fullscreen mode

Syntax Check (Lint)

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

# Example
php -l script.php
Enter fullscreen mode Exit fullscreen mode

Built-in Development Server

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

# Example
php -S localhost:8000
Enter fullscreen mode Exit fullscreen mode

Execute a PHP File

php -f <file> # executes a php file

# Example
php -f migrate.php
Enter fullscreen mode Exit fullscreen mode

Run PHP Code Directly

php -r <code> # runs php code without creating a file

# Example
php -r 'echo bin2hex(random_bytes(16));'
Enter fullscreen mode Exit fullscreen mode

Show PHP Version

php -v # displays the current php version

# Example
php -v
Enter fullscreen mode Exit fullscreen mode

Show Full PHP Information

php -i # displays detailed php configuration

# Example
php -i | grep "Loaded Configuration File"
Enter fullscreen mode Exit fullscreen mode

Show Loaded Modules

php -m # lists all compiled and loaded php modules

# Example
php -m | grep -i redis
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Show Loaded INI Files

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

# Example
php --ini
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Strip Comments and Whitespace

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

# Example
php -w foo.php
Enter fullscreen mode Exit fullscreen mode

Show Help

php -h # lists all available command-line options

# Example
php -h
Enter fullscreen mode Exit fullscreen mode

“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

Top comments (1)

Collapse
 
suppdevbot profile image
DEV SUPPORTS • 
You need to verify your account.
Enter fullscreen mode Exit fullscreen mode

tr.ee/dev-to