DiscordPHP Documentation

Optional local RPC client

Discord\RPC\IpcClient is an optional, low-level client for Discord's local IPC protocol. Construct and connect it explicitly in a CLI application. Creating a bot client does not start RPC, and RPC does not start a bot or connect to the Gateway. It uses the ReactPHP event loop and returns promises for asynchronous operations.

This foundation provides framing, a handshake, command correlation and raw event delivery. It does not provide typed command payload builders or typed RPC domain objects. RPC responses can differ from HTTP API objects; do not assume that a raw RPC response satisfies a DiscordPHP Part's contract.

Transport and platforms

On Unix-like systems, discovery considers discord-ipc-0 through discord-ipc-9 under each configured directory, in this order: XDG_RUNTIME_DIR , TMPDIR , TMP , TEMP , then /tmp . The default connector uses asynchronous Unix sockets.

Windows is unsupported by the default connector. Applications may inject a React\Socket\ConnectorInterface that asynchronously returns a React\Socket\ConnectionInterface for native paths such as \\?\pipe\discord-ipc-0 . An opt-in helper connector is described below. Deprecated RPC over WebSocket is outside this module. Path discovery and an injected stream fixture do not establish that the module works with an installed Discord client on any platform.

Optional Windows pipe helper

Discord\RPC\WindowsPipeConnector implements the existing connector contract without changing the RPC protocol. Install Node.js 22 or newer separately, then supply the absolute path to its trusted executable:

use Discord\RPC\IpcClient;
use Discord\RPC\WindowsPipeConnector;
use React\EventLoop\Loop;

$loop = Loop::get();
$connector = new WindowsPipeConnector('C:\\Program Files\\nodejs\\node.exe', $loop, 2.0);
$rpc = new IpcClient($loop, $connector);
// Register listeners, connect with your application ID, then run the loop.

The default remains unchanged. The helper accepts only local discord-ipc-0 through discord-ipc-9 pipe paths, including both \\?\pipe\ and \\.\pipe\ spellings. Discovery and fallback remain owned by IpcClient . Each attempted endpoint gets a new helper, ephemeral listener and random secret. The connector timeout (greater than zero, at most 300 seconds) covers helper startup and native connection; the client's connect_timeout still covers all discovery attempts and the READY handshake. Cancellation/close terminates the helper; reconnect never reuses its connection or replays requests. Keep the loop running briefly after close so process-exit polling can reap the helper. No automatic retries occur within the connector.

PHP's standard stream_select loop cannot watch Windows pipe handles safely. Changing a blocking pipe's mode does not supply overlapped completion handling. This prototype therefore delegates native I/O to Node's asynchronous libuv pipe transport, with stream piping for backpressure in both directions. PHP watches only a selectable TCP socket. Process creation itself is an OS spawn operation; there is no waiting on native pipe reads/writes or process exit in the loop. proc_close is called only after process termination has been observed.

The listener binds literal 127.0.0.1 on an OS-assigned port before the helper starts. The helper connects back and presents a fresh 256-bit secret before PHP returns the connection or sends any RPC bytes. Other peers are closed; at most eight pending peers are accepted during the bounded startup window. The helper has no TCP listener, cannot select a remote pipe or hostname, and never logs RPC payloads. The secret travels in a minimal child environment, never argv or a file; application environment and Node preload options are not inherited. Anonymous process pipes and shell command strings are not used.

This is a same-machine trust boundary: loopback TCP is unencrypted and does not protect against administrators, debuggers, packet capture with local privileges, or compromise of the PHP application, Node executable or Discord pipe server. It must never be port-forwarded, proxied or exposed on another interface. Close RPC explicitly during application shutdown. Node.js is optional and is never started unless this connector is explicitly injected; proc_open must be enabled in Windows CLI PHP.

Validation is split into three distinct levels:

  • Existing injected-stream tests validate protocol behavior with mocked transports.
  • Windows CI uses a synthetic Node native named-pipe server to exercise real pipe I/O, fragmented READY, command correlation, deadlines, cancellation, reconnect and a large binary backpressure exchange through the helper.
  • Live Discord desktop interoperability, OAuth eligibility and real commands require a separate manual run. No installed Discord client or OAuth credentials are assumed, and synthetic READY is not evidence of live interoperability.

Transport references: PHP stream_select limitations, Microsoft overlapped pipe I/O, and Node asynchronous IPC.

Connecting and sending commands

Create the client on the loop owned by your CLI application. Register listeners before connecting; the connection promise resolves only after READY .

use Discord\RPC\IpcClient;
use React\EventLoop\Loop;

$loop = Loop::get();
$rpc = new IpcClient($loop);
$rpc->on('dispatch', function (string $event, $data, array $raw) {
    // Handle a raw RPC dispatch; validate the event's data in your application.
});
$rpc->on('error', function (\Throwable $error) {
    // Record an operational error without logging tokens or authorization codes.
});

$rpc->connect('YOUR_NUMERIC_APPLICATION_ID')->then(
    function (IpcClient $rpc) {
        // IPC is ready; authorization and authentication are separate steps.
    },
    function (\Throwable $error) {
        // Connection or handshake failed.
    }
);
$loop->run();

After authenticating with the necessary scopes and eligibility, use request($command, $args, $event, $timeout) . It returns the complete raw response envelope, including cmd , nonce and data where present. The library supplies the nonce and correlates replies. The caller owns each command's arguments and response interpretation.

