feat(middleware)!: guard a component the way a command is guarded

[mikield]

Middleware landed for commands in #21. A button could not use it, so the check stayed at the top of the handler — and "may this person do this" is one question whether it arrives as a subcommand or as the button that does the same thing.

#[Button(id: 'petition.accept.{petition}', middleware: [ModerationOnly::class])]
public function accept(ButtonInteraction $button, string $petition): void
{
    // reached only by moderation; the status check that is actually
    // domain logic stays here
}

#[Button], #[SelectMenu] and #[ModalSubmit] now take middleware, compiled and validated by the same rule the command path uses — the validator moved into DeclaredMiddleware so a button and a subcommand are held to the same rule and refused in the same words.

ComponentDispatcher runs the chain before resolving arguments, and hands the middleware the interaction in the shape that kind of component is answered with — ButtonInteraction, ComponentInteraction, ModalSubmitInteraction. It builds that itself rather than taking it from the handler's arguments: a guard has to be able to refuse even when the handler it guards never asked for an interaction at all.

Middleware runs before the handler, so nothing has been deferred yet and a refusal answers with an ordinary ephemeral reply. The defer() stays in the handler, where the slow work is.

Breaking

Middleware::__invoke takes a union now:

public function __invoke(
    CommandInteraction|ButtonInteraction|ComponentInteraction|ModalSubmitInteraction $interaction,
    callable $next,
): void;

A middleware written against 0.14 widens its parameter and nothing else changes — the interaction it receives for a command is the same object as before.

A union rather than a shared interface is a deliberate trade: the four interaction classes have no common ancestor, and giving them one means changing discord-php too. Worth revisiting if the union grows.

Docs

tools/guides/09-middleware.md, with every example pulled from a fixture the suite compiles and exercises — including SuggestionCommand, the mixed-audience case that is the whole reason this exists, and a test asserting the guard lands on one subcommand and not the other.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MQ51VhJ8GmnJdfHrj6Mz7D

[github-actions]

🎉 This PR is included in version 1.0.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