PHP CLI

PHP CLI is the command-line version of PHP. It is used for scripts, Composer, framework console commands, migrations, test runners, cron jobs, queue workers, imports, exports, and maintenance tools.

CLI code has different inputs and outputs from web PHP. Instead of $_GET, forms, cookies, and HTTP responses, CLI scripts deal with arguments, options, standard input, standard output, standard error, and exit codes.

Running PHP From The Terminal

Common CLI commands:

php -v
php -m
php --ini
php -l script.php
php script.php
php -r "echo PHP_VERSION . PHP_EOL;"

php -l is a syntax check. php -r runs a small piece of PHP without creating a file. php script.php runs a script file.

Inside CLI PHP, PHP_SAPI is normally cli.

<?php

declare(strict_types=1);

echo 'SAPI: ' . PHP_SAPI . PHP_EOL;

// Prints:
// SAPI: cli

Positional Arguments With $argv

CLI arguments are available in $argv. The first item is the script name.

<?php

declare(strict_types=1);

$name = $argv[1] ?? null;

if ($name === null || trim($name) === '') {
    fwrite(STDERR, "Usage: php greet.php <name>\n");
    exit(1);
}

echo 'Hello ' . trim($name) . PHP_EOL;

// Example:
// php greet.php Ada
//
// Prints:
// Hello Ada

This is the simplest way to accept input when a script has one or two required values.

Named Options With getopt()

Named options are clearer when a command has optional settings.

<?php

declare(strict_types=1);

$options = getopt('', ['file:', 'dry-run']);
$file = $options['file'] ?? null;
$dryRun = array_key_exists('dry-run', $options);

if (!is_string($file) || $file === '') {
    fwrite(STDERR, "Usage: php import.php --file=orders.csv [--dry-run]\n");
    exit(1);
}

echo 'File: ' . $file . PHP_EOL;
echo 'Mode: ' . ($dryRun ? 'dry run' : 'write changes') . PHP_EOL;

// Example:
// php import.php --file=orders.csv --dry-run
//
// Prints:
// File: orders.csv
// Mode: dry run

The colon in file: means the option requires a value. dry-run has no colon because it is a boolean flag.

STDOUT, STDERR, And Exit Codes

Write normal output to STDOUT. Write errors, usage messages, and diagnostics to STDERR.

Exit codes tell the shell whether the command succeeded:

• 0 means success
• non-zero means failure

<?php

declare(strict_types=1);

$path = $argv[1] ?? null;

if (!is_string($path) || !is_file($path)) {
    fwrite(STDERR, "File does not exist.\n");
    exit(1);
}

echo filesize($path) . PHP_EOL;
exit(0);

Exit codes matter in CI, cron, deploy scripts, and shell pipelines. A command that prints an error but exits with 0 can make automation think everything succeeded.

Reading From STDIN

STDIN lets a command receive piped input.

<?php

declare(strict_types=1);

$input = stream_get_contents(STDIN);
$lines = array_filter(explode("\n", trim($input)));

echo 'Lines: ' . count($lines) . PHP_EOL;

// Example:
// printf "one\ntwo\n" | php count-lines.php
//
// Prints:
// Lines: 2

This is useful for small tools that work with output from other commands.

Environment Variables In CLI

CLI scripts often depend on environment variables. Cron and process managers may provide a different environment from your interactive terminal.

<?php

declare(strict_types=1);

$appEnvironment = getenv('APP_ENV') ?: 'production';

echo 'Environment: ' . $appEnvironment . PHP_EOL;

// Example:
// APP_ENV=local php env.php
//
// Prints:
// Environment: local

If a command works manually but fails in cron, check PATH, working directory, PHP binary path, and environment variables.

Shebang Scripts

On Unix-like systems, a PHP script can be directly executable with a shebang line.

#!/usr/bin/env php
<?php

declare(strict_types=1);

echo 'Hello from an executable PHP script' . PHP_EOL;

Then:

chmod +x hello
./hello

This is common for project tools in bin/.

Use $argc And $argv As Untrusted Input

$argc contains the argument count and $argv contains argument strings when the variables are available. $argv[0] identifies the invoked script or command name; later elements come from the shell after its own quoting and expansion.

Do not assume a numeric-looking argument is a valid integer, a path exists, or a filename is inside an allowed directory. Validate before performing work.

<?php

declare(strict_types=1);

$rawQuantity = $argv[1] ?? null;
$quantity = filter_var($rawQuantity, FILTER_VALIDATE_INT);

if ($quantity === false || $quantity < 1) {
    fwrite(STDERR, "Quantity must be a positive integer.\n");
    exit(2);
}

echo "Quantity: ", $quantity, PHP_EOL;

Use distinct non-zero statuses only when callers benefit from distinguishing usage, validation, and operational failures. Document them; unexplained status numbers are difficult to maintain.

Design An Option Contract

An option can require a value, accept an optional value, or act as a flag. With getopt(), a colon after a long option name requires a value and two colons make it optional. Optional values can be ambiguous, so prefer required values or boolean flags when possible.

Support --help without requiring the command's normal inputs. Usage text should show command shape, required values, optional flags, defaults, and at least one example.

Treat unknown options deliberately. For larger command surfaces, use a maintained console component that provides strict parsing, generated help, validation, and tests rather than building a fragile parser around getopt().

