DiscordPHP Agent Guide

This file is the repo operating manual for AI agents. It describes how to work inside this repository without breaking its design. Specialist skills in .agents/skills/ provide deeper playbooks for specific layers.

If a change crosses layers, load multiple skills and use the playbooks in this file to keep boundaries clean.

Start here

Before changing anything:

1. Identify the layer you are touching.
2. Read the base abstraction for that layer before copying a concrete class.
3. Read one representative concrete implementation from the same family.
4. Trace how that layer connects to adjacent layers.
5. Make the change in the narrowest layer that can own it.
6. Update companion surfaces that define the same contract.

In this repo, companion surfaces usually matter as much as the line you edit.

Non-negotiable truths

1. CLI-only runtime. DiscordPHP is a long-running process built on ReactPHP. Do not design around web requests, controllers, middleware stacks, or per-request state.
2. Async first. Production I/O is Promise-based. Blocking helpers belong in tests only.
3. Parts are canonical domain objects. They model Discord resources and expose typed magic properties.
4. Repositories are persistence and cache boundaries. They are not generic service classes.
5. Gateway handlers keep caches coherent. They do more than relay notifications.
6. Builders own outbound payload rules. If a payload has meaningful shape or validation, it usually deserves a builder.
7. Docblocks are runtime-adjacent documentation. They are not optional decoration.
8. Traits are preferred over deep inheritance or broad interface hierarchies for shared behavior.
9. Type maps are central dispatch points. If a Discord payload is polymorphic, there is usually one place that decides the concrete subtype.
10. Use current library idioms. Prefer Factory::part() / Factory::repository(), prefer $part->save($reason) over repository save($part) in user-facing paths, and prefer builder ->create($repository) helpers where they exist.

Skill map

For Compatibility Watch findings, Discord API/schema drift, or an issue labelled openapi, read the compatibility handoff. Reuse the existing OpenAPI check and issue; retain source/spec revisions and prove affected runtime behavior separately from schema coverage. Do not accept a baseline merely to silence a new finding.

Each skill lives in .agents/skills/<name>/SKILL.md and is loaded automatically when relevant. When a task crosses layers, load multiple skills.

Architecture map

External packages

Three external packages are tightly coupled to core runtime behavior. Treat them as first-class parts of the architecture:

When editing endpoint bindings, REST routes, cache storage, or voice audio, you are necessarily touching these packages' contracts.

Repo worldview

Runtime to domain flow

Discord owns bootstrapping. Gateway dispatch goes through Handlers into a dedicated event class. Event classes translate payloads into typed parts and update repositories. Repositories provide cache and REST persistence. Parts expose that state through magic properties and typed helpers. Builders assemble outbound payloads for operations that would otherwise become fragile arrays.

Why the split matters

• If you put transport logic in parts, parts stop being stable domain objects.
• If you put domain validation in repositories, repository APIs stop being predictable.
• If you skip builders, payload rules spread across unrelated methods.
• If gateway handlers do not update caches correctly, every downstream relation becomes stale.

Common class patterns

Parts

Expect these elements on real resource models:

• large class-level @property and @property-read docblocks
• protected $fillable = [...]
• optional protected $repositories = [...]
• constants mirroring Discord enums or flags
• getXAttribute() and setXAttribute() mutators
• overrides for getCreatableAttributes(), getUpdatableAttributes(), getRepository(), save(), fetch(), or getRepositoryAttributes() when the part is persistable

Semantic rules:

• raw attribute names stay snake_case to match Discord payloads
• convenience relations (guild, channel, owner, member) are usually computed, not directly stored
• nested typed data should become a Part, typed collection, or Carbon value through helper methods
• permission checks for high-level mutations belong on the part before repository delegation
• created tells you whether the object already exists remotely
• a payload that is an existing part's object plus a few fields gets a subclass of that part, which merges only its extra keys into the inherited $fillable
• a subclass's override declares the narrowest return type it can truly return (PHP return types are covariant), and every path must honour it. For example, GameDirectMessage::getChannelAttribute() returns Channel where Message's returns Part, because a game DM's channel can never be a Thread
• inherited methods that can never work in a subclass's context return a rejected promise (\BadMethodCallException) instead of sending a request Discord will refuse. See part-model-maintainer for all three
• parts live under the namespace of the API route they come from: a message, its attachments, reactions and embeds are under Parts\Channel\Message because they come from /channels/{channel.id}/messages. A part that moves keeps its old name working through a class_alias() at the end of src/Discord/functions.php, which Composer loads eagerly, so instanceof, type hints and cached (serialised) data with the old name still work

