Command
Reference for the Command module: run a PHP application from the command line. The same index.php that serves web requests can also be run from the command line; arguments are routed to command handlers that modules and sites register, and when no command is given the module prints help listing every command.
This page is a pure reference. It documents every public class and function of the Command module with its full signature, parameters and return type.
Command- the command line entry point: detect command line mode, read arguments and dispatch to a handler.CommandConfig- register the commands an application supports and look them up by name.CommandHelp- print help text for the whole application or a single command.CommandHelpCommand- a command's name, description and nested subcommands.CommandProcess- start a detached background process that outlives the script.CommandRoute- match subcommands and typed arguments against the command line, or print their usage.
Command
The command line entry point. Detects whether PHP was run from the command line, reads the arguments, and dispatches the first argument to a registered command handler or prints the application help.
Arguments
Command::Arguments(): array
The command line arguments, excluding the script name itself.
Returns array The list of argument strings.
do
Command::do(callable $callback): void
Run a callback that is expected to finish the command by calling Command::done; fails if it does not.
| Name | Type | Description |
|---|---|---|
$callback | callable | The command body to run. |
Returns void
done
Command::done(): void
Mark the current command as handled, so the routing stops looking for more to do.
Returns void
HandleCommand
Command::HandleCommand(string $applicationName, string|null $optionalApplicationDescription, string $commandName, array $arguments): void
Look up the named command in the config and run its route with the given arguments, or report that the command is unknown.
| Name | Type | Description |
|---|---|---|
$applicationName | string | The application name, used in help output. |
$optionalApplicationDescription | string|null | An optional description of the application. |
$commandName | string | The command to run. |
$arguments | array | The remaining arguments passed to the command. |
Returns void
IsCommandLine
Command::IsCommandLine(): bool
Whether PHP is running from the command line rather than serving a web request.
Returns bool True when the SAPI is the command line.
Server
Command::Server(string $applicationName, string|null $optionalApplicationDescription = null): void
The command line entry point for a site. When run from the command line, reads the arguments and dispatches the first one to a registered command, or prints the application help when there is none. Does nothing when serving a web request.
| Name | Type | Description |
|---|---|---|
$applicationName | string | The application name, shown in help output. |
$optionalApplicationDescription | string|null | An optional description of the application. |
Returns void
CommandConfig
Holds the commands an application supports. Each command has a name, a description and a route callback; the config registers them and looks them up by name.
Properties
| Property | Type | Description |
|---|---|---|
CommandConfig::$commands | array | The registered commands, keyed by command name. |
Command
CommandConfig::Command(string $name, string $description, callable $routeCallback): void
Register a command with a name, a description and a route callback that defines its subcommands and arguments.
| Name | Type | Description |
|---|---|---|
$name | string | The command name. |
$description | string | A description of the command. |
$routeCallback | callable | The callback that defines the command's routing. |
Returns void
eachCommand
CommandConfig::eachCommand(callable $callback): void
Call the callback once for every registered command, passing its name, description and route callback.
| Name | Type | Description |
|---|---|---|
$callback | callable | Called with the command name, description and route callback. |
Returns void
getCommandOptional
CommandConfig::getCommandOptional(string $name): array|null
Look up a registered command by name, or null when no command with that name is registered.
| Name | Type | Description |
|---|---|---|
$name | string | The command name to look up. |
Returns array|null The command details, or null when not found.
CommandHelp
Prints help text to the console: a header, an overview of the commands, and the full usage for the whole application or for a single command.
Application
CommandHelp::Application(string $applicationName, string|null $optionalApplicationDescription): void
Print the help for the whole application: the header, an overview of the commands and the full usage for each command.
| Name | Type | Description |
|---|---|---|
$applicationName | string | The application name. |
$optionalApplicationDescription | string|null | An optional description of the application. |
Returns void
Command
CommandHelp::Command(string $commandName, string $commandDescription, callable $commandRouteCallback): void
Print the help for a single command: its name, description and usage, produced by running its route in help mode.
| Name | Type | Description |
|---|---|---|
$commandName | string | The command name. |
$commandDescription | string | The command description. |
$commandRouteCallback | callable | The command's route callback. |
Returns void
Commands
CommandHelp::Commands(): void
Print the full usage for every registered command.
Returns void
CommandsOverview
CommandHelp::CommandsOverview(): void
Print an indented one-line summary of every registered command.
Returns void
CommandSummary
CommandHelp::CommandSummary(string $commandName, string $commandDescription, callable $commandRouteCallback): void
Print a single command as one summary line of its name and description.
| Name | Type | Description |
|---|---|---|
$commandName | string | The command name. |
$commandDescription | string | The command description. |
$commandRouteCallback | callable | The command's route callback. |
Returns void
Header
CommandHelp::Header(string $applicationName, string|null $optionalApplicationDescription): void
Print a header of the application name and optional description that can go above any help output.
| Name | Type | Description |
|---|---|---|
$applicationName | string | The application name. |
$optionalApplicationDescription | string|null | An optional description of the application. |
Returns void
CommandHelpCommand
A command described for help output: its name, its description and its nested subcommands, each itself a CommandHelpCommand.
Properties
| Property | Type | Description |
|---|---|---|
$name | string | The command name. |
$description | string | The command description. |
$subcommands | array | The nested subcommands, each a CommandHelpCommand. |
__construct
$commandHelpCommand->__construct(string $name, string $description, array $subcommands)
Create a command help entry from its name, description and nested subcommands.
| Name | Type | Description |
|---|---|---|
$name | string | The command name. |
$description | string | The command description. |
$subcommands | array | The nested subcommands, each a CommandHelpCommand. |
CommandProcess
Starts an external process detached from the current script, so it keeps running independently after the PHP script finishes.
Start
CommandProcess::Start(string $executable, array $arguments, ?string $workingDirectory = null): void
Start a detached background process and return immediately, leaving it running independently of the script. Arguments are escaped and the process is launched with the platform's detached launcher.
| Name | Type | Description |
|---|---|---|
$executable | string | The executable to run. |
$arguments | array | The arguments to pass, each escaped as a shell argument. |
$workingDirectory | ?string | A directory to run in, or null for the current directory; must exist when given. |
Returns void
CommandRoute
The routing used inside a command's callback: match subcommands and typed arguments against the command line, then run the handler. In help mode the same calls print the usage instead of running it.
Handler
CommandRoute::Handler(callable $handler): void
Run the handler when all subcommands and arguments have been consumed, or report unexpected leftover subcommands. In help mode, print the usage line instead.
| Name | Type | Description |
|---|---|---|
$handler | callable | The callback that runs the command. |
Returns void
Help
CommandRoute::Help(string $commandPrefix, callable $helpCallback): void
Run the callback in help mode, so any routing inside it prints its usage under the given command prefix instead of matching arguments.
| Name | Type | Description |
|---|---|---|
$commandPrefix | string | The command prefix printed before the routing. |
$helpCallback | callable | The routing callback to run in help mode. |
Returns void
IntegerArgument
CommandRoute::IntegerArgument(string $name, callable $handler): void
Consume the next argument as an integer and pass it to the handler, or report an error when it is missing or not an integer. In help mode, print the argument's usage.
| Name | Type | Description |
|---|---|---|
$name | string | The argument name shown in usage. |
$handler | callable | Called with the parsed integer. |
Returns void
nextSubCommand
CommandRoute::nextSubCommand(string $name, callable $onSubCommand, callable $onNoSubCommand): void
Look at the next remaining subcommand and call one of the two callbacks depending on whether there is one.
| Name | Type | Description |
|---|---|---|
$name | string | The argument name. |
$onSubCommand | callable | Called with the next subcommand when there is one. |
$onNoSubCommand | callable | Called when there are no more subcommands. |
Returns void
Run
CommandRoute::Run(string $command, array $subCommands, callable $routeCallback): void
Run a command's route callback against the remaining subcommands, reporting an unhandled command when nothing matches.
| Name | Type | Description |
|---|---|---|
$command | string | The command name being routed. |
$subCommands | array | The remaining subcommand arguments. |
$routeCallback | callable | The command's route callback. |
Returns void
StringArgument
CommandRoute::StringArgument(string $name, callable $handler): void
Consume the next argument as a string and pass it to the handler, or report an error when it is missing. In help mode, print the argument's usage.
| Name | Type | Description |
|---|---|---|
$name | string | The argument name shown in usage. |
$handler | callable | Called with the argument value. |
Returns void
SubCommand
CommandRoute::SubCommand(string $name, string $description, callable $handler): void
Match the named subcommand as the next argument and run its handler when it matches. In help mode, print the subcommand's description and nested routing.
| Name | Type | Description |
|---|---|---|
$name | string | The subcommand name to match. |
$description | string | A description of the subcommand, shown in help. |
$handler | callable | The routing to run when the subcommand matches. |
Returns void