Introduction to Server-Sent Events (SSE) in Laravel: Real-Time Notifications

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 () {
            // Disable PHP buffering to send data instantly
            if (ob_get_level() > 0) {
                ob_end_flush();
            }
            flush();

            // Simulate sending 10 notifications
            for ($i = 1; $i <= 10; $i++) {
                if (connection_aborted()) {
                    break;
                }

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

            // Notify client to close the connection cleanly
            echo $this->formatClosedEvent();
            flush();
        }, 200, $this->sseHeaders());
    }

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

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

    /**
     * Final event to close the connection without automatic reconnection.
     */
    public function formatClosedEvent(): string
    {
        return "event: closed\ndata: {\"message\":\"Stream finished\"}\n\n";
    }

    /**
     * SSE Headers: 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: unidirectional stream of real-time notifications
Route::get('/v1/events', [SSEController::class, 'stream']);

Note on connections

The route does not use auth:sanctum middleware so that it can be easily tested with a browser. In production, add authentication to secure the endpoint. Browser's EventSource automatically sends session cookies if the route is on the same domain.

<template>
  <div>
    <div>
      <h1>
        Live Notifications (SSE)
      </h1>

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

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

      <p v-if="isConnected">
        Connected to 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 manages automatic connection and reconnection
      this.eventSource = new EventSource('/api/v1/events')

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

      // Executes for each data: {JSON}\n\n
      this.eventSource.addEventListener('message', (event) => {
        this.messages.push(JSON.parse(event.data))
      })

      // Listen for custom server "closed" event
      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":"Notification #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' => 'Notification #2',
                ]);
        });

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

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

Run tests:

php artisan test --compact --filter=SSEControllerTest

# View first events (~6 seconds)
curl -sN --max-time 6 http://larafirststep.test/api/v1/events

# Expected output:
data: {"message":"Notification #1","time":"13:18:42"}

data: {"message":"Notification #2","time":"13:18:44"}


# View full 10 events + closure (~24 seconds)
curl -sN --max-time 24 http://larafirststep.test/api/v1/events | tail -3

# Last lines:
event: closed
data: {"message":"Stream finished"}

The -N flag

The -N flag (equivalent to --no-buffer) tells curl to output each line as it arrives, without waiting for full server buffering.

Scalability

If you need broadcasting to thousands of simultaneous clients, consider Laravel Reverb with WebSockets or services like Pusher. SSE is ideal for internal dashboards, admin notifications, or demos where concurrent volume is moderate.

 M  resources/js/vue/App.vue            ← "SSE" link in nav
 M  resources/js/vue/router.js          ← route /vue/sse
 M  routes/api.php                      ← GET /api/v1/events
??  app/Http/Controllers/Api/SSEController.php  ← SSE controller
??  resources/js/vue/componets/SSEComponent.vue ← Vue component
??  tests/Feature/SSEControllerTest.php         ← Pest tests (4)

Steps to Test

1. Ensure Vite is running: npm run dev
2. Open the app in your browser: http://larafirststep.test/vue/sse
3. Click Connect
4. Watch notifications arriving every 2 seconds
5. Upon completion (closed event), the connection closes automatically