Type Map Keeper

Skill: type-map-keeper

Use this skill when work touches:

• any TYPES constant array on a part or builder
• TYPE_* constants on channel, interaction, component, or embed families
• code that dispatches by type, component_type, or similar runtime discriminator
• attributeTypedCollectionHelper() or attributePartHelper() calls that consume a TYPES map
• ChannelBuilder::TYPES alias or equivalent builder-side mirrors

This is subtype-dispatch skill. Load it when a change adds, removes, or reorganizes how the codebase resolves a polymorphic Discord payload into a concrete PHP class.

Goal

Keep type maps as the single source of truth for polymorphic dispatch:

• one constant array decides which class represents each discriminator value
• all materialization sites consume that array instead of branching ad hoc
• builder-side mirrors stay aligned with inbound part maps
• fallback at index 0 handles unknown future values safely
• public TYPE_* constants remain stable vocabulary for userland

Read in this order

1. src/Discord/Parts/Channel/Channel.php — Channel::TYPES and TYPE_* constants, deprecated aliases
2. src/Discord/Parts/Interactions/Interaction.php — Interaction::TYPES and TYPE_* constants
3. src/Discord/Parts/Channel/Message/Embed/Embed.php — Embed::TYPES with string-keyed discriminators
4. src/Discord/Parts/Channel/Message/Component.php — inbound Component::TYPES map
5. src/Discord/Builders/Components/ComponentObject.php — outbound ComponentObject::TYPES and TYPE_* constants
6. src/Discord/Parts/PartTrait.php — attributeTypedCollectionHelper() at line ~530, createOf() at line ~429
7. src/Discord/Builders/ChannelBuilder.php — ChannelBuilder::TYPES = Channel::TYPES alias
8. Representative event handlers that dispatch through maps:
   • src/Discord/WebSockets/Events/ChannelCreate.php
   • src/Discord/WebSockets/Events/InteractionCreate.php
   • src/Discord/WebSockets/Events/ThreadListSync.php

Core contract

A TYPES constant is a public const array on the root class of a polymorphic family. Keys are discriminator values (integers or strings) sent by Discord in the type field. Values are fully-qualified class names of concrete subtypes. Index 0 (or equivalent) holds the root class itself as a safe fallback for unrecognized discriminator values.

All code that needs to turn a raw discriminator into a class must look up the map instead of writing its own switch/match/if chain. This keeps subtype knowledge centralized: add one map entry and every dispatch site picks it up automatically.

How type maps work

Map shape

public const TYPES = [
    0 => self::class,                       // fallback
    self::TYPE_PING => Ping::class,         // known subtypes
    self::TYPE_APPLICATION_COMMAND => ApplicationCommand::class,
    // ...
];

The discriminator field varies by family: type for channels, interactions, and embeds; type or component_type for components. The attributeTypedCollectionHelper() in PartTrait handles both via $part->type ?? $part->component_type ?? 0.

Dispatch expression

At every materialization site, the pattern is:

$class::TYPES[$data->type ?? 0]

This resolves to either a known concrete class or the fallback root class. Event handlers may add a secondary fallback with ?? Channel::class for families like channels that lack an explicit index 0 entry.

Known type map families

Component::TYPES and ComponentObject::TYPES are independent arrays that happen to share the same key space and constant names. They map to different class hierarchies — inbound parts vs outbound builders.

Materialization sites

Type maps are consumed in these code paths:

1. Gateway event handlers

Event classes call $this->factory->part(TYPES[$data->type] ?? Fallback::class, ...) to hydrate the correct subtype from raw gateway payloads.

• ChannelCreate, ChannelUpdate, ChannelDelete use ChannelBuilder::TYPES[$data->type] ?? Channel::class
• ThreadCreate, ThreadUpdate, ThreadDelete, ThreadListSync use the same channel map
• InteractionCreate uses Interaction::TYPES[$data->type ?? 0]

2. attributeTypedCollectionHelper() in PartTrait

Called by mutators like Message::getEmbedsAttribute() and Message::getComponentsAttribute() to build typed collections from raw payload arrays:

$part = $this->createOf($class::TYPES[$part->type ?? $part->component_type ?? 0], $part);

3. attributePartHelper() for single-object dispatch

Used by Section::getAccessoryAttribute(), Label::getComponentAttribute(), and Component::getComponentAttribute() to resolve a single nested object:

return $this->attributePartHelper('accessory', Component::TYPES[$this->attributes['accessory']->type ?? 0]);

4. Resolved data hydration

Resolved::getChannelsAttribute() uses ChannelBuilder::TYPES[$channel->type] ?? Channel::class to hydrate resolved channels from interaction payloads.

5. Builder alias forwarding

ChannelBuilder::TYPES = Channel::TYPES makes the builder a transparent proxy. Event handlers reference ChannelBuilder::TYPES so the builder layer can theoretically override mapping without changing the part, though today both are identical.

Adding a new subtype

Follow this sequence:

1. Add TYPE_* constant on the root class, matching the Discord API integer/string value.
2. Create the concrete class extending the root part (or sibling base). Keep it in the same namespace family.
3. Add the map entry in the root class TYPES array, keyed by the new constant.
4. Update event handlers — any gateway event that hydrates this family will automatically pick up the new entry if it reads TYPES. Verify the fallback expression still works.
5. Update builder-side mirror if one exists. For channels, ChannelBuilder::TYPES is an alias so it picks up changes automatically. For components, ComponentObject::TYPES must be updated independently.
6. Update typed collection helpers — if the new subtype appears in a collection context (embeds, components), confirm attributeTypedCollectionHelper() resolves it.
7. Add docblocks and @property annotations on parent parts if the subtype surfaces through typed collections.
8. Update $fillable and any subtype-specific mutators, repositories, or permission checks.
9. Preserve deprecated aliases if the new constant replaces an older name.