Runtime Bootstrap Keeper

Skill: runtime-bootstrap-keeper

Use this skill when work touches src/Discord/Discord.php, startup options, loop setup, cache configuration, gateway connection behavior, readiness, member chunking, reconnect logic, or root repositories.

This is not generic PHP skill. This is the orchestrator-lifecycle guard. Load it when changing how the client boots, what dependencies it wires, how it connects to Discord's gateway, or how it reaches the ready state.

Goal

Keep Discord as the single bootstrapping orchestrator:

• resolves all user-facing options centrally through OptionsResolver
• wires infrastructural dependencies once during construction
• connects to the gateway eagerly from the constructor
• delegates loop start to a one-liner run() method
• maintains lifecycle flags that the rest of the system depends on
• owns root repositories as long-lived properties on the Client part
• manages the ready flow: guild backfill → member chunking → init emission

Read in this order

1. src/Discord/Discord.php — the entire orchestrator
2. src/Discord/WebSockets/Handlers.php — handler registry for gateway events
3. src/Discord/WebSockets/Event.php — event constant definitions
4. src/Discord/Factory/Factory.php — part/repository factory, created once here
5. src/Discord/Parts/User/Client.php — the Client part that holds root repos
6. README.md — public-facing construction examples
7. guide/basics.rst — user-facing lifecycle guide

Do not start by reading individual event classes. Understand the wiring in Discord.php first, then follow references outward.

Core contract

Discord is the application entry point. It is not a service class, not a controller, not a request handler. It is a long-running CLI process orchestrator built on ReactPHP. The entire class rests on these guarantees:

• __construct() does real work: resolves options, creates HTTP client, creates Factory, creates Client part, registers handlers, and calls connectWs() to open the gateway
• run() only starts the ReactPHP event loop — it must stay a one-liner
• the class assumes CLI SAPI — a web-server warning is logged if php_sapi_name() is not cli or micro
• Factory is created exactly once and shared across the entire system
• root repositories (guilds, users, private_channels, emojis, sounds, sticker_packs, lobbies) live on the Client part, proxied through Discord::__get()

If a change violates any of these, the runtime becomes unpredictable.

Options and intent resolution

All user-facing configuration is resolved in resolveOptions() using Symfony's OptionsResolver. This is the single normalization point for the entire client.

Key options

Intent folding

If intents is passed as an array of intent constants, resolveOptions() folds them into a single bitmask with bitwise OR. This happens once at resolution time — the rest of the system sees only the integer.

If loadAllMembers is enabled, the resolver enforces that GUILD_MEMBERS intent is included, throwing IntentException otherwise.

Cache normalization

The cache option normalizer converts bare CacheInterface or CacheConfig values into the canonical [AbstractRepository::class => $config] array shape. The default null value means LegacyCacheWrapper (in-memory) is used. External cache backends are treated as experimental and logged as warnings.

Construction vs run() lifecycle

What __construct() does (in order)

1. Validates x86 GMP extension requirement
2. Calls resolveOptions() — all normalization and validation happens here
3. Stores $token, $loop, $logger, $cacheConfig, $collectionClass
4. Checks CLI SAPI — logs critical warning if web context detected
5. Creates SocketConnector and Connector (WebSocket factory)
6. Creates Handlers instance — the gateway event handler registry
7. Warns if critical events (GUILD_CREATE, GUILD_DELETE, RESUMED, READY, GUILD_MEMBERS_CHUNK) are in disabledEvents
8. Removes disabled event handlers from registry
9. Creates Http client with React driver
10. Creates Factory — the single part/repository factory for the system
11. Creates Client part via factory — this is where root repositories are born
12. Stores compression settings
13. Calls connectWs() — initiates the gateway connection

What run() does

public function run(): void
{
    $this->loop->run();
}

Nothing else. The loop was already wired during construction. run() simply unblocks the event loop. Do not add bootstrap logic here.

Why this matters

The eager constructor means the system is fully wired before run() is called. User code that registers event listeners between new Discord(...) and $discord->run() works because the loop has not started yet but all infrastructure is ready. Moving connection logic to run() would break this contract.

Gateway connection and reconnection

connectWs()

Retrieves the gateway URL via setGateway(), then opens a WebSocket connection through $this->wsFactory. On success, calls handleWsConnection(). On failure, calls handleWsConnectionFailed() which retries after 5 seconds.

setGateway() calls the REST endpoint Endpoint::GATEWAY_BOT to get the gateway URL and session start limit. The URL is decorated with v, encoding, and optional compress=zlib-stream query parameters in buildParams(). If a resume_gateway_url was received from a prior READY, that is used instead.

handleWsConnection()

Sets $this->connected = true, initializes the payload rate counter (120/60s limit with 5 reserved for heartbeats), and registers message, close, and error listeners on the WebSocket.

handleWsClose()

Cancels heartbeat and payload timers. If $this->closing is true, returns silently. If the close code is a critical op code (checked via Op::getCriticalCloseCodes()), does not reconnect. Otherwise, sets $reconnecting = true and calls connectWs() after a 2-second delay.

handleHello()

Received when the gateway connection is established. Calls setupHeartbeat() with the server-provided interval, then calls identify().

identify() vs resume()

identify() sends OP_IDENTIFY with token, properties, intents, shard info, and presence. resume() sends OP_RESUME with token, session ID, and last sequence number. The gateway decides which path to use after reconnection via handleInvalidSession().

handleInvalidSession()

If the session is resumable ($data->d is true), attempts resume(). Otherwise, calls identify() after a 2-second delay.

Heartbeat

setupHeartbeat() creates a periodic timer at the server-specified interval. Each heartbeat() call sends OP_HEARTBEAT with the current sequence number and starts a guard timer. If no HEARTBEAT_ACK arrives within one heartbeat interval, the connection is closed with code 1001, triggering reconnect.

Ready flow

The ready sequence is the most delicate part of the bootstrap. It ensures all guilds are loaded and optionally chunked before userland code runs.

Step 1: handleReady()

Receives the READY payload. If $this->reconnecting is true, it skips full re-parsing and just emits reconnected. Otherwise:

1. Stores resume_gateway_url for future reconnects
2. Fills the Client part with user data and stores sessionId
3. Iterates content->guilds and processes each through GuildCreate::handle()
4. Tracks unavailable guilds

If all guilds are immediately available, calls ready() directly. Otherwise, sets up temporary GUILD_CREATE and GUILD_DELETE listeners to track when unavailable guilds become available. A 60-second safety timer also triggers ready() as fallback.

Step 2: setupChunking()

Called when all guilds are available. If loadAllMembers is false, calls ready() immediately. Otherwise, starts a periodic 5-second timer that calls checkForChunks().

Step 3: checkForChunks()

Drains the $largeGuilds array in batches of 50, sending OP_REQUEST_GUILD_MEMBERS for each. Guilds are added to $largeGuilds by addLargeGuild(), which is called from GuildCreate event handling. If loadAllMembers is an array of guild IDs, only those guilds are chunked.