The shell convention -- marks the end of options in many command-line tools, allowing later values beginning with - to be treated as arguments. Verify how the chosen parser handles this boundary.

Remember Shell Quoting Happens First

A user can pass one argument containing spaces by quoting it:

php greet.php "Ada Lovelace"

PHP receives Ada Lovelace as one $argv element. Without quotes, the shell sends two elements. Windows PowerShell, Command Prompt, and POSIX shells have different quoting rules, especially for php -r commands.

Keep reusable code in files rather than publishing complex one-liners whose quoting works in only one shell. Never construct a shell command by concatenating untrusted CLI input.

Inspect CLI Configuration And Overrides

CLI PHP can display help and configuration information:

php --help
php --ini
php -i

Apply an INI directive to one invocation with -d:

php -d memory_limit=256M report.php

This is useful for a controlled job with a documented resource need. It does not edit php.ini or configure another SAPI. Do not use an unlimited memory or execution setting as a substitute for investigating an unbounded import.

The CLI SAPI commonly has different defaults from web SAPIs, including execution-time behaviour. Long-running commands still need explicit timeouts for network operations, bounded batches, memory monitoring, cancellation, and resumability.

Distinguish Interactive Input From A Pipeline

A command reading STDIN can receive a pipe, redirected file, or keyboard input. Decide whether waiting for interactive input is acceptable.

For automation, avoid prompts by default. A cron job cannot answer "Continue?" and can hang until killed. Provide explicit options such as --force or --no-interaction only when their safety semantics are clear.

When available, stream_isatty(STDIN) can help identify a terminal stream. Do not make correctness depend entirely on it; environments and platform support vary. A command should document whether it expects piped data or interaction.

Never read secrets from ordinary command arguments when avoidable. Arguments can appear in shell history or process listings. Use a protected file descriptor, secret store, environment mechanism with understood exposure, or an interactive no-echo prompt supplied by a suitable library.

Produce Stable Machine-Readable Output

Human-readable tables are useful in terminals but awkward for automation. A mature command can offer a format such as JSON while keeping diagnostics on stderr.

<?php

declare(strict_types=1);

$result = [
    'processed' => 12,
    'failed' => 0,
];

echo json_encode($result, JSON_THROW_ON_ERROR), PHP_EOL;

Do not mix progress messages into stdout when stdout is documented as JSON or CSV. Send progress to stderr or disable it in non-interactive mode. Keep field names and exit semantics stable because scripts may depend on them.

Resolve Paths Predictably

A CLI script's current working directory comes from the caller. Relative inputs such as data/orders.csv are resolved from that directory, not automatically from the script's location.

Use getcwd() when the command contract is working-directory-relative. Use __DIR__ for files packaged beside the script. Resolve and validate user-supplied paths before reading or writing them.

Avoid changing the working directory globally unless the command owns that decision and documents it. Hidden chdir() calls can make error messages and relative output paths surprising.

Make Maintenance Commands Safe To Retry

Imports, migrations, and repair commands can stop halfway because of invalid data, network failure, deployment interruption, or a terminated process. Design for restart:

• support --dry-run when a meaningful preview is possible;
• process bounded batches;
• record stable checkpoints;
• use transactions for atomic units;
• make repeated operations idempotent where possible;
• report counts and failed identifiers;
• avoid duplicate email, payments, or external side effects;
• provide a clear resume or rollback procedure.

A dry run must not secretly perform writes. Test it against each side effect, including database changes, files, queues, email, and external APIs.

Handle Failures At The Command Boundary

Let application services throw meaningful exceptions, then convert them to concise CLI diagnostics and non-zero statuses at the command entry point. Do not print full stack traces to ordinary users by default, but preserve enough logged detail for diagnosis.

Use try/finally for resources that must be released, and rely on database transactions or atomic file replacement where partial output would be dangerous. Temporary files should have unique names and be cleaned without deleting unrelated files.

Signals and graceful shutdown matter for long-running workers. Framework console and process components can help, but the command still needs a defined policy for finishing the current unit, releasing locks, and reporting interruption.

Test CLI Behaviour At Two Levels

Keep business logic in functions or services that can be tested without spawning a process. Then add command-level tests for:

• parsing arguments and options;
• help and usage output;
• stdout and stderr separation;
• exit statuses;
• files or records changed;
• dry-run guarantees;
• invalid input and operational failures.

A command that only works when manually observed is difficult to trust in CI, cron, or deployment automation.

Common CLI Failure Patterns

What Makes A Good CLI Script

A good CLI script:

• validates required arguments and options
• prints a useful usage message
• writes errors to STDERR
• exits non-zero on failure
• avoids hard-coded absolute paths where possible
• handles missing files and empty input deliberately
• is safe to run more than once when used for maintenance

For larger applications, framework console components usually provide better argument parsing, help text, commands, dependency injection, and test support. The raw PHP CLI basics still matter because those frameworks build on the same runtime concepts.

What You Should Be Able To Do

After this lesson, you should be able to run PHP from the terminal, read positional arguments, parse named options, read STDIN, write errors to STDERR, and return meaningful exit codes.

For junior PHP work, this matters because CLI tasks are part of real projects: imports, migrations, scheduled jobs, one-off fixes, test commands, and deployment checks all rely on command-line PHP.