$rpc->request('GET_GUILD', ['guild_id' => $guildId])->then(
    function (array $response) {
        $guildData = $response['data'];
    }
);

$rpc->request('SUBSCRIBE', ['channel_id' => $channelId], 'MESSAGE_CREATE');
$rpc->request('UNSUBSCRIBE', ['channel_id' => $channelId], 'MESSAGE_CREATE');

SUBSCRIBE and UNSUBSCRIBE use the same command correlation mechanism. There is no local subscription registry or automatic subscription replay. Reconnect explicitly after a disconnect, then authenticate and restore any subscriptions your application still needs. Pending commands are rejected on disconnect. close() closes the session; sendPing($payload) sends a protocol ping and does not constitute a platform health check.

Authorization and confidential token exchange

authorize(['rpc', 'identify']) sends AUTHORIZE and returns its raw response. authenticate($accessToken) sends AUTHENTICATE . These helpers do not make an application eligible for restricted scopes. Discord documents approval and tester restrictions; verify access with Discord for your own app. A bot token is not an RPC OAuth2 access token.

authorizeAndAuthenticate($scopes, $redirectUri, $exchange, $timeout) chains authorization, an injected asynchronous token exchange, and authentication. Only one such flow may be active per client; concurrent flows reject. Call close() when finished to release the owned connection and deadlines. Implement Discord\RPC\TokenExchangeInterface :

public function exchange(
    string $code,
    string $clientId,
    string $redirectUri
): \React\Promise\PromiseInterface;

The promise must resolve to a nonempty access-token string. Host the confidential OAuth2 exchange securely in infrastructure you control. Never ship an application client secret in a distributed desktop client. This module does not implement the token endpoint, store tokens, refresh tokens, or ship a client secret. Your exchange implementation owns transport, server authentication, redirect validation and token handling. Keep authorization codes and access tokens out of logs.

API reference

All timeout values below are seconds.

new IpcClient(?LoopInterface $loop = null, ?ConnectorInterface $connector = null, array $options = []);
connect(string $clientId, int $version = 1): PromiseInterface;
request(string $command, array $args = [], ?string $event = null, float $timeout = 15): PromiseInterface;
authorize(array $scopes = ['rpc', 'identify'], float $timeout = 15): PromiseInterface;
authenticate(string $accessToken, float $timeout = 15): PromiseInterface;
authorizeAndAuthenticate(array $scopes, string $redirectUri, TokenExchangeInterface $exchange, float $timeout = 15): PromiseInterface;
close(): void;
sendPing(string $payload = ''): void;

Listeners receive ready (data, raw READY envelope), dispatch (event name, data, raw envelope), error (Throwable ), and close (nullable CloseException ). pong receives the payload bytes. READY and ERROR are handled by the lifecycle and error paths rather than ordinary dispatch notifications. Command failures reject the request promise; handle its rejection even when you have installed an error listener.

The constructor accepts these resource and scheduling options:

Option Default Meaning
paths IpcClient::getCandidatePaths() Ordered local Unix socket URIs or Discord native pipe paths.
connect_timeout 10.0 Overall connection and READY deadline in seconds.
max_frame_bytes 1048576 Maximum payload bytes per frame.
max_buffer_bytes 2097168 Maximum buffered incoming bytes; at least frame limit plus eight.
max_pending_requests 128 Maximum concurrent pending commands.
max_queue_bytes 4194304 Maximum buffered outgoing bytes.
frames_per_tick 32 Per-tick frame processing budget.

Unknown options and invalid limits are rejected. Request deadlines include queue time. Cancelling an unsent request removes it from the queue; cancelling a command already sent cannot undo its effect. The injected token exchange must support cancellation so a deadline or disconnect can abort pending exchange work. Use positive finite timeout values.

Coverage and verification boundaries

scripts/rpc-coverage.json inventories the documented command and event names. The audit dated 2026-10-20 counts 18 client commands and 25 events, plus the server DISPATCH envelope: 44 named entries. SELECT_TEXT_CHANNEL and ACTIVITY_INVITE are included. The inventory records raw envelope support, convenience helpers, absent typed wrappers, and fixture evidence separately. It is not a full-support percentage or an assertion that all commands work against Discord.

Offline stream fixtures can verify framing, handshakes, correlation, timeouts, disconnect behavior and dispatch forwarding. tests/RPC/IpcSocketTest.php also exercises the default connector and real event loop against a temporary local Unix socket server: path fallback, fragmented READY, binary PING/PONG, out-of-order replies and shutdown when READY never arrives. These tests skip where PHP has no Unix socket transport, including the Windows CI environment. They cannot prove compatibility with an installed Discord client, native Windows pipe support, user consent, app approval, scope eligibility, or command-specific behavior on Discord. No live authentication or live command integration is claimed.

Sources

The inventory was reconciled against the official references on 2026-10-20:

  • RPC for IPC, payloads, commands, events and authorization.
  • Opcodes and status codes for RPC errors and close codes. Error and close code namespaces are distinct.
  • OAuth2 scopes for scope names and approval restrictions.

The RPC RELATIONSHIP_UPDATE prose names relationships_read , while the OAuth2 scope table names relationships.read . The inventory preserves this source discrepancy; it does not silently infer which spelling the live RPC server accepts. New projects should also assess Discord's recommended Social SDK against their requirements.

Search results