Helpers And Infra Keeper

Skill: helpers-and-infra-keeper

Use this skill when work touches src/Discord/Helpers/*, src/Discord/Exceptions/*, Endpoint::bind() patterns, or the external Collection / discord-php/http packages.

These are cross-cutting infrastructure utilities. They have no domain logic, but nearly every other layer depends on them.

Read in this order

1. src/Discord/Helpers/CacheWrapper.php — PSR-16 + React cache bridge
2. src/Discord/Helpers/CacheConfig.php — cache options (compression, sweep, TTL)
3. src/Discord/Helpers/LegacyCacheWrapper.php — fallback for older cache implementations
4. src/Discord/Helpers/BigInt.php — 32-bit PHP GMP polyfill for snowflake IDs and permission bitfields
5. src/Discord/Helpers/Multipart.php — multipart/form-data builder for file uploads
6. src/Discord/Repository/AbstractRepository.php — how repositories consume CacheWrapper and $endpoints
7. src/Discord/Discord.php — options['cache'] wiring to CacheWrapper/CacheConfig

Cache infrastructure

Three-class hierarchy

Rule: repositories do not interact with cache stores directly. They always go through CacheWrapper. Do not bypass it.

When to use CacheConfig

If a feature needs configurable cache behavior (TTL, compression, sweep interval), add it as a property on CacheConfig. Do not scatter cache tuning across individual repositories.

Cache coherence rule

When a REST write succeeds, the cache write must happen in the same promise chain — not after a refetch. This is enforced by convention, not framework. Break the chain and you get stale cache.

Endpoint::bind() — URL template pattern

All REST endpoints are defined as Endpoint constants in the external discord-php/http package:

use Discord\Http\Endpoint;

protected $endpoints = [
    'get'    => Endpoint::CHANNEL,
    'update' => Endpoint::CHANNEL,
    'delete' => Endpoint::CHANNEL,
];

Routes with parameters use :param placeholders. Binding happens via Endpoint::bind($endpoint, $params) where $params is a key-value map matching the placeholders.

Rule: never build URL strings by hand. Always use Endpoint::bind() or assign a named Endpoint constant. Raw string concatenation bypasses rate-limit bucket identification.

Finding endpoint constants

Browse vendor/discord-php/http/src/Endpoint.php for available constants. If a Discord API endpoint is missing, add it to the external package — do not define it inline in DiscordPHP source.

Checking against Discord's OpenAPI description

composer openapi (scripts/openapi-check.php) compares the library with the live preview of Discord's OpenAPI description. It lists the operations DiscordPHP never sends a request for, and routes with no Endpoint constant. It also lists what Discord has changed since the commit recorded in scripts/openapi-baseline.json: endpoints added or removed, parameters and responses, schema properties and enum values. It reads the library's source to see which request each constant is sent with. It recognises a repository's $endpoints table (all/get send GET, create POST, update PATCH, delete DELETE, and other keys whatever method sends $this->endpoints['key']), a direct call like ->post(Endpoint::bind(Endpoint::X, …)), or a variable assigned the endpoint and sent later in the same method. Keep new request code in one of those shapes, or the check will report the operation as unsent.

After implementing an operation, or deciding not to, run composer openapi:update and commit the baseline. Record the reason for every gap that remains in its unimplemented map. A daily workflow (.github/workflows/openapi.yml) runs the same check and opens an issue labelled openapi when it finds something new.

Collection base class

All repositories extend Collection from discord-php-helpers/collection. Key behaviors inherited:

• discriminator-keyed storage ($discrim — defaults to 'id')
• typed item enforcement ($class)
• get($key), has($key), first(), find(callable), filter(callable)
• JSON serialization

AbstractRepository adds REST/cache behavior on top. Do not re-implement collection operations in repositories — use the inherited helpers.