Artisan: la interfaz de comandos de Laravel

Hola, ¿cómo están? Continuando con el curso de Laravel, hoy veremos Artisan, la herramienta de línea de comandos que trae el framework.

Es lo que más vas a usar después del editor, así que conviene conocerla bien desde el principio.

¡Empecemos!

Qué es Artisan

Artisan es un archivo ejecutable en la raíz de tu proyecto que da acceso a decenas de comandos: generar código, ejecutar migraciones, limpiar caché, arrancar el servidor y mucho más.

Para ver todo lo que puede hacer:

php artisan list

Y para saber cómo funciona un comando concreto:

php artisan help make:model

Ese help es más útil de lo que parece: muestra todas las opciones disponibles, y muchas veces la opción que necesitas ya existe.

Por qué usarlo en vez de crear archivos a mano

Podrías crear un controlador manualmente, escribiendo la clase y su espacio de nombres. Pero Artisan lo hace mejor:

• Lo pone en la carpeta correcta con el espacio de nombres correcto.
• Aplica las convenciones de nombres del framework.
• Genera el esqueleto con los métodos y las importaciones que corresponden.
• No se equivoca al escribir.

Y hay un beneficio menos obvio: al usar los generadores, tu proyecto queda organizado igual que cualquier otro proyecto Laravel. Quien llegue nuevo se orienta de inmediato.

Los comandos make

Son los que más vas a escribir. Generan las clases de tu aplicación.

php artisan make:model Paciente
php artisan make:controller PacienteController
php artisan make:migration create_pacientes_table
php artisan make:seeder PacienteSeeder
php artisan make:factory PacienteFactory
php artisan make:request GuardarPacienteRequest
php artisan make:middleware VerificarRol
php artisan make:command EnviarRecordatorios

Para ver la lista completa de generadores:

php artisan list make

El atajo que ahorra más tiempo

make:model acepta banderas para generar de una vez todo lo que suele acompañar a un modelo:

php artisan make:model Paciente -mfsc

Cada letra crea algo:

Bandera	Genera
-m	La migración
-f	El factory
-s	El seeder
-c	El controlador
-r	El controlador con métodos de recurso
--all	Todo lo anterior

En la práctica, --all es lo que vas a usar al crear una entidad nueva:

php artisan make:model Cita --all

Un comando, y tienes el modelo, su migración, su factory, su seeder, su controlador de recursos y sus form requests.

Comandos de base de datos

php artisan migrate                 # ejecuta las migraciones pendientes
php artisan migrate:status          # muestra cuáles se ejecutaron
php artisan migrate:rollback        # deshace el último lote
php artisan migrate:fresh           # borra todo y vuelve a migrar
php artisan migrate:fresh --seed    # además ejecuta los seeders
php artisan db:seed                 # solo los seeders

Un aviso serio sobre migrate:fresh: borra todas las tablas y sus datos. En tu máquina es cómodo; en producción es una catástrofe. Acostúmbrate a mirar dos veces en qué entorno estás antes de ejecutarlo.

Tinker: probar código sin escribir una pantalla

php artisan tinker

Abre una consola interactiva con toda tu aplicación cargada. Puedes ejecutar código y ver el resultado al instante:

>>> App\Models\Paciente::count()
>>> App\Models\Paciente::first()
>>> App\Models\Paciente::where('ciudad', 'Cochabamba')->get()

Es de las herramientas más útiles del framework para explorar datos y probar consultas antes de escribirlas en el código. Le dedicamos una lección completa más adelante.

Comandos de caché

Laravel guarda en caché la configuración, las rutas y las vistas para ir más rápido. Cuando algo no refleja tus cambios, casi siempre es eso:

php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clear
php artisan optimize:clear     # todo lo anterior de una vez

Y en producción, al revés, se cachea para ganar rendimiento:

php artisan optimize

Lo desarrollamos en la lección de limpiar la caché de Laravel, porque es uno de los problemas que más tiempo hace perder.

Comandos de inspección

Estos no generan nada: te dicen cómo está el proyecto.

php artisan about

Un resumen del entorno: versión de Laravel y de PHP, base de datos, caché, colas. Es lo primero que ejecuto al llegar a un proyecto ajeno.

