Constants

ARG_REQUIRED

ARG_REQUIRED

Command argument is required.

ARG_OPTIONAL

ARG_OPTIONAL

Command argument is optional.

VALUE_REQUIRED

VALUE_REQUIRED

VALUE_NONE

VALUE_NONE

Properties

$runner

$runner : \Dewdrop\Cli\Run

The \Dewdrop\Cli\Run instance that is managing this and other CLI commands.

Type

\Dewdrop\Cli\Run

$renderer

$renderer : \Dewdrop\Cli\Renderer\RendererInterface

The renderer that should be used for all command output. No output should be rendered directly (i.e. with echo, print, printf, etc.), so that it is easier to capture and examine output during testing.

Type

\Dewdrop\Cli\Renderer\RendererInterface

$paths

$paths : \Dewdrop\Paths

Paths utility to assist CLI commands in getting around the WP environment.

Type

\Dewdrop\Paths

$command

$command : string

The command name that should be used on the CLI to select this command class for execution. For example, when running the dewdrop CLI tool like this:

./vendor/bin/dewdrop command-name

\Dewdrop\Cli\Run will select the command class that has a command class that has a $command property value of "command-name"

Type

string

$description

$description : string

A brief, 8-12 word description of this command's purpose. This will be displayed in the command's own help content and the global list of available commands.

Type

string

$aliases

$aliases : array

Any aliases that can be used to trigger this command in addition to the primary command name.

Type

array

$primaryArg

$primaryArg : string

The name of the command's primary argument. The primary argument's value can be specified without naming the argument explicitly on the command line. Using popular version control system Subversion as an example, you can do a code checkout without specifying the name of the path argument like this:

svn checkout http://example.org/path

In that case, the path argument is the primary argument of SVN's checkout command.

In Dewdrop, if your command had a primary argument of "name" and the user supplied this input:

./vendor/bin/dewdrop my-command --folder=example "Example Name Value"

The argument parser would set the name argument's value to "Example Name Value" because that is the value expression not explicitly assigned to another argument name.

Users can still explicitly set the argument name for the primary argument, too, if they prefer:

./vendor/bin/dewdrop --name="Example Name Value"

Type

string

$args

$args : array

The arguments that are available for this command.

Type

array

$supportFallbackArgs

$supportFallbackArgs : boolean

Whether this command supports passing along any unrecognized arguments to another command. For example, if your CLI command is a thin wrapper around phpunit, you could pass all unrecognized arguments to phpunit so that the Dewdrop user has the full capabilities of phpunit available to them.

Type

boolean

$fallbackArgs

$fallbackArgs : array

Any unrecognized arguments that should be passed along to the an underlying/wrapped command.

Type

array

$examples

$examples : array

Examples of valid usage for this command.

Type

array

Methods

__construct()

__construct(\Dewdrop\Cli\Run  $runner, \Dewdrop\Cli\Renderer\RendererInterface  $renderer) 

Instantiate command with a runner and renderer. After the command sub-class runs its init() method, check to ensure the required basic properties were set.

Parameters

\Dewdrop\Cli\Run $runner
\Dewdrop\Cli\Renderer\RendererInterface $renderer

init()

init() : void

Implement the init() method in your command sub-class to set required properties. You'll likely call:

  • setCommand()
  • setDescription()
  • addAlias()
  • addArg()
  • addPrimaryArg()
  • addExample()

execute()

execute() 

Run your command. This will only be called if parseArgs() returns true, indicating that the command line arguments could be successfully parsed according the definitions you created in your init() method.

parseArgs()

parseArgs(array  $args) : boolean

Parse the arguments passed to this command.

If the "--help" argument is present anywhere in the argument input, all further parsing will be aborted and the command's help content will be displayed.

For all argument names and their aliases, there are multiple acceptable formats of argument and value. For example, all of these inputs are equivalent:

./vendor/bin/dewdrop my-command --argument-name=value ./vendor/bin/dewdrop my-command --argument-name value ./vendor/bin/dewdrop my-command --argument-alias=value ./vendor/bin/dewdrop my-command -argument-alias=value ./vendor/bin/dewdrop my-command -argument-alias value

In short, you can use one or two dashes at the beginning of the argument name and you can separate the value from the name with either a space or an equals sign.

For every argument your command supports, you need to implement a setter method. For example, if you have an argument with the name "my-argument" then your command class needs a method called "setMyArgument()".

Also note that the command API supports the concept of a "primary argument". See the documentation for the $primaryArgument property for more information about that feature.

Parameters

array $args

Returns

boolean —

Whether args were fully parsed and command can be executed.

setDescription()

setDescription(string  $description) : \Dewdrop\Cli\Command\CommandAbstract

Set a human-friendly description of this command's role

Parameters

string $description

Returns

