# Structured Payloads Improve Extension-Point Legibility ## Claim A single typed payload object at an extension point is easier for another developer (or a static-analysis tool) to inspect than the same information spread across positional arguments and accepted-argument counts. <!-- atomicity: 1 idea ✓ --> ## Scope & conditions - Holds when the event class and the mutability of its properties are documented — the legibility gain comes from the payload being a named, typed thing, not just from being one object instead of many arguments. - Breaks when the object becomes an unbounded bag of loosely-typed mutable state; at that point it's re-creating the discoverability problem it was meant to solve, just inside one class instead of across several arguments. - Demonstrated in WordPress's proposed hook convention: `do_action()` already accepts an object argument, so the improvement is purely in payload design, not in the dispatcher. ## Evidence > [!quote] > Instead of passing loose arguments, pass one object that describes what happened. The underlying mechanism: field names, types, and which properties are read-only versus mutable all live in one class definition instead of being distributed across the firing call site, every callback signature, and each accepted-argument count declaration. ## Links - [[3. Resources/Literature Notes/Rethinking do_action() - Events as Objects, Hooks as Class Names]] — source literature note, §H2 - [[3. Resources/Permanent Notes/Public Event Names Outlive Their Implementation Structure]] — because extends: the payload-legibility gain and the hook-name-stability requirement are the two halves of the same event-object convention - [[3. Resources/MOCs/Open Source Governance MOC]] — applies-in: extension-point API design for any plugin ecosystem ## Tests / falsifiers - Compare completion accuracy, static-analysis coverage, or bug rate between a hook migrated to a typed event object and its previous positional-argument form — no measured improvement would weaken the claim to "plausible but unverified." - A production event class that accumulates enough loosely-typed mutable properties to become as hard to reason about as the positional arguments it replaced — would show the gain is contingent on discipline, not automatic from object-shape alone. ## Maintenance - Last tended: 2026-08-16 - Next review: 2026-11-16 ## Source - [[3. Resources/Readwise/Articles/Rethinking Do_action() Events as Objects, Hooks as Class Names]] — proposes the typed event-object convention for custom WordPress hooks.