php artisan route:list

Todas las rutas registradas, con su método, su URI, su nombre y qué controlador las atiende. Cuando una dirección devuelve 404, este comando te dice si la ruta existe realmente.

Se puede filtrar:

php artisan route:list --path=pacientes
php artisan route:list --method=POST

php artisan model:show Paciente

Muestra la tabla del modelo, sus columnas, sus relaciones y sus atributos. Muy útil en proyectos heredados.

Instalar funcionalidades

Algunos componentes no vienen de fábrica y se añaden con un comando:

php artisan install:api            # rutas de API y Sanctum
php artisan install:broadcasting   # canales de eventos en tiempo real

Como vimos en la lección de estructura, esto es coherente con el diseño actual del framework: nada que no uses.

Crear tus propios comandos

Aquí es donde Artisan deja de ser una herramienta del framework y pasa a ser tuya.

php artisan make:command EnviarRecordatorios

Se crea en app/Console/Commands/:

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use App\Models\Cita;

class EnviarRecordatorios extends Command
{
    protected $signature = 'citas:recordar {--dias=1}';

    protected $description = 'Envía recordatorios de las citas próximas';

    public function handle(): int
    {
        $dias = (int) $this->option('dias');

        $citas = Cita::where('estado', 'programada')
            ->whereDate('fecha', now()->addDays($dias))
            ->get();

        $this->info("Citas encontradas: {$citas->count()}");

        foreach ($citas as $cita) {
            // enviar el recordatorio
            $this->line("Recordatorio enviado a {$cita->paciente->nombre}");
        }

        return Command::SUCCESS;
    }
}

Y se ejecuta:

php artisan citas:recordar --dias=2

La propiedad $signature define el nombre y los argumentos. Los dos puntos agrupan comandos por tema: citas:recordar, citas:cancelar.

Dar información en pantalla

$this->info('Mensaje en verde');
$this->error('Mensaje en rojo');
$this->warn('Advertencia en amarillo');
$this->line('Texto normal');
$this->table(['Nombre', 'Fecha'], $filas);

Y para procesos largos, una barra de progreso:

$barra = $this->output->createProgressBar($citas->count());

foreach ($citas as $cita) {
    // ...
    $barra->advance();
}

$barra->finish();

Pedir datos al usuario

$nombre = $this->ask('¿Nombre del paciente?');
$clave = $this->secret('¿Contraseña?');

if ($this->confirm('¿Continuar?')) {
    // ...
}

$opcion = $this->choice('Estado', ['programada', 'atendida', 'cancelada']);

Comandos programados

Un comando propio cobra todo su sentido cuando se ejecuta solo. En routes/console.php:

Schedule::command('citas:recordar')->dailyAt('08:00');

Lo veremos en la lección de tareas programadas, en el módulo avanzado.

Los comandos que más vas a usar

Si tuviera que quedarme con siete:

php artisan serve                # levantar el servidor
php artisan make:model X --all   # crear una entidad completa
php artisan migrate              # aplicar migraciones
php artisan route:list           # ver las rutas
php artisan tinker               # probar código
php artisan optimize:clear       # limpiar toda la caché
php artisan about                # estado del proyecto

Errores comunes

• Crear archivos a mano en lugar de usar los generadores, y equivocarse en el espacio de nombres.
• Ejecutar migrate:fresh en producción.
• No limpiar la caché tras cambiar configuración, y perder media hora buscando un fallo que no existe.
• No conocer route:list y depurar un 404 a ciegas.
• Ignorar php artisan help, que suele tener la opción que estabas buscando.

Para cerrar

Artisan es el atajo permanente del framework. Casi todo lo que vas a necesitar crear tiene un generador, y usarlo garantiza que tu proyecto siga las convenciones que hacen a Laravel predecible.

Y el consejo que di en la primera lección aplica aquí especialmente: cuando un comando genere un archivo, ábrelo y léelo. Es la mejor forma de aprender qué está haciendo el framework por ti.

Con esto cerramos el módulo de fundamentos. En la siguiente lección empezamos con la base de datos.

Saludos y éxitos.