Tema 9 · Archivos & Storage

9. Subida de Archivos y Multimedia en APIs: multipart/form-data y Storage

Recibe avatares o documentos con validaciones de tipo MIME y peso máximo, almacenándolos con el disco public o Amazon S3 y devolviendo URLs públicas.

Subida de Archivos en Peticiones de API

Cuando un cliente necesita adjuntar una imagen de producto, un avatar de usuario o un documento PDF a la API, no puede enviar un payload application/json convencional. La petición debe codificarse como multipart/form-data.

Validación de Archivos con la Regla File

Laravel incluye un objeto de validación robusto Illuminate\Validation\Rules\File que permite verificar dimensiones de imágenes, extensiones permitidas y tamaño máximo en kilobytes:

'avatar' => [
    'required',
    File::image()
        ->types(['jpg', 'jpeg', 'png', 'webp'])
        ->max(2 * 1024), // Máximo 2 MB
],

Almacenamiento con Storage::disk('public')

Nunca guardes archivos directamente en la carpeta public/. Utiliza la abstracción de discos de Laravel:

  • Los archivos se guardan en storage/app/public/avatares.
  • Se ejecuta el enlace simbólico php artisan storage:link.
  • En el API Resource devuelves la URL pública generada con Storage::url($ruta).

⚡ Controlador API para Subir Imagen y Retornar URL Pública

Ejemplo completo de subida de imagen de producto con Storage y Resource:

AvatarUploadController.php
Solo lectura
<?php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Storage;
use Illuminate\Validation\Rules\File;

class AvatarUploadController extends Controller
{
    /**
     * POST /api/v1/perfil/avatar (multipart/form-data)
     */
    public function subirAvatar(Request $request): JsonResponse
    {
        $request->validate([
            'avatar' => [
                'required',
                File::image()
                    ->types(['jpg', 'png', 'webp'])
                    ->max(2048), // 2MB
            ],
        ]);

        $usuario = $request->user();

        // 1. Eliminar avatar previo si existía para no acumular basura en el VPS
        if ($usuario->avatar_path && Storage::disk('public')->exists($usuario->avatar_path)) {
            Storage::disk('public')->delete($usuario->avatar_path);
        }

        // 2. Guardar el nuevo archivo con nombre aleatorio único en storage/app/public/avatares
        $ruta = $request->file('avatar')->store('avatares', 'public');

        // 3. Actualizar el registro del usuario
        $usuario->update(['avatar_path' => $ruta]);

        // 4. Retornar URL pública absoluta
        return response()->json([
            'status'     => 'success',
            'mensaje'    => 'Avatar actualizado exitosamente',
            'avatar_url' => Storage::disk('public')->url($ruta),
        ], 200);
    }
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué comando de Artisan es necesario ejecutar una vez para que los archivos guardados en el disco "public" sean accesibles públicamente desde la web?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar APIs RESTful con Laravel, Resources & Sanctum y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.