Repositories

Expect these elements:

• extends AbstractRepository
• protected $class = SomePart::class
• protected $endpoints = [...]
• optional constructor normalization for route vars
• occasional domain-specific convenience methods

Semantic rules:

• repositories are typed collections plus REST/cache wrappers
• create() builds a local part; save() persists it
• $vars carries parent route context like guild_id or channel_id
• cache writes must stay aligned with REST writes and gateway updates
• special methods should still return typed parts or repositories, not loose payloads

Builders

Expect these elements:

• extends Builder
• implements JsonSerializable
• fluent setX() / getX() methods
• eager validation in setters or adders
• new() factory method on most builders
• create($repository) helper on newer builders

Semantic rules:

• builders are not parts and should not own persistence or cache logic
• validation belongs here when it describes outgoing payload shape
• jsonSerialize() should omit unset optionals when Discord distinguishes missing from explicit null
• fromPart() should make edit flows symmetrical

Gateway events

Expect these elements:

• one class per event type under src/Discord/WebSockets/Events
• matching constant in src/Discord/WebSockets/Event.php
• matching registration in src/Discord/WebSockets/Handlers.php
• handle($data) method returning typed semantic values

Semantic rules:

• event handlers should hydrate the right subtype on first read
• event handlers are responsible for repository/cache coherence
• update events often return both new and old state
• delete events often return cached removed state, not only the raw payload id
• related user/member caches usually need updating too

Cross-layer rules

1. Parts delegate persistence; repositories own REST

If a part can be saved:

• the part decides whether the action is allowed and which repository owns it
• the repository decides how to call Discord and update cache

Smell: a part method manually building endpoints and PATCH payloads when a repository already exists for that family.

2. Parts own semantics; builders own payload ergonomics

If userland needs to construct a non-trivial outbound payload:

• add or extend a builder
• keep raw-array construction as an implementation detail only when a builder would be needless overhead

Smell: multiple methods assembling the same nested array by hand.

3. Gateway events own reactive cache updates

If Discord can tell us something through gateway dispatch:

• prefer updating cache from the event instead of forcing later REST refetches
• keep parent/child repository relationships coherent at the same time

Smell: event handler creates a part but does not update the repository that should own it.

4. Traits carry horizontal behavior

The codebase prefers traits for shared capabilities across sibling models.

Examples:

• PartTrait for universal part mechanics
• ChannelTrait for channel/thread behavior
• GuildTrait for guild asset and feature helpers
• DynamicPropertyMutatorTrait for builder/property mutators (src/Discord/Helpers/DynamicPropertyMutatorTrait.php)
• AbstractRepositoryTrait for repository collection mechanics
• ComponentsTrait for shared component helpers across builders (src/Discord/Builders/ComponentsTrait.php)
• VoiceGroupCryptoTrait for voice channel encryption/decryption

Smell: new abstract intermediate base class that only exists to share a few methods between peers that already have a common root.

5. Type maps beat repeated branching

When a Discord discriminator chooses a subtype:

• extend the relevant TYPES map
• update all materialization sites that depend on that family

Smell: one event handler special-cases a new subtype but the central type map still does not know it.

Common companion surfaces

If you touch one of these, inspect the companions too:

Change playbooks

Playbook: editing a Part

1. Update $fillable.
2. Add or adjust mutators for typed nested data, computed properties, or normalization.
3. Update class docblocks.
4. Update $repositories if a new child repository is exposed.
5. Update getRepositoryAttributes() if child route vars changed.
6. Update getCreatableAttributes() / getUpdatableAttributes() if persistence shape changed.
7. Update getRepository() or save() if ownership or permission rules changed.
8. Check gateway events and repositories that hydrate or cache the part.
9. Add or update tests.

Playbook: editing a Repository

1. Confirm $class, $discrim, and $endpoints still describe the family correctly.
2. Confirm parent route vars are complete and in the correct shape.
3. Keep REST writes and cache writes in sync.
4. Return typed values.
5. Check owning parts for getRepository() and getRepositoryAttributes() assumptions.
6. Update tests and docs if public behavior changed.

Playbook: editing a Builder

1. Put payload validation in setters/adders.
2. Keep fluent chaining style.
3. Keep jsonSerialize() aligned with Discord docs and existing payload semantics.
4. Keep fromPart() edit symmetry in mind.
5. Update tests for validation limits and payload shape.
6. Update docs/examples if the preferred public construction path changed.

