Cómo Crear Comandos CLI Personalizado Mediante el Componente de Consola Symfony

() translation by (you can also view the original English article)

En este artículo vamos a explorar cómo se pueden crear comandos personalizados comando-línea interfaz (CLI) en las aplicaciones de PHP usando el componente de consola Symfony. Después de instalar las librerías necesarias, vamos a crear unos puñado de ejemplos para demostrar los conceptos de los componentes de la consola.

De hecho, este componente es utilizado por varios frameworks PHP para desarrollar aplicaciones CLI, y unos marcos popular ya están usando este componente como punto de partida.

¿Qué Es el Componente de Consola?

El componente de consola Symfony permite crear comandos CLI personalizados en las aplicaciones PHP. Si nunca has trabajado con Laravel o Symfony, podría ser consciente de las herramientas CLI que proporcionan con el fin de facilitar las operaciones diarias como:

generar código de andamios
cachés de claro
instalación, habilitación y deshabilitando servicios adicionales
corriente de base de datos de migraciones
y más

Por ejemplo, en el caso de Laravel, viene con la herramienta artisan que proporciona el montón de comandos de la utilidad que hacen nuestra vida más fácil. Se sorprendió al saber que la herramienta del artisan se basa en el componente de consola Symfony sí mismo! De hecho, existen muchos frameworks que aprovechan el componente de consola para construir sus herramientas de línea de comandos.

En este artículo vamos a explorar los fundamentos del componente de la consola para que pueda crear comandos CLI personalizados en las aplicaciones PHP. Para comenzar con, a seguir adelante e instalar el componente de consola con el compositor. Después de la instalación, construiremos unos ejemplos para fines de demostración.

Instalación y Configuración

En esta sección, vamos a instalar el componente de consola que se requiere para crear comandos de CLI en las aplicaciones PHP. Supongo que has instalado el compositor en su sistema, necesitaremos instalar el componente de consola que está disponible en Packagist.

Una vez que has instalado a compositor, adelante e instalar el componente de consola mediante el comando siguiente.

1	$composer require symfony/console

Debería haber creado el archivo composer.json, que debe tener este aspecto:

{
    "require": {
        "symfony/console": "^4.0"
    }
}

Vamos a modificar el archivo composer.json para ver como la siguiente:

{
    "require": {
        "symfony/console": "^4.0"
    },
    "autoload": {
         "psr-4": {
             "Console\\": "src"
         },
         "classmap": ["src"]
     }
}

Como hemos añadido una nueva entrada classmap, vamos a seguir adelante y actualizar el autoloader compositor ejecutando el siguiente comando.

1	$composer dump -o

Ahora, usted puede utilizar la console de nombres para clases de autocarga bajo el directorio src.

Su Primer Comando HelloWorld

Creación de comandos de la CLI usando el componente de console es un proceso de dos pasos.

En primer lugar, usted necesita crear una aplicación de consola que carga las dependencias necesarias y registra tus comandos personalizados.
A continuación, necesita crear archivos para todos los comandos que se han registrado en la aplicación de consola.

Crear la Aplicación de Consola

En esta sección, a seguir adelante y crear nuestra aplicación de consola personalizado.

La estructura de la propuesta del directorio de nuestra aplicación de consola se ve así.

