Download the PHP package phpdevcommunity/php-console without Composer

PHP Console

A lightweight PHP library designed to simplify command handling in console applications. This library is dependency-free and focused on providing a streamlined and efficient solution for building PHP CLI tools.

Installation

You can install this library via Composer. Ensure your project meets the minimum PHP version requirement of 7.4.

Requirements

• PHP version 7.4 or higher

Table of Contents

1. Setup in a PHP Application
2. Creating a Command
3. Defining Arguments and Options
4. Handling Different Output Types

I attempted to rewrite the chapter "Setup in a PHP Application" in English while updating the document, but the update failed due to an issue with the pattern-matching process. Let me fix the issue manually. Here's the rewritten content in English:

Setup in a PHP Application

To use this library in any PHP application (Symfony, Laravel, Slim, or others), first create a bin directory in your project. Then, add a script file, for example, bin/console, with the following content:

By convention, the file is named bin/console, but you can choose any name you prefer. This script serves as the main entry point for your CLI commands. Make sure the file is executable by running the following command:

Creating a Command

To add a command to your application, you need to create a class that implements the CommandInterface interface. Here is an example implementation for a command called send-email:

Registering the Command in CommandRunner

After creating your command, you need to register it in the CommandRunner so that it can be executed. Here is an example of how to register the SendEmailCommand:

The CommandRunner takes an array of commands as its parameter. Each command should be an instance of a class that implements the CommandInterface. Once registered, the command can be called from the console.

Example Usage in the Terminal

1. Command without a subject option:

   Output:

2. Command with a subject option:

   Output:

3. Command with an invalid email format:

   Output:

4. Command without the required argument:

   Output:

Explanation of the Features Used

1. Required Arguments:

   • The recipient argument is mandatory. If missing, the command displays an error.

2. Optional Options:

   • The --subject option allows defining the subject of the email. If not specified, a default value ("No subject") is used.

3. Simple Validation:

   • The email address is validated using filter_var to ensure it has a valid format.
4. User Feedback:
   • Clear and simple messages are displayed to guide the user during the command execution.

Defining Arguments and Options

Arguments and options allow developers to customize the behavior of a command based on the parameters passed to it. These concepts are managed by the CommandArgument and CommandOption classes, respectively.

1 Arguments

An argument is a positional parameter passed to a command. For example, in the following command:

recipient@example.com is an argument. Arguments are defined using the CommandArgument class. Here are the main properties of an argument:

• Name (name): The unique name of the argument.
• Required (isRequired): Indicates whether the argument is mandatory.
• Default Value (defaultValue): The value used if no argument is provided.
• Description (description): A brief description of the argument, useful for help messages.

Example of defining an argument:

If a required argument is not provided, an exception is thrown.

2 Options

An option is a named parameter, often prefixed with a double dash (--) or a shortcut (-). For example, in the following command:

--subject is an option. Options are defined using the CommandOption class. Here are the main properties of an option:

• Name (name): The full name of the option, used with --.
• Shortcut (shortcut): A short alias, used with a single dash (-).
• Description (description): A brief description of the option, useful for help messages.
• Flag (isFlag): Indicates whether the option is a simple flag (present or absent) or if it accepts a value.

Example of defining an option:

An option with a flag does not accept a value; its mere presence indicates that it is enabled.

3 Usage in a Command

In a command, arguments and options are defined by overriding the getArguments() and getOptions() methods from the CommandInterface.

Example:

In this example:

• recipient is a required argument.
• --subject (or -s) is an option that expects a value.
• --verbose (or -v) is a flag option.

4 Validation and Management

Arguments and options are automatically validated when the command is executed. For instance, if a required argument is missing or an attempt is made to access an undefined option, an exception will be thrown.

The InputInterface allows you to retrieve these parameters in the execute method:

• Arguments: $input->getArgumentValue('recipient')
• Options: $input->getOptionValue('subject') or $input->hasOption('verbose')

This ensures clear and consistent management of the parameters passed within your PHP project.

Handling Different Output Types

Output management provides clear and useful information during command execution. Below is a practical example demonstrating output functionalities.

Example: Command UserReportCommand

This command generates a report for a specific user and uses various output features.

Features Used

1. Rich Messages:

   • success($message): Displays a success message.
   • warning($message): Displays a warning message.
   • error($message): Displays a critical error message.
   • info($message): Displays an informational message.
   • title($title): Displays a main title.

2. Structured Output:

   • json($data): Displays data in JSON format.
   • list($items): Displays a simple list.
   • listKeyValues($data): Displays key-value pairs.
   • table($headers, $rows): Displays tabular data.
3. Progression and Interactivity:
   • progressBar($total, $current): Displays a progress bar.
   • spinner(): Displays a loading spinner.
   • confirm($question): Prompts for user confirmation.

License

This library is open-source software licensed under the MIT license.