Download the PHP package snicco/better-wp-cli without Composer

BetterWPCLI - The missing parts to the already awesome WP-CLI

BetterWPCLI is a small, zero-dependencies, PHP library that helps you build enterprise WordPress command-line applications.

BetterWPCLI does not replace or take over any functionality of the wp runner.

Instead, it sits between WP-CLI and your custom commands.

Table of contents

1. Motivation
2. Installation
3. Usage
   1. Commands
      1. Synopsis
      2. Default flags
   2. Registering Commands
   3. Console Input
   4. Console Output
      1. Verbosity levels
   5. Styling command output
      1. Title
      2. Section
      3. Info
      4. Note
      5. Success
      6. Warning
      7. Error
   6. Interactive input
      1. Asking for confirmation
      2. Asking for information
      3. Hidden input
      4. Validating answers
   7. Exception handling
      1. Uncaught exceptions
      2. Logging
      3. Converting errors to exceptions
   8. Testing
4. Contributing
5. Issues and PR's
6. Security
7. Credits

Motivation

We developed this library for the WordPress related components of the Snicco project due to the following reasons:

• ❌ WP-CLI has no native support for dependency-injection and does not support lazy-loading of commands.

• ❌ WP-CLI encourages command configuration in meta language or by hard-coded string names.

  • see Why Config Coding Sucks.
  • "Was it repeating or was it multiple?", "Was it long_description or long_desc?"

• ❌ WP-CLI has inconsistent and unconfigurable handling of writing to STDOUT and STDERR.

  • WP_CLI::log(), WP_CLI::success(), WP_CLI::line() write to STDOUT
  • WP_CLI::warning() and WP_CLI::error() write to STDERR.
  • Progress bars are written to STDOUT making command piping impossible.
  • Prompts for input are written to STDOUT making command piping impossible.
  • Uncaught PHP notices (or other errors) are written to STDOUT making command piping impossible.

• ❌ WP-CLI has no error handling. Thrown exceptions go directly to the global shutdown handler (wp_die) and show up in the terminal as the dreaded "There has been a critical error on this website.Learn more about troubleshooting WordPress." . Thus, they also go to STDOUT instead of STDER.

• ❌ WP-CLI can detect ANSI support only for STDOUT and not individually for both STDOUT and STDERR.

  • If you are redirecting STDOUT you probably don't want STDERR to lose all colorization.

• ❌ WP-CLI commands are hard to test because its encouraged to use the static WP_CLI class directly in your command instead of using some Input/Output abstraction.

• ❌ WP-CLI does not play nicely with static analysers like psalm and phpstan.
  • You receive two completely untyped arrays in your command classes.
  • You have no easy way of separating positional arguments from repeating positional arguments.

BetterWPCLI aims to solve all of these problems while providing you many additional features.

BetterWPCLI is specifically designed to be usable in distributed code like public plugins.

Installation

BetterWPCLI is distributed via composer.

Usage

Commands

All commands extend the Command class.

One Command class is responsible for handling exactly ONE command and defining its own synopsis.

The command class reproduces the example command described in the WP-CLI commands cookbook .

Synopsis

The Synopsis value object helps you to create the command synopsis using a clear PHP API.

The Synopsis has a rich set of validation rules that are only implicit in the WP-CLI. This helps you prevent certain gotchas right away like:

• Having duplicate names for arguments/options/flags.
• Registering a positional argument after a repeating argument.
• Setting a default value that is not in the list of allowed values.
• ...

A Synopsis consists of zero or more positional arguments, options or flags.

These a represented by their respective classes:

• InputArgument
• InputOption
• InputFlag

Default flags

The Command class has several inbuilt flags that you can use in your commands.

You can automatically add them to all your commands by adding them to the parent synopsis.

This is totally optional.

This will add the following command synopsis:

Registering commands

Commands are registered by using the WPCLIApplication class.

Console Input

Console input is abstracted away through an Input interface.

All commands will receive an instance of Input that holds all the passed arguments.

Console Output

Console output is abstracted away through an Output interface.

All commands will receive an instance of Output.

Its recommend that you write use this class in your commands to write to the output stream.

This way your commands will stay testable as you can just substitute this Output interface with a test double.

