laravel-websockets/docs/advanced-usage/helpers-and-testing.md

---
title: Helpers and Testing
order: 2
---

# Helpers and Testing

This package is designed to be easy to use from both app code and test code.

## Global helpers

Global helpers live in `src/helpers_global.php` and call into the same core service used by the server.

### Broadcast to channel

```php
ws_broadcast('chat.message', ['text' => 'Hello world'], 'chat');
```

### Whisper to specific sockets

```php
ws_whisper('chat.typing', ['typing' => true], ['1234.1', '1234.2'], 'chat');
```

### Broadcast except sockets

```php
ws_broadcast_except('chat.message', ['text' => 'Server update'], ['1234.1'], 'chat');
```

### Runtime availability check

```php
if (ws_available()) {
    ws_broadcast('system.heartbeat', ['ok' => true]);
}
```

### Per-connection session store

`wsSession()` returns a Redis-backed key/value store scoped to the current WebSocket connection,
persisting across messages on the same socket. It takes **no arguments** and returns `null` outside
a WS message handler, so null-guard it.

```php
wsSession()?->increment('transmit_count');
$count = wsSession()?->get('transmit_count', 0);
wsSession()?->put('last_action', 'transmitted');
```

Available methods: `get`, `put`, `has`, `forget`, `all`, `replace`, `increment`, `save`, `flush`.

## WebsocketService class

If you prefer explicit classes over helpers:

```php
use BlaxSoftware\LaravelWebSockets\Services\WebsocketService;

WebsocketService::send('chat.message', ['text' => 'Hello'], 'chat');
WebsocketService::whisper('chat.typing', ['typing' => true], ['1234.1'], 'chat');
WebsocketService::broadcastExcept('chat.message', ['text' => 'Hi'], ['1234.1'], 'chat');
```

### Tracking helpers

`WebsocketService` also exposes lightweight in-process tracking helpers:

- `setUserAuthed($socketId, $user)`
- `clearUserAuthed($socketId)`
- `getAuth($socketId)`
- `getAuthedUsers()`
- `isUserConnected($userId)`
- `getUserSocketIds($userId)`
- `getActiveChannels()`
- `getChannelConnections($channel)`
- `resetAllTracking()`

## Testing with package helpers

The package test base class includes high-level helpers that make tests concise:

- `newConnection()`
- `newActiveConnection(['channel'])`
- `newPrivateConnection('private-channel')`
- `newPresenceConnection('presence-channel', ['user_id' => 1, 'user_info' => [...]])`

### Example ping/pong test

```php
$connection = $this->newActiveConnection(['websocket']);
$connection->resetEvents();

$this->wsHandler->onMessage($connection, new Message([
    'event' => 'websocket.ping',
    'data' => new stdClass(),
]));

$connection->assertSentEvent('websocket.pong');
```

### Example subscription test

```php
$connection = $this->newPrivateConnection('private-chat');
$connection->assertSentEvent('websocket_internal.subscription_succeeded');
```

## New reference test files

For complete examples, see:

- `tests/WebsocketServiceTest.php`
- `tests/HandlerLifecycleTest.php`

These files cover helper-first testing patterns and full handler lifecycle behavior.