Tinker en Laravel: probar código desde la terminal

Hola, ¿cómo están? Cerramos el módulo de base de datos con Tinker, una herramienta que probablemente vas a usar todos los días.

Es una consola interactiva donde puedes ejecutar cualquier código de tu aplicación y ver el resultado al instante, sin crear rutas ni vistas.

¡Empecemos!

Abrir Tinker

php artisan tinker

Verás algo así:

Psy Shell v0.12 (PHP 8.5 — cli)
>

Ya estás dentro de tu aplicación: modelos, configuración, base de datos y todos tus paquetes cargados.

Para salir, exit o Ctrl + D.

El problema que resuelve

Sin Tinker, probar una consulta implica: crear una ruta, escribir un controlador, hacer un dd(), recargar el navegador, y borrar todo cuando terminas.

Con Tinker escribes la consulta y ves el resultado.

>>> App\Models\Paciente::count()
= 50

>>> App\Models\Paciente::first()
= App\Models\Paciente {#5234
    id: 1,
    cedula: "1234567",
    nombre: "Ana",
    apellido: "Torres",
  }

Esa diferencia, multiplicada por las veces que pruebas algo al día, es mucho tiempo.

Consultas Eloquent

Todo lo que vimos en la lección de Eloquent funciona aquí:

>>> use App\Models\Paciente;

>>> Paciente::all()
>>> Paciente::find(3)
>>> Paciente::where('ciudad', 'Cochabamba')->get()
>>> Paciente::latest()->take(5)->get()
>>> Paciente::pluck('nombre')

Ese use al inicio te ahorra escribir el espacio de nombres completo en cada línea. Se mantiene durante toda la sesión.

Un consejo para no ahogarte en salida: si la tabla tiene miles de registros, Paciente::all() va a llenar la pantalla. Usa ->take(5) o ->pluck() para ver solo lo necesario.

Crear y modificar datos

>>> Paciente::create([
...   'cedula' => '9876543',
...   'nombre' => 'Carlos',
...   'apellido' => 'Mendoza',
...   'fecha_nacimiento' => '1988-04-12',
... ])

>>> $p = Paciente::find(1)
>>> $p->telefono = '76980510'
>>> $p->save()

Las variables se conservan mientras la sesión esté abierta, así que puedes trabajar por pasos.

Y combinado con los factories, poblar la base para una prueba rápida es inmediato:

>>> Paciente::factory()->count(10)->create()

Y aquí una advertencia importante: Tinker escribe de verdad en la base de datos configurada en tu .env. Un Paciente::truncate() ejecutado sin pensar borra la tabla. Antes de escribir algo destructivo, confirma en qué entorno estás:

>>> app()->environment()
= "local"

Probar relaciones

Es de los usos donde más se aprecia:

>>> $paciente = Paciente::with('citas')->first()
>>> $paciente->citas
>>> $paciente->citas->count()
>>> $paciente->citas->first()->doctor->nombre

Si una relación no está bien declarada, el error aparece aquí en dos segundos en lugar de en una pantalla a medio construir.

Ver el SQL que se genera

Muy útil para entender qué hace Eloquent por debajo:

>>> Paciente::where('activo', true)->orderBy('apellido')->toSql()
= "select * from `pacientes` where `activo` = ? order by `apellido` asc"

Y con los valores incluidos:

>>> Paciente::where('ciudad', 'Cochabamba')->toRawSql()

Es la forma más rápida de comprobar si tu consulta está haciendo lo que crees.

Más allá de los modelos

Tinker ejecuta cualquier código de tu aplicación:

>>> config('app.name')
>>> config('database.default')

>>> now()
>>> now()->addDays(30)->format('d/m/Y')

>>> Str::slug('Consulta de Cardiología')
= "consulta-de-cardiologia"

>>> Hash::make('secreto')

>>> Storage::disk('public')->files()

>>> collect([3, 1, 2])->sort()->values()->all()

Incluso puedes probar tus propias clases:

>>> $servicio = new App\Services\CalculadoraDeCostos()
>>> $servicio->calcular(250, 0.10)

Es la mejor forma de verificar una clase antes de conectarla a un controlador.

Comandos útiles dentro de Tinker

>>> help              // lista de comandos disponibles
>>> ls                // variables definidas en la sesión
>>> doc Str::slug     // documentación de un método
>>> show App\Models\Paciente   // el código fuente de la clase
>>> clear             // limpiar la pantalla
>>> exit

doc y show son sorprendentemente prácticos: te muestran la firma o el código sin salir de la terminal ni abrir el navegador.

Ejecutar una sola línea sin abrir la consola

php artisan tinker --execute="echo App\Models\Paciente::count();"

Útil en scripts o para comprobar algo rápido en un servidor.

Tinker en producción

Se puede, y a veces hace falta para diagnosticar algo. Pero con criterio:

• Consulta antes de modificar. Mira qué vas a afectar con un ->get() antes de escribir un ->update().
• Nada de truncate(), delete() masivo ni migrate:fresh.
• Recuerda que no hay deshacer. No existe un Ctrl + Z en la base de datos.

Si tienes que hacer una modificación masiva, envuélvela en una transacción como vimos en el curso de MySQL:

>>> DB::beginTransaction()
>>> Cita::where('fecha', '<', now())->update(['estado' => 'cancelada'])
= 47
>>> DB::rollBack()   // o DB::commit() si el número cuadra

Ese número te dice cuántas filas afectaste antes de confirmar. Es la red de seguridad.

Limitaciones

Para tener expectativas realistas:

No hay contexto HTTP. No existe una petición ni una sesión, así que cosas que dependen de request() o del usuario autenticado no funcionan igual.

Los cambios en el código requieren reiniciar. Si modificas un modelo mientras Tinker está abierto, la sesión sigue con la versión vieja. Sal y vuelve a entrar.

No es cómodo para código largo. Escribir un bloque de veinte líneas en la consola es incómodo. Para eso, mejor un comando de Artisan.

Tinker o Laravel Gohu

Si seguiste el curso de Laravel Gohu, reconocerás el parecido: ambos ejecutan consultas y muestran el resultado.

La diferencia está en el formato y el entorno. Tinker vive en la terminal y devuelve objetos de PHP; Gohu vive dentro de Visual Studio Code, muestra el resultado en JSON con el conteo de registros y el tiempo de ejecución, y no obliga a salir del editor.

Para explorar rápido, Tinker. Para comparar consultas y ver cuánto tarda cada una, Gohu.

Errores comunes

• Olvidar el espacio de nombres completo, o el use al inicio.
• Ejecutar all() sobre tablas enormes y llenar la terminal.
• Modificar datos en producción sin comprobar antes.
• Esperar que refleje cambios de código sin reiniciar la sesión.
• No comprobar el entorno antes de escribir algo destructivo.

Para cerrar

Tinker es el laboratorio de tu aplicación: el sitio donde probar una consulta, verificar una relación o comprobar qué devuelve una función, sin montar nada alrededor.

El hábito que recomiendo: antes de escribir una consulta en un controlador, pruébala en Tinker. Si funciona ahí, funciona en el código.

Con esto cerramos el módulo de base de datos. En la siguiente lección profundizamos en las consultas de Eloquent.

Saludos y éxitos.