WebSockets
debt(d8/e7/b7/t7)
Closest to 'silent in production until users hit it' (d9), adjusted down to d8. The detection_hints field explicitly states 'automated: no' and the code pattern is a semantic/architectural choice (using polling instead of WebSockets, or using WebSockets when SSE suffices). No listed tools can catch this — it only surfaces when performance degrades or security incidents (unauthenticated upgrades) occur in production under real load.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix mentions adopting Ratchet or ReactPHP plus implementing heartbeat, reconnection, and connection handling. The common_mistakes reveal multiple systemic issues: auth on upgrade requests, shared-state for horizontal scaling (Redis pub/sub integration), client reconnection logic, and targeted broadcast patterns. These span server infrastructure, client code, and deployment topology — clearly cross-cutting.
Closest to 'strong gravitational pull' (b7). WebSockets impose persistent architectural decisions: stateful server processes (or a shared-state layer like Redis), load balancer configuration for sticky sessions or pub/sub, client reconnection logic, authentication on upgrade, and payload management. Every subsequent change to the real-time feature surface is shaped by the WebSocket connection model. Applies to web context broadly.
Closest to 'serious trap — contradicts how a similar concept works elsewhere' (t7). The misconception field explicitly states the core trap: developers assume WebSockets are the universal solution for all real-time features, when SSE is simpler and sufficient for one-way server-push. Additionally, common_mistakes show that stateless HTTP assumptions (no persistent auth, no shared memory concerns) don't carry over — horizontal scaling and connection state are fundamentally different from standard HTTP request handling.
Also Known As
TL;DR
Explanation
WebSockets upgrade an HTTP connection to a persistent bidirectional channel — either side can push messages any time with minimal framing overhead. Ideal for: live dashboards, chat, collaborative editing, real-time game state, and push notifications. Traditional PHP (synchronous, request-per-process) is poorly suited to maintaining thousands of long-lived connections. Use a dedicated WebSocket server: Ratchet (PHP/ReactPHP), Swoole, or RoadRunner for PHP-native solutions. A common practical pattern: a lightweight Node.js or Go WebSocket server handles connections and publishes events via Redis Pub/Sub, while PHP handles business logic through standard HTTP endpoints.
Common Misconception
Why It Matters
Common Mistakes
- Not authenticating the WebSocket upgrade request — anyone can connect without credentials.
- Storing WebSocket connection state in memory on one server — horizontal scaling requires a shared state layer (Redis pub/sub).
- Not handling connection drops and reconnection logic on the client — connections drop; clients must reconnect.
- Broadcasting large payloads to all connections — use targeted pub/sub, not broadcast to all.
Code Examples
// WebSocket server with no authentication:
$server->on('open', function(Connection $conn): void {
// No auth check — any client can connect and receive all messages
$this->clients->attach($conn);
});
// Should verify a token in the upgrade request headers or first message// PHP WebSocket server with Ratchet
use Ratchet\MessageComponentInterface;
use Ratchet\ConnectionInterface;
class ChatServer implements MessageComponentInterface {
private \SplObjectStorage $clients;
public function __construct() { $this->clients = new \SplObjectStorage(); }
public function onOpen(ConnectionInterface $conn): void {
$this->clients->attach($conn);
}
public function onMessage(ConnectionInterface $from, $msg): void {
foreach ($this->clients as $client) {
if ($client !== $from) $client->send($msg); // broadcast
}
}
public function onClose(ConnectionInterface $conn): void {
$this->clients->detach($conn);
}
public function onError(ConnectionInterface $conn, \Exception $e): void {
$conn->close();
}
}
// Start server: php bin/chat-server.php
// Client JS: const ws = new WebSocket('ws://yourapp.com:8080');