Playbook: editing a gateway event

1. Add or update the event constant in Event.php if needed.
2. Add or update the handler registration in Handlers.php.
3. Hydrate the correct subtype.
4. Update every affected repository and relation cache.
5. Preserve event return shape expected by userland listeners.
6. Cache related users/members if the payload supplies them.
7. Re-check any intent-gated or partial-data behavior.

Playbook: editing interactions or commands

1. Keep application-command and prefix-command layers separate.
2. Keep interaction typing and resolved-data hydration intact.
3. Keep builders as the outbound authoring path for commands, components, and modals.
4. Avoid slow interaction-time work that can delay a response.
5. Update both inbound event handling and outbound builder/docs surfaces if public behavior shifts.

Design tripwires

If you see one of these, slow down:

• a new raw nested array where a typed part already exists
• a repository method returning raw decoded payload instead of a part
• a part saving itself with hand-built endpoints even though an owning repository exists
• a new subtype without a TYPES map entry
• a magic property added in code but not in docblocks
• a gateway handler that updates one cache but leaves related repositories stale
• a synchronous wait or loop-stop trick outside tests
• a new abstraction layer that duplicates what parts, repositories, events, or builders already do
• web-framework terminology creeping into core runtime code
• extending OldVoiceClient or any Old* class in src/Discord/Voice/ unless deliberately fixing legacy behavior
• bypassing Endpoint::bind() with hand-assembled raw URL strings

Preferred reference files

When you need an example worth imitating, start here:

• Runtime orchestration: src/Discord/Discord.php
• Base part mechanics: src/Discord/Parts/Part.php, src/Discord/Parts/PartTrait.php
• Rich part model: src/Discord/Parts/Guild/Guild.php
• Channel/resource semantics: src/Discord/Parts/Channel/Channel.php
• Message semantics and repository binding: src/Discord/Parts/Channel/Message/Message.php
• Repository baseline: src/Discord/Repository/AbstractRepository.php, src/Discord/Repository/AbstractRepositoryTrait.php
• Simple repo specialization: src/Discord/Repository/Channel/MessageRepository.php
• Rich repo specialization: src/Discord/Repository/GuildRepository.php
• Outbound builder style: src/Discord/Builders/MessageBuilder.php
• Interaction typing: src/Discord/Parts/Interactions/Interaction.php
• Gateway cache mutation: src/Discord/WebSockets/Events/MessageCreate.php, src/Discord/WebSockets/Events/GuildCreate.php
• Optional command layer: src/Discord/DiscordCommandClient.php, src/Discord/CommandClient/Command.php
• Cache infrastructure: src/Discord/Helpers/CacheWrapper.php, src/Discord/Helpers/CacheConfig.php
• Voice protocol and encryption: src/Discord/Voice/VoiceGroupCrypto.php, src/Discord/Voice/VoicePacket.php

Testing and docs workflow

Tests

• All unit-test classes extend DiscordTestCase.
• Use $this->getMockBuilder() for isolated class dependencies and getMockDiscord() when a lightweight real Discord client is needed.
• Use and return wait() from tests/functions.php whenever a test performs asynchronous work so PHPUnit tracks it.
• Keep semantic tests focused on behavior, not on incidental implementation details.
• When a test requires a live Discord or MessageCommandClient instance (for example, to exercise registration, event handling, or runtime integration), obtain it via the wait(function (Discord $discord, $resolve) { ... }) pattern and return that wait() call. Use $this->getMockBuilder() for isolated class dependencies and getMockDiscord() when a lightweight real client is needed without network access.

Docs

• Public magic properties, repositories, and helpers should be reflected in PHPDoc.
• Long-form guides live in guide/.
• Gatsby docs live in docs/.
• Keep docs in sync when preferred usage or public contracts change.

Useful commands

Integration tests expect .env values for DISCORD_TOKEN, TEST_CHANNEL, and TEST_CHANNEL_NAME. Without DISCORD_TOKEN the suite runs offline: tests that answer requests with getMockHttpDriver() run, and only those that call $this->channel() skip. .github/workflows/tests.yml runs it that way on every push and pull request; unit.yml runs it live, by hand.

Final rule

When unsure where code belongs, choose the layer that already owns the same kind of knowledge elsewhere in the repo. Matching the existing ownership model matters more than shaving a few lines off one class.