Introducción a Server-Sent Events (SSE) en Laravel: Notificaciones en Tiempo Real

SSE vs WebSockets

┌────────────┐       GET /api/v1/events        ┌────────────────┐
│            │ ───────────────────────────────▶ │                │
│            │                                  │    Laravel     │
│   Vue 3    │   HTTP 200                       │  (PHP Worker)  │
│  Browser   │ ◀── Content-Type: text/event-... │                │
│            │                                  │                │
│            │   data: {"msg":"Notif #1"}\n\n   │  sleep(2) × 10 │
│            │   data: {"msg":"Notif #2"}\n\n   │                │
│  EventSource  data: {"msg":"Notif #3"}\n\n   │  → event:      │
│  .onmessage   ...                            │    closed       │
│            │   event: closed\n\n               │                │
│            │ ──── connection.close() ──────▶ │  flush()       │
└────────────┘                                  └────────────────┘

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\StreamedResponse;

class SSEController extends Controller
{
    public function stream(): StreamedResponse
    {
        return response()->stream(function () {
            // Desactivar el buffering de PHP para enviar datos al instante
            if (ob_get_level() > 0) {
                ob_end_flush();
            }
            flush();

            // Simulamos envío de 10 notificaciones
            for ($i = 1; $i <= 10; $i++) {
                if (connection_aborted()) {
                    break;
                }

                echo $this->formatEvent($i);
                flush();
                sleep(2);
            }

            // Avisamos al cliente para que cierre la conexión limpiamente
            echo $this->formatClosedEvent();
            flush();
        }, 200, $this->sseHeaders());
    }

    /**
     * Formato obligatorio de SSE: data: {JSON}\n\n
     */
    public function formatEvent(int $iteration): string
    {
        $data = json_encode([
            'message' => "Notificación #{$iteration}",
            'time'    => now()->toTimeString(),
        ], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);

        return "data: {$data}\n\n";
    }

    /**
     * Evento final para cerrar la conexión sin reconexión automática.
     */
    public function formatClosedEvent(): string
    {
        return "event: closed\ndata: {\"message\":\"Stream finalizado\"}\n\n";
    }

    /**
     * Cabeceras SSE: no-cache, keep-alive, Nginx buffering off.
     */
    public function sseHeaders(): array
    {
        return [
            'Cache-Control'         => 'no-cache',
            'Content-Type'          => 'text/event-stream; charset=utf-8',
            'Connection'            => 'keep-alive',
            'X-Accel-Buffering'     => 'no',
        ];
    }
}

<?php

use App\Http\Controllers\Api\SSEController;

// Server-Sent Events: flujo unidireccional de notificaciones en tiempo real
Route::get('/v1/events', [SSEController::class, 'stream']);

Nota sobre conexiones

La ruta no usa middleware auth:sanctum para poder probarla fácilmente con un navegador. En producción, añadir autenticación para proteger el endpoint. El EventSource del navegador envía cookies de sesión automáticamente si la ruta está en el mismo dominio.

<template>
  <div>
    <div>
      <h1>
        Notificaciones en vivo (SSE)
      </h1>

      <div>
        <o-button
          v-if="!isConnected"
          iconLeft="play"
          variant="success"
          @click="connect"
        >Conectar</o-button>

        <o-button
          v-else
          iconLeft="stop"
          variant="danger"
          @click="disconnect"
        >Desconectar</o-button>
      </div>

      <p v-if="isConnected">
        Conectado al stream...
      </p>

      <ul v-if="messages.length > 0">
        <li
          v-for="(msg, index) in messages"
          :key="index"
        >
          <strong>[{{ msg.time }}]:</strong> {{ msg.message }}
        </li>
      </ul>
    </div>
  </div>
</template>

