ssnepenthe/apheleia-cli

An alternative syntax for writing WP-CLI commands

0.1.0 2022-07-05 20:31 UTC

Requires

• php: ^7.4 || ^8.0

Requires (Dev)

• php-di/invoker: ^2.3
• php-stubs/wp-cli-stubs: ^2.6
• phpunit/phpunit: ^9.5
• vimeo/psalm: ^4.22
• wp-cli/wp-cli: ^2.6

MIT

README

Apheleia CLI provides an alternate approach to writing WP-CLI commands. It eliminates the need for docblock command definitions and should allow you to take full advantage of the autocomplete features in your favorite editor.

The syntax for Apheleia commands is loosely modeled after the symfony/console package.

Warning

This package is currently in development and is subject to breaking changes without notice until v1.0 has been tagged.

It is one in a series of WordPress toys I have been working on with the intention of exploring ways to modernize the feel of working with WordPress.

As the label suggests, it should be treated as a toy.

Installation

composer require ssnepenthe/apheleia-cli

Usage

I think this is best explained through examples, so let's demonstrate some different ways we might implement the example hello command from the WP-CLI handbook commands cookbook.

The preferred approach is to create self-contained command classes.

Extend the Command class using the configure method to define the command signature and the handle method to define the command logic to be executed when the command is called:

use ApheleiaCli\Argument;
use ApheleiaCli\Command;
use ApheleiaCli\Option;
use WP_CLI;

class HelloCommand extends Command
{
    public function configure(): void
    {
        $this->setName('example hello')
            ->setDescription('Prints a greeting.')
            ->addArgument(
                (new Argument('name'))
                    ->setDescription('The name of the person to greet.')
            )
            ->addOption(
                (new Option('type'))
                    ->setDescription('Whether or not to greet the person with success or error.')
                    ->setDefault('success')
                    ->setOptions('success', 'error')
            )
            ->setUsage("## EXAMPLES\n\n\twp example hello newman")
            ->setWhen('after_wp_load');
    }

    public function handle($args, $assocArgs)
    {
        [$name] = $args;

        $type = $assocArgs['type'];
        WP_CLI::$type("Hello, $name!");
    }
}

Commands are registered using the CommandRegistry.

use ApheleiaCli\CommandRegistry;

$registry = new CommandRegistry();

$registry->add(new HelloCommand());

$registry->initialize();

There is a significant difference between the command we have created and the original version: WP-CLI does not have any description text to display for the parent example command when you run wp help example.

There are a couple of different approaches we can take to fix this.

The first is to register a dedicated namespace alongside our HelloCommand:

$registry->namespace('example', 'Implements example command.');
$registry->add(new HelloCommand());

The second is to take advantage of command groups.

First we need to remove the parent command portion of our command name:

class HelloCommand extends Command
{
    public function configure(): void
    {
        $this->setName('hello')
            // etc...
            ;
    }

    // ...
}

And then we use the group method on our registry. The callback provided to the group method will receive a registry instance that has been scoped such that any commands added within the callback will automatically be registered as children of the example command:

$registry->group('example', 'Implements example command.', function (CommandRegistry $registry) {
    $registry->add(new HelloCommand());
});

It is also possible to define a command without extending the Command class:

$registry->add(
    (new Command())
        ->setName('hello')
        ->setDescription('Prints a greeting.')
        ->addArgument(
            (new Argument('name'))
                ->setDescription('The name of the person to greet.')
        )
        ->addOption(
            (new Option('type'))
                ->setDescription('Whether or not to greet the person with success or error.')
                ->setDefault('success')
                ->setOptions('success', 'error')
        )
        ->setUsage("## EXAMPLES\n\n\twp example hello newman")
        ->setWhen('after_wp_load')
        ->setHandler(function ($args, $assocArgs) {
            [$name] = $args;

            $type = $assocArgs['type'];
            WP_CLI::$type("Hello, $name!");
        })
);

Advanced Usage

By default, command handlers should be written more-or-less the same as they would if you were working directly with WP-CLI. That is to say they should always expect to receive a list of command arguments as the first parameter and an associative array of command options as the second:

$command->setHandler(function (array $args, array $assocArgs) {
    // ...
});

However, commands can modify handler signatures by overriding their handlerInvokerClass property.

This package only ships with one alternative handler invoker: the PhpDiHandlerInvoker. It uses the php-di/invoker package to call command handlers.

Before it can be used, you must install php-di/invoker:

composer require php-di/invoker

Then set the handler invoker on your command (or a base command from which all of your commands extend):

use ApheleiaCli\Invoker\PhpDiHandlerInvoker;

class HelloCommand extends Command
{
    protected $handlerInvokerClass = PhpDiHandlerInvoker::class;

    // ...
}

With this in place, command handlers can now ask for command parameters by name:

class HelloCommand extends Command
{
    // ...

    public function handle($name, $type)
    {
        WP_CLI::$type("Hello, $name!");
    }
}