Tabla de contenido

Cuando empezamos a trabajar con Laravel para construir APIs, nos damos cuenta de que cargamos mucho más de lo que necesitamos: vistas, sesiones, autenticación de formularios… Para resolver esto, el equipo de Laravel creó Lumen.

¿Qué es Lumen?

Lumen es un micro-framework de PHP construido sobre los componentes de Laravel, diseñado específicamente para crear APIs REST y microservicios con alta velocidad y bajo consumo de recursos.

La idea es simple: tomas todos los componentes más valiosos de Laravel (routing, Eloquent ORM, validación, middleware) y eliminas todo lo que no necesitas en una API pura (vistas Blade, sesiones HTTP, CSRF protection, etc.). El resultado es un framework mucho más ligero y rápido.

Lumen vs Laravel: ¿cuándo usar cada uno?

LaravelLumen
Uso principalAplicaciones web completasAPIs y microservicios
Vistas✅ Blade templates❌ No incluidas
Sesiones✅ Incluidas❌ No por defecto
RendimientoBuenoExcelente
ConfiguraciónCompletaMínima
Curva de aprendizajeMediaBaja (si ya sabes Laravel)

Usa Laravel cuando:

  • Construyes una aplicación web con frontend incluido
  • Necesitas autenticación con sesiones, vistas, formularios
  • Usas herramientas como Livewire o Inertia

Usa Lumen cuando:

  • Solo necesitas una API REST
  • Construyes microservicios
  • La velocidad de respuesta es crítica
  • El equipo de frontend está separado (React, Vue, mobile)

Instalación de Lumen

Necesitas tener Composer instalado. Luego:

composer create-project --prefer-dist laravel/lumen mi-api
cd mi-api

Para correr el servidor de desarrollo:

php -S localhost:8000 -t public

O si instalas el Lumen Generator:

composer require flipbox/lumen-generator

Y en bootstrap/app.php agrega:

$app->register(Flipbox\LumenGenerator\LumenGeneratorServiceProvider::class);

Ahora puedes usar:

php artisan serve

Estructura de directorios

mi-api/
├── app/
│   ├── Http/
│   │   └── Controllers/      ← Controladores
│   └── Models/               ← Modelos Eloquent
├── bootstrap/
│   └── app.php               ← Configuración principal
├── config/                   ← Configuraciones (si las activas)
├── database/
│   └── migrations/           ← Migraciones
├── public/
│   └── index.php             ← Punto de entrada
├── routes/
│   └── web.php               ← Definición de rutas
└── .env                      ← Variables de entorno

Tu primera ruta en Lumen

Las rutas se definen en routes/web.php:

<?php

/** @var \Laravel\Lumen\Routing\Router $router */

// Ruta simple
$router->get('/', function () {
    return response()->json(['mensaje' => 'API Lumen funcionando']);
});

// Rutas de recursos
$router->get('/usuarios', 'UsuarioController@index');
$router->get('/usuarios/{id}', 'UsuarioController@show');
$router->post('/usuarios', 'UsuarioController@store');
$router->put('/usuarios/{id}', 'UsuarioController@update');
$router->delete('/usuarios/{id}', 'UsuarioController@destroy');

// Agrupando con prefijo y middleware
$router->group(['prefix' => 'api/v1', 'middleware' => 'auth'], function () use ($router) {
    $router->get('/perfil', 'PerfilController@show');
});

Respuestas JSON

Lumen hace muy sencillo devolver respuestas JSON:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\Usuario;

class UsuarioController extends Controller {
    
    // GET /usuarios
    public function index() {
        $usuarios = Usuario::all();
        return response()->json($usuarios, 200);
    }
    
    // GET /usuarios/{id}
    public function show($id) {
        $usuario = Usuario::find($id);
        
        if (!$usuario) {
            return response()->json([
                'error' => 'Usuario no encontrado'
            ], 404);
        }
        
        return response()->json($usuario, 200);
    }
    
    // POST /usuarios
    public function store(Request $request) {
        $this->validate($request, [
            'nombre' => 'required|string|max:100',
            'email'  => 'required|email|unique:usuarios',
        ]);
        
        $usuario = Usuario::create($request->all());
        
        return response()->json($usuario, 201);
    }
    
    // DELETE /usuarios/{id}
    public function destroy($id) {
        $usuario = Usuario::find($id);
        
        if (!$usuario) {
            return response()->json(['error' => 'No encontrado'], 404);
        }
        
        $usuario->delete();
        
        return response()->json(null, 204);
    }
}

¿Sigue siendo relevante Lumen en 2026?

Esta es una pregunta legítima. El equipo de Laravel anunció que Lumen ya no recibirá actualizaciones importantes y sugirió que para APIs modernas se use Laravel directamente (que también ha mejorado mucho en rendimiento para APIs).

Sin embargo, Lumen sigue siendo:

  • Una excelente herramienta de aprendizaje para entender micro-frameworks
  • Funcional y estable para proyectos existentes
  • Un buen punto de entrada si ya sabes Laravel

Si estás empezando un proyecto nuevo, considera usar Laravel API routes con artisan:api que ofrece la misma ligereza con el ecosistema completo de Laravel. Pero entender Lumen te da una base sólida para cualquier API en PHP.