However, there is nothing preventing you from using the WP_CLI class in your commands.

Verbosity levels

BetterWPCLI has a concept of verbosity levels to allow the user to choose how detailed the command output should be.

See: default flags for instructions of adding the flags to your commands.

WP-CLI has a similar concept but only allows you to choose between quiet (no output) and debug (extremely verbose output including wp-cli internals.)

BetterWPCLI has the following five verbosity levels which can be either set per command or by using a SHELL_VERBOSITY environment value.

(Command line arguments have a higher priority then SHELL_VERBOSITY and --debug and --quiet overwrite all values unique to BetterWPCLI.)

It is possible to print specific information only for specific verbosity levels.

Styling command output

BetterWPCLI provides you a utility class SniccoStyle that you can instantiate in your commands.

This class contains many helpers methods for creating rich console output. The style is based on the styling of the symfony/console package.

Color support is automatically detected based on the operating system, whether the command is piped and the provided flags like: --no-color, --no-ansi. See: default flags.

This class will write to STDERR unless you configure it not too.

You should use the Output instance to write important information to STDOUT.

Important information is information that could in theory be piped into other commands.

If your command does not output such information just return Command::SUCCESS and don't output anything. Silence is Golden.

Title

The title() method should be used once at the start of a command.

Section

The section() method can be used to separate multiple coherent sections of a command

Info

The info() method can be used signalize successful completion of a section.

Note

The note() method can be used to draw extra attention to the message. Use this sparingly.

Text

The text() method output regular text without colorization.

Success

The success() method should be used once at the end of a command.

Warning

The warning() method should be used once at the end of a command.

Error

The error() method should be used once at the end of a command if it failed.

Interactive input

The SniccoStyle class provides several methods to get more information from the user.

If the command was run with the --no-interaction flag the default answer will be used automatically. See: default flags.

All output produced by interactive questions is written to STDERR.

Asking for confirmation

Asking for information

Hidden input

You can also ask a question and hide the response.

This will be done by changing the stty mode of the terminal.

If stty is not available, it will fall back to visible input unless you configure it otherwise.

Validating the provided input

You can validate the provided answer of the user. If the validation fails the user will be presented with the same question again.

You can also set a maximum amount of attempts. If the maximum attempts are exceeded an InvalidAnswer exception will be thrown.

Exception handling

BetterWPCLI comes with very solid exception/error-handling.

This behaviour is however totally isolated and only applies to YOUR commands. Core commands or commands by other plugins are not affected in any way.

Uncaught exceptions

If your command throws an uncaught exception two things will happen:

1. The exception is displayed in STDERR while taking the current verbosity into consideration.
2. The exception is WPCLIApplication)

This is how exceptions are displayed with different verbosity levels:

VERBOSTIY::NORMAL:

VERBOSTIY::VERBOSE:

VERBOSTIY::VERY_VERBOSE and above:

You can disable catching exceptions although this is not recommended.

Logging

By default a StdErrLogger is used to log exceptions using error_log.

This class is suitable for usage in distributed code as it will log exceptions to the location configured in WP_DEBUG_LOG. If you want to use a custom logger you have to pass it as the third argument when creating your WPCLIApplication.

The Logger will create a log record for all uncaught exceptions during your command lifecycle + all commands that return a non-zero exit code.

Converting errors to exceptions

In a normal WP-CLI command errors such as notices, warnings and deprecations are not handled at all. Instead, they bubble up to the global PHP error handler.

It is a best practice to treat notices and warnings as exceptions.

BetterWPCLI will promote all errors during YOUR command to instances of ErrorException.

The following code:

will throw an exception and exit with code 1.

By default, all error including deprecations are promoted to exceptions.

If you find this to strict for your production environment you can customize the behaviour.

Testing

This package comes with dedicated testing utilities which are in a separate package snicco/better-wp-cli-testing.

Contributing

This repository is a read-only split of the development repo of the Snicco project.

This is how you can contribute.

Reporting issues and sending pull requests

Please report issues in the Snicco monorepo.

Security

If you discover a security vulnerability within BetterWPAPI, please follow our disclosure procedure.

Credits

Inspecting the source of the symfony console symfony/console was invaluable to developing this library.