|-- bin
|   `-- console
|-- composer.json
|-- composer.lock
|-- src
|   `-- App
|       `-- Commands
|           |-- ClearcacheCommand.php
|           `-- HelloworldCommand.php
`-- vendor

Seguir adelante y crear el archivo de aplicación principal bin/console con el siguiente contenido. Tenga en cuenta que no existe ninguna extensión de archivo y también asegurarse de que es ejecutable, así pues tendremos que ejecutarlo desde la línea de comandos.

#!/usr/bin/env php
<?php
require_once __DIR__ . '/../vendor/autoload.php';

use Symfony\Component\Console\Application;

$app = new Application();
$app->run();

La primera línea en el archivo #!/usr/bin/env php se cerciora de que se ejecuta bajo el entorno de PHP. Seguir adelante y tratar de ejecutarlo y ver como va.

$bin/console
Console Tool

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  help  Displays help for a command
  list  Lists commands

¡Bien! Con sólo unas pocas líneas de código, tiene una aplicación de consola personalizada rodando a su disposición! Pero no está haciendo nada útil en este momento. En la siguiente sección, veremos cómo crear comandos personalizados y regístrese con nuestra aplicación de consola personalizada.

Crear el Archivo de Comando de Hola Mundo

Vamos a ir adelante y crear nuestro primer comando personalizado: HelloworldCommand. Crear el archivo src/App/Commands/HelloworldCommand.php con el siguiente contenido.

<?php
namespace Console\App\Commands;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Input\InputArgument;

class HelloworldCommand extends Command
{
    protected function configure()
    {
        $this->setName('hello-world')
            ->setDescription('Prints Hello-World!')
            ->setHelp('Demonstration of custom commands created by Symfony Console component.')
            ->addArgument('username', InputArgument::REQUIRED, 'Pass the username.');
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $output->writeln(sprintf('Hello World!, %s', $input->getArgument('username')));
    }
}

Existen dos métodos principales que se deben crear al crear el comando personalizado: configure y execute.

Como su nombre indica, el método de configure le permite configurar el comando para que usted puede configurar el nombre del comando, una breve descripción del comando, el texto de ayuda y más. También puede configurar los argumentos para el comando para pasar parámetros al ejecutar un comando.

En el ejemplo anterior, el nombre de comando se establece en hello-world. También, queremos pasar un nombre de usuario como primer argumento, y por lo tanto ya hemos configurado con el método addArgument.

Por otro lado, el método execute contiene la lógica de la aplicación del comando. En nuestro caso, hemos mantenido lo bastante simple muestra Hello World como la salida del comando.

Antes de puede seguir adelante y realmente ejecutar este comando, debe registrarse con la aplicación de consola que hemos creado en la sección anterior. Vamos a revisar rápidamente el archivo bin/console para ver como la siguiente.

#!/usr/bin/env php
<?php
require_once __DIR__ . '/../vendor/autoload.php';

use Symfony\Component\Console\Application;
use Console\App\Commands\HelloworldCommand;

$app = new Application();
$app->add(new HelloworldCommand());
$app->run();

Como se puede ver, hemos utilizado el método add del objeto Application para agregar el comando HelloworldCommand. Vamos a enumerar rápidamente todos los comandos disponibles.

$bin/console list
Console Tool

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  hello-world      Prints Hello-World!
  help             Displays help for a command
  list             Lists commands

Como era de esperar, el comando hello-world aparece en la lista de comandos disponibles! ¡Anímate y ejecutarlo!

1	$bin/console hello-world tutsplus
2	Hello World!, tutsplus

Por lo que cómo puede configurar comandos básicos!

Un Ejemplo Real: Borrar Caché Comando

En la sección anterior, hemos construido el comando hello-world para demostrar los conceptos del componente de la consola. En esta sección, a seguir adelante y crear un ejemplo real que demuestra cómo puede crear un comando para borrar caché en la aplicación.

Crear el archivo de Borrar Cache Comando

Seguir adelante y crear el archivo src/App/Commands/ClearcacheCommand.php con el siguiente contenido.

<?php
namespace Console\App\Commands;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;

class ClearcacheCommand extends Command
{
    protected function configure()
    {
        $this->setName('clear-cache')
            ->setDescription('Clears the application cache.')
            ->setHelp('Allows you to delete the application cache. Pass the --groups parameter to clear caches of specific groups.')
            ->addOption(
                    'groups',
                    'g',
                    InputOption::VALUE_OPTIONAL,
                    'Pass the comma separated group names if you don\'t want to clear all caches.',
                    ''
                );
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $output->writeln('Cache is about to cleared...');

        if ($input->getOption('groups'))
        {
            $groups = explode(",", $input->getOption('groups'));

            if (is_array($groups) && count($groups))
            {
                foreach ($groups as $group)
                {
                    $output->writeln(sprintf('%s cache is cleared', $group));
                }
            }
        }
        else
        {
            $output->writeln('All caches are cleared.');
        }

        $output->writeln('Complete.');
    }
}

El método de configure es casi lo mismo, excepto que hemos utilizado el método de addOption para agregar una opción a nuestro comando. Así, podría pasar valores de grupo utilizando el parámetro de grupos.

Por otro lado, el método execute contiene la lógica de la aplicación de nuestro comando.

Si desea borrar la caché de grupos específicos, necesita pasar nombres de grupos junto con el parámetro --group. Por otro lado, omitir el parámetro --group si desea borrar cachés de todos. Usted puede haber notado que hemos mantenido el parámetro --group opcional proporcionando el valor de InputOption::VALUE_OPTIONAL en el tercer argumento del método addOption.

Registro y Prueba Con la Aplicación de Consola

Antes de pasar adelante y realmente ejecutarlo, vamos a registrar el comando con nuestra aplicación de consola.

#!/usr/bin/env php
<?php
require_once __DIR__ . '/../vendor/autoload.php';

use Symfony\Component\Console\Application;
use Console\App\Commands\HelloworldCommand;
use Console\App\Commands\ClearcacheCommand;

$app = new Application();
$app->add(new HelloworldCommand());
$app->add(new ClearcacheCommand());
$app->run();

Ahora, seguir adelante y ejecutar el comando bin/console clear-cache para borrar cachés de todos!

1	$bin/console clear-cache
2	Cache is about to cleared...
3	All caches are cleared.
4	Complete.

A continuación, si desea borrar cachés específicas, usted podría intentar algo como esto.

$bin/console clear-cache --groups=group1,group2
Cache is about to cleared...
group1 cache is cleared
group2 cache is cleared
Complete.

Por supuesto, tendrá que implementar la lógica actual para borrar la caché, pero eso debería servir como un buen punto de partida.

Conclusión

Hoy en día, pasamos por uno de los componentes populares proporcionados por el framework Symfony: el componente de consola. Realmente es un componente útil si desea desarrollar su propia aplicación de CLI que le ayuda a ejecutar sus tareas de utilidad día a día con facilidad.

En la primera mitad, pasamos por la instalación y configuración del componente. Luego, en la segunda mitad, creamos un par de ejemplos de comandos de la consola.

Háganos saber lo que piensas en los comentarios.

1	<?php
2	namespace Console\App\Commands;
3
4	use Symfony\Component\Console\Command\Command;
5	use Symfony\Component\Console\Input\InputInterface;
6	use Symfony\Component\Console\Output\OutputInterface;
7	use Symfony\Component\Console\Input\InputArgument;
8	use Symfony\Component\Console\Input\InputOption;
9
10	class ClearcacheCommand extends Command
11	{
12	protected function configure()
13	{
14	$this->setName('clear-cache')
15	->setDescription('Clears the application cache.')
16	->setHelp('Allows you to delete the application cache. Pass the --groups parameter to clear caches of specific groups.')
17	->addOption(
18	'groups',
19	'g',
20	InputOption::VALUE_OPTIONAL,
21	'Pass the comma separated group names if you don\'t want to clear all caches.',
22	''
23	);
24	}
25
26	protected function execute(InputInterface $input, OutputInterface $output)
27	{
28	$output->writeln('Cache is about to cleared...');
29
30	if ($input->getOption('groups'))
31	{
32	$groups = explode(",", $input->getOption('groups'));
33
34	if (is_array($groups) && count($groups))
35	{
36	foreach ($groups as $group)
37	{
38	$output->writeln(sprintf('%s cache is cleared', $group));
39	}
40	}
41	}
42	else
43	{
44	$output->writeln('All caches are cleared.');
45	}
46
47	$output->writeln('Complete.');
48	}
49	}