Documentation/Console commands

Console Commands

The framework HLEB2 includes both built-in console commands and the capability for developers using the framework to create their own.

Console commands are executed from the terminal or task scheduler, and their entry point is the 'console' file located in the project root, which is a regular PHP file.

#Standard Commands

You can get the list of framework commands by running the console command:

$php console --help

--version or -v                                 (displays the current version of the framework)
--info or -i [name]                             (shows current settings from common)
--help or -h                                    (displays the default list of commands)
--ping                                          (service check, returns predefined value)
--logs or -lg                                   (outputs the last lines from log files)
--list or -l                                    (displays the list of added commands)
--routes or -r                                  (formatted list of routes)
--find-route (or -fr) <url> [method] [domain]   (route search by URL)
--route-info (or -ri) <url> [method] [domain]   (route info by URL)
--clear-routes-cache or -cr                     (removes route cache)
--update-routes-cache or --routes-upd or -u     (updates route cache)
--clear-cache or -cc                            (clears framework cache)
--add <task|controller|middleware|model> <name> [desc]   (creates a class)
--create module <name>                          (creates module files)
--clear-cache--twig or -cc-twig                 (clears cache for Twig template engine)

<command> --help                                (displays command help)

#Creating Your Own Console Command

Example of adding your own console command by creating the corresponding class in the /app/Commands/Demo/ folder:

<?php

namespace App\Commands\Demo;

use Hleb\Base\Task;

class ExampleTask extends Task
{
    /**
     * Short description of the action.
     */
    protected function run(?string $arg = null): int
    {
        // Your code here.

        return self::SUCCESS_CODE;
    }
}

Or through the built-in console command:

$php console --add task demo/example-task "task description"

A file /app/Commands/Demo/ExampleTask.php will be created. If necessary, you can modify the default template for generating tasks.

In the framework, the command name consists of the class name (relative path) located in the /app/Commands/ folder. Therefore, it is recommended to initially give significant names to commands that reflect the essence of their action.

Now you can run the new command from the console, and it will also appear in the general list of commands.
But since there is no output result yet, add the --help parameter to get information about the command.

$php console demo/example-task --help

#Passing Parameters with a Command

Modify the command class so that the run() method accepts arguments.

<?php

namespace App\Commands\Demo;

use Hleb\Base\Task;

class ExampleTask extends Task
{
    /**
     * Connecting two values using `and`.
     */
    protected function run(string $argA, string $argB): int
    {
        echo $argA . ' and ' . $argB . PHP_EOL;

        return self::SUCCESS_CODE;
    }
}

The return value self::SUCCESS_CODE in the command class indicates that the command completed successfully. If commands in the console or task scheduler are chained with &&, execution will stop if self::ERROR_CODE is returned. This can also be useful in complex cases like CI/CD.

Next, run the command with two arguments to get the output 'speed and quality':

$php console demo/example-task speed quality

For specific cases, the framework allows creating named parameters for commands.

#Executing a Command from Code

You can execute the created command from within application code or from another console command.

use App\Commands\Demo\ExampleTask;
use Hleb\Static\Command;

Command::execute(new ExampleTask(), ['speed ', 'quality']);

However, in this case, the command’s output will not be displayed since its purpose has changed.
To retrieve the command’s result, use the $this->setResult() method within the class to set the data, and then access this data externally via the getResult() method.

use App\Commands\Demo\ExampleTask;
use Hleb\Static\Command;

$task = new ExampleTask();
Command::execute($task, ['speed', 'quality']);
echo $task->getResult();

#Specifying Text Color in the Terminal

To output text or a portion of it in one of the basic terminal colors, use the specially designated color() method in the command.
For example:

<?php

namespace App\Commands\Demo;

use Hleb\Base\Task;

class ColoredTask extends Task
{
    protected function run(): int
    {
        $greenText = $this->color()->green('this text is green');
        $yellowText = $this->color()->yellow('this text is yellow');

        echo $greenText . " and " . $yellowText . PHP_EOL;

        return self::SUCCESS_CODE;
    }
}

#Setting Command Restrictions with Attributes

The type and intended use of created commands can be controlled using PHP attributes.

The attribute #[Purpose] is used to define the command’s visibility scope.

<?php

namespace App\Commands\Demo;

use Hleb\Base\Task;
use Hleb\Constructor\Attributes\Task\Purpose;

#[Purpose(status:Purpose::CONSOLE)]
class ExampleTask extends Task {
// ... //
}

This attribute has a status argument, where you can specify options:
Purpose::FULL - unrestricted, the default value.
Purpose::CONSOLE - can only be used as a console command.
Purpose::EXTERNAL - used only in code, not listed in command list.

The #[Disabled] attribute for a command class disables the command.

The #[Hidden] attribute for a command class hides it from the console command list.

← Template Engine TWIG Container →

Page translated: chatgpt 4-o

PHP Framework HLEB2