\Dewdrop\Cli\Command\CommandAbstract

getDescription()

getDescription() : string

This method is available so the Help command can display a list of available commands.

Returns

string

setCommand()

setCommand(string  $command) : \Dewdrop\Cli\Command\CommandAbstract

Set the primary command that will be used to run this command. This value differs from aliases because it is displayed in the default help listings.

Parameters

string $command

Returns

\Dewdrop\Cli\Command\CommandAbstract

getCommand()

getCommand() : string

This method is available so the Help command can display a list of available commands.

Returns

string

addAlias()

addAlias(string  $alias) : \Dewdrop\Cli\Command\CommandAbstract

Register an alias for this command. This can be useful to provide the user other ways to execute the command. For example, you might provide a shortened version of the command name so that experienced users can avoid typing the full name once their comfortable with the command.

Parameters

string $alias

Returns

\Dewdrop\Cli\Command\CommandAbstract

addPrimaryArg()

addPrimaryArg(string  $name, string  $description, boolean  $required, array  $aliases = array()) : \Dewdrop\Cli\Command\CommandAbstract

Add an argument while also setting it as the primary arg for this command. For more information about the primary arg feature, read the docs on the $primaryArg property.

Parameters

string $name
string $description
boolean $required
array $aliases

Returns

\Dewdrop\Cli\Command\CommandAbstract

addArg()

addArg(string  $name, string  $description, boolean  $required, array  $aliases = array(), string  $mode = self::VALUE_REQUIRED) : \Dewdrop\Cli\Command\CommandAbstract

Register a new argument allowed to be used with this command.

Parameters

string $name
string $description
boolean $required
array $aliases
string $mode

Returns

\Dewdrop\Cli\Command\CommandAbstract

setSupportFallbackArgs()

setSupportFallbackArgs(boolean  $supportFallbackArgs) : \Dewdrop\Cli\Command\CommandAbstract

Set whether this command supports fallback args.

Parameters

boolean $supportFallbackArgs

Returns

\Dewdrop\Cli\Command\CommandAbstract

addExample()

addExample(string  $description, string  $command) : \Dewdrop\Cli\Command\CommandAbstract

Add an example usage for this command. These are displayed in the command's help content.

Parameters

string $description
string $command

Returns

\Dewdrop\Cli\Command\CommandAbstract

isSelected()

isSelected(string  $inputCommand) : boolean

Based on the supplied input command, determine whether this command should be selected for argument parsing and execution.

Parameters

string $inputCommand

Returns

boolean

help()

help() : $this

Display help content for this command.

The basic command name and description, any avaialble aliases, and any avaialble examples are all included in the help display.

This content can be accessed by called "--help" on this command directly:

./vendor/bin/dewdrop my-command --help

Or, you can use the built-in help command to access it:

./vendor/bin/dewdrop help my-command

Returns

$this

getFallbackArgString()

getFallbackArgString() : string

Get a string representing all the args that were not recognized directly by this command and should be passed along to the underlying/wrapped command.

Returns

string

abort()

abort(string  $errorMessage, boolean  $displayHelp = true) : boolean

Render the provided error message and display the command's help content.

Parameters

string $errorMessage
boolean $displayHelp

Returns

boolean

passthru()

passthru(string  $command) : integer

Use the built-in passthru() function to call an external command and return its exit status. This is separated into its own method primarily to make it easier to mock during testing.

Parameters

string $command

Returns

integer

exec()

exec(string  $command, array  $output, integer  $exitStatus) : void

Run a shell command using PHP's exec fucntion, which may be preferable to passthru() when you need to capture output. This is primarily present to make it easy to mock exec() during testing.

Parameters

string $command
array $output
integer $exitStatus

evalPathArgument()

evalPathArgument(string  $path) : string

Change "~" prefix to the user's home folder.

Bash doesn't do "~" evaluation automatically for command arguments, so we do it here to avoid confusing developers by creating a "~" folder in their WP install instead.

Parameters

string $path

Returns

string

autoDetectExecutable()

autoDetectExecutable(string  $name) : string

First, we check to see if the executable is present in Composer's "./vendor/bin/" folder. Then, we attempt to locate the named executable using "which", if it is available. Otherwise, just return the name and hope it is in the user's $PATH.

Parameters

string $name

Returns

string

setArgValue()

setArgValue(string  $name, string  $value) : \Dewdrop\Cli\Command\CommandAbstract

Set the valid of the specified argument.

The argument's name is inflected to form a setter name that will be called to set the value. If no setter is available, execution will be aborted.

Parameters

string $name
string $value

Returns

\Dewdrop\Cli\Command\CommandAbstract

argTakesNoValue()

argTakesNoValue(string  $name) : boolean

Check to see if the given arg requires a value or not.

Parameters

string $name

Returns

boolean