banner comandos personalizados en Laravel

Artisan, la consola interactiva de Laravel es nuestro asistente cuando estamos creando o trabajando sobre un proyecto. En esta publicación vamos a conocer cómo podemos crear comandos personalizados mediante un entretenido ejemplo.

Preparación de nuestro ejemplo

Para que esta publicación sea didáctica, vamos a tener un ejemplo donde un administrador de un sitio web podrá decidir cuándo activar o desactivar el registro de nuevos usuarios.

Los pasos a seguir para la preparación de este tutorial son simples, para comenzar creamos un nuevo proyecto Laravel con Composer ejecutando en la terminal:

Procedemos ahora con agregar las credenciales necesarias para la conexión a una base de datos en el archivo .env.

Seguidamente ejecutamos el comando php artisan make:auth para generar un sitio con registro, login y recuperación de contraseña.

Para manejar la habilitación del registro de nuevos usuarios vamos a crear un modelo llamado Config con su respectiva migración ejecutando el siguiente comando:

En el modelo app/Config.php vamos a colocar 2 propiedades, las cuales son:

La tabla del modelo no seguirá la convención de nombres en plural pues en ella se almacenará solo la información del sitio web.

La migración generada con este modelo debe quedarnos de esta forma en el método up:

Vamos a dirigirnos al archivo database/seeds/DatabaseSeeder.php para tener el registro. El archivo lo dejaremos de esta forma:

Finalmente ejecutamos las migraciones junto a los seeders con el siguiente comando:

Creación de un comando personalizado

Para crear un nuevo comando de Artisan solo debemos ejecutar la siguiente instrucción en nuestra terminal:

Este comando creará una nueva clase en el directorio app/Console/Commands llamada RegistrationStatus. Puedes además enviar la opción  --command con la cual podemos especificar cómo puede ser llamado el comando desde la terminal.

Lógica de nuestro comando

Vamos a dirigirnos a la clase recién creada en la dirección app/Console/Commands/RegistrationStatus.php y vamos a comenzar colocando el nombre del comando y su descripción.

Con la propiedad $signature se define el nombre o la manera de llamar al comando desde la consola.

Adicionalmente, en nuestro caso también vamos a requerir un parámetro llamado activation el cual tendrá como valor predeterminado on.

Los comandos en Laravel pueden tener como entradas de datos: opciones y/o argumentos. Una opción de un comando puede cambiar el comportamiento de un comando y se expresa con el prefijo -- , mientras que un argumento es un valor que puede requerir un comando para trabajar sobre él.

Ahora con la propiedad $description colocamos la descripción de nuestro comando:

Por último, vamos a definir la lógica de nuestro comando en el método handle de esta forma:

El método argument nos ayuda a recuperar un argumento pasado al invocar el comando (de la misma manera existe el método option si quieres recuperar una opción).  Por otro lado, el método info nos permite enviar un mensaje a la consola, también tenemos disponible el método error para enviar un mensaje de advertencia o error.

Culminación del ejemplo

Vamos a crear el método estático allowRegistrations en nuestro modelo Config creado anteriormente.

Con esto ya tenemos nuestro comando funcionando. Al ejecutar php artisan list podemos verlo incluido en el listado.

En este punto ya nuestro comando funciona, pero para que nuestro ejemplo esté completo debemos restringir el acceso al registro cuando no esté activo.  Para ello vamos a crear un middleware el cual se encargará de esto:

Seguidamente, editamos el método handle para colocar la restricción de acceso:

Agregamos el middleware recién creado al arreglo $routeMiddleware del archivo app/Http/Kernel.php de esta forma:

En el archivo de rutas web.php vamos a realizar algunos cambios para aplicar el middleware sobre las rutas de registro. Es decir, vamos a trabajar con las rutas directamente en el archivo web.php para configurar la activación o desactivación del registro en la aplicación, dependiendo del estado.

Para culminar, vamos a modificar la vista welcome.blade.php para mostrar un mensaje de advertencia. Agregaremos después de la etiqueta body el siguiente contenido:

Closure Commands

En nuestro ejemplo hemos creado una clase para nuestro comando lo cual puede ser más cómodo. Pero existe la posibilidad de crear comandos con solo un Closure o función anónima desde el archivo routes/console.php. Laravel por defecto nos muestra un ejemplo de su uso en el mismo archivo:

Así podemos crear el comando de nuestro ejemplo de esta forma:

El resultado seria el mismo pero desde una clase podemos extender a otros métodos en caso de que el comando pueda tener mucha más lógica, el código estaría un poco más ordenado y sería más fácil de encontrar. Así que queda de tu parte elegir la forma de crear comandos que prefieras.

Entrada de datos

Si necesitas crear un comando el cual necesite preguntar, confirmar o seleccionar entre múltiples opciones puedes hacerlo con algunos métodos disponibles.

Ejecutar comandos desde la aplicación

Podemos ejecutar comandos con el facade Artisan desde cualquier lugar de nuestra aplicación esta forma:

El método call desde la versión 5.8 puede recibir el primer parámetro con el comando completo. En versiones anteriores las parámetros del comando eran pasados en un arreglo.

Probar comandos de forma automatizada

Además podemos crear una o más pruebas unitarias para comprobar la funcionalidad del comando y otra prueba funcional para comprobar que se pueda acceder o no según el estado del registro.

Comenzamos creando la prueba unitaria con el siguiente comando en nuestra terminal:

En el test recién creado vamos a colocar 2 pruebas las cuales son las siguientes:

Con estas pruebas estamos comparando que cuando se ejecute el comando con los argumentos on y off se actualice la columna allow_registrations en nuestra base de datos con el valor correspondiente.

Creamos ahora una Feature Test con el comando:

Procedemos ahora a colocar 2 pruebas dentro del archivo:

Con estas pruebas comprobamos que dependiendo del valor en la columna allow_registrations se habilitara o no el acceso al registro de nuevos usuarios.

Finalmente, procedemos a ejecutar en la consola las pruebas con vendor/bin/phpunit (o vendor\bin\phpunit si usas Windows) y las deberíamos verlas pasar.

Nunca te confíes de pruebas que pasen al primer intento. Regresa al comando RegistrationStatus e invierte la lógica condicional, re-ejecuta las pruebas y al verlas fallar puedes proceder a arreglar el código; aunque parezca innecesario, de esta manera tienes una mayor garantía de que las pruebas realmente vigilen la calidad de tu código.

Terminamos

Con esto terminamos, durante este ejemplo he tratado de mostrarte un uso sencillo para los comandos en nuestra aplicación Laravel y hemos conocido algunas de las posibilidades que tenemos con este feature.

Puedes encontrar todo el código de la lección en este repositorio. Si te ha gustado este material por favor compártelo en tus redes sociales.

Suscríbete a nuestro boletín

Te enviaremos publicaciones con consejos útiles y múltiples recursos para que sigas aprendiendo.

Regístrate hoy en Styde y obtén acceso a todo nuestro contenido.