<script>
export default {
  data() {
    return {
      messages: [],
      eventSource: null,
      isConnected: false,
    }
  },

  beforeUnmount() {
    this.disconnect()
  },

  methods: {
    connect() {
      // EventSource gestiona la conexión y reconexión automática
      this.eventSource = new EventSource('/api/v1/events')

      this.eventSource.addEventListener('open', () => {
        this.isConnected = true
      })

      // Se ejecuta por cada data: {JSON}\n\n
      this.eventSource.addEventListener('message', (event) => {
        this.messages.push(JSON.parse(event.data))
      })

      // Escuchar evento custom "closed" del servidor
      this.eventSource.addEventListener('closed', () => {
        this.disconnect()
      })

      this.eventSource.addEventListener('error', () => {
        if (this.eventSource.readyState === 2) {
          this.isConnected = false
        }
      })
    },

    disconnect() {
      if (this.eventSource) {
        this.eventSource.close()
        this.eventSource = null
        this.isConnected = false
      }
    },
  },
}
</script>

<?php

use App\Http\Controllers\Api\SSEController;

describe('SSEController', function () {
    describe('stream', function () {

        it('returns an SSE response with the correct headers', function () {
            $response = $this->get('/api/v1/events');

            $response->assertOk();
            expect($response->headers->get('Cache-Control'))
                ->toContain('no-cache');
            $response->assertHeader(
                'Content-Type',
                'text/event-stream; charset=utf-8'
            );
            $response->assertHeader('Connection', 'keep-alive');
            $response->assertHeader('X-Accel-Buffering', 'no');
        });

        it('streams events in the SSE format', function () {
            $controller = new SSEController;

            $event = $controller->formatEvent(1);

            expect($event)
                ->toMatch('/^data: \{"message":"Notificación #1",/')
                ->toEndWith("\n\n");
        });

        it('encodes JSON without escaping accents', function () {
            $controller = new SSEController;

            $json = trim(substr(
                $controller->formatEvent(2),
                strlen('data: ')
            ));

            expect(json_decode($json, true))
                ->toMatchArray([
                    'message' => 'Notificación #2',
                ]);
        });

        it('formats the closing event with the closed name', function () {
            $controller = new SSEController;

            expect($controller->formatClosedEvent())
                ->toStartWith('event: closed')
                ->toContain('"message":"Stream finalizado"');
        });
    });
});

Ejecutar los tests:

php artisan test --compact --filter=SSEControllerTest

# Ver los primeros eventos (~6 segundos)
curl -sN --max-time 6 http://larafirststep.test/api/v1/events

# Salida esperada:
data: {"message":"Notificación #1","time":"13:18:42"}

data: {"message":"Notificación #2","time":"13:18:44"}


# Ver los 10 eventos completos + el cierre (~24 segundos)
curl -sN --max-time 24 http://larafirststep.test/api/v1/events | tail -3

# Últimas líneas:
event: closed
data: {"message":"Stream finalizado"}

El flag -N

El flag -N (equivalente a --no-buffer) le dice a curl que muestre cada línea a medida que llega, sin esperar al buffer completo del servidor.

Escalabilidad

Si necesitas broadcasting a miles de clientes simultáneos, considera Laravel Reverb con WebSockets o servicios como Pusher. SSE es ideal para dashboards internos, notificaciones de admin o demos donde el volumen concurrente es moderado.

 M  resources/js/vue/App.vue           ← enlace "SSE" en el nav
 M  resources/js/vue/router.js          ← ruta /vue/sse
 M  routes/api.php                      ← GET /api/v1/events
??  app/Http/Controllers/Api/SSEController.php  ← controlador SSE
??  resources/js/vue/componets/SSEComponent.vue ← componente Vue
??  tests/Feature/SSEControllerTest.php         ← tests Pest (4)

Pasos para probar

1. Asegurarse de que Vite esté corriendo: npm run dev
2. Abrir la app en el navegador: http://larafirststep.test/vue/sse
3. Hacer clic en Conectar
4. Ver las notificaciones llegando cada 2 segundos
5. Al finalizar (evento closed), la conexión se cierra automáticamente