Console

The Command API allows you to create custom CLI commands for your application, integrated with WP-CLI. These commands can be used to perform tasks like database migrations, seeding, or administrative actions.

Registering Commands

To make a command available to the CLI, you must register it using the Command facade.

Register Command

Register a new command with the application.

Description:

The register() method binds a command name to a command class. All commands are automatically prefixed with droip. For example, registering make:model creates the command wp droip make:model.

Method Signature:

public static function register(string $name, string|object $command): void

Parameters:

• $name - The name of the command (e.g., process:orders)
• $command - The fully qualified class name of the command or a command instance. Must extend Ecommerce\Core\Console\CommandBase.

Examples:

use Ecommerce\Supports\Facades\Command;
use Ecommerce\App\Console\Commands\ProcessOrdersCommand;
use Ecommerce\App\Console\Commands\CleanupLogsCommand;

// Register a command class
Command::register('process:orders', ProcessOrdersCommand::class);

// Register with a class name string
Command::register('logs:cleanup', CleanupLogsCommand::class);

// Register an instance (not recommended for performance)
Command::register('db:seed', new DatabaseSeederCommand());

---

Command Structure

Custom commands must extend the Ecommerce\Core\Console\CommandBase class and implement the run() method. The base class provides several methods to configure the command's metadata.

Set Summary

Define the short description of the command.

Description:

The summary() method sets a brief, one-line explanation of what the command does. This is shown when listing available commands using wp droip.

Method Signature:

protected function summary(string $summary): self

Parameters:

• $summary - The short description text

Examples:

class ProcessOrdersCommand extends CommandBase
{
    protected function prepare()
    {
        $this->summary('Process pending orders');
    }
}

---

Set Description

Define the detailed description of the command.

Description:

The description() method sets the full documentation for the command, including usage examples and detailed behavioral explanation. This is shown when using the --help flag.

Method Signature:

protected function description(string $description): self

Parameters:

• $description - The detailed description text. Can include multiple lines and examples.

Examples:

class CreateUserCommand extends CommandBase
{
    protected function prepare()
    {
        $this->description("Creates a new user in the system.\n\n## EXAMPLES\n\n  wp droip user:create admin@example.com --role=admin");
    }
}

---

Define Arguments (Synopsis)

Define the arguments and options for the command.

Description:

The synopsis() method allows you to define positional arguments, flags, and associative options that the command accepts. It uses a Synopsis object to build the definition.

Method Signature:

protected function synopsis(Synopsis $synopsis): self

Parameters:

• $synopsis - A generic Synopsis object configured with argument details.

Examples:

class CreateProductCommand extends CommandBase
{
    protected function prepare()
    {
        // Define a positional argument 'name'
        $this->synopsis(
            $this->new_synopsis()
                ->type('positional')
                ->name('name')
                ->description('The name of the product')
        );

        // Define a flag '--active'
        $this->synopsis(
            $this->new_synopsis()
                ->type('flag')
                ->name('active')
                ->description('Set product as active')
                ->optional()
        );

        // Define an associated option '--price' with default
        $this->synopsis(
            $this->new_synopsis()
                ->type('assoc')
                ->name('price')
                ->description('The product price')
                ->default(0)
                ->optional()
        );
    }
}

---

Command Execution

Methods to handle command execution and validation.

Validate Command Arguments

Validate the arguments before the command runs.

Description:

The passed() method allows you to perform validation on the provided arguments and options. If this method returns false, the command execution is halted, and an error message is shown. This is useful for ensuring required parameters are present and valid.

Method Signature:

protected function passed(array $args, array $assoc): bool

Parameters:

• $args - Indexed array of positional arguments
• $assoc - Associative array of flags and options

Examples:

class CreateUserCommand extends CommandBase
{
    protected function passed($args, $assoc)
    {
        // Check if email is provided
        if (empty($assoc['email'])) {
            \WP_CLI::error('The --email parameter is required.');
            return false;
        }

        // Validate email format
        if (!filter_var($assoc['email'], FILTER_VALIDATE_EMAIL)) {
            \WP_CLI::error('Invalid email format.');
            return false;
        }

        return true;
    }
}

// Ensure positional argument exists
class FindOrderCommand extends CommandBase
{
    protected function passed($args, $assoc)
    {
        if (empty($args[0])) {
            \WP_CLI::error('Please provide an order ID.');
            return false;
        }
        return true;
    }
}

---

Run Command Logic

Execute the command's main logic.

Description:

The run() method is the entry point for your command. It receives the parsed arguments and associative options. You can use the Ecommerce\Supports\Facades\Info or standard WP-CLI methods to output information.

Method Signature:

abstract protected function run(array $args, array $assoc): void

Parameters:

• $args - Indexed array of positional arguments
• $assoc - Associative array of flags and options

Examples:

use Ecommerce\Core\Console\CommandBase;
use Ecommerce\App\Models\Order;
use Ecommerce\App\Models\Customer;

class CreateOrderCommand extends CommandBase
{
    protected function prepare()
    {
        $this->summary('Create a new order for a customer');

        $this->synopsis(
            $this->new_synopsis()->type('assoc')->name('email')->description('Customer email')
        );

        $this->synopsis(
            $this->new_synopsis()->type('assoc')->name('amount')->description('Order total amount')
        );
    }

    protected function run($args, $assoc)
    {
        $email = $assoc['email'];
        $amount = $assoc['amount'];

        $customer = Customer::where('email', $email)->first();

        if (!$customer) {
            \WP_CLI::error("Customer not found: {$email}");
            return;
        }

        $order = Order::create([
            'customer_id' => $customer->id,
            'total' => $amount,
            'status' => 'pending'
        ]);

        \WP_CLI::success("Order #{$order->id} created successfully.");
    }
}

---