The Flag primitive

Flag is a small readonly value object plus a PHP attribute. As an attribute it can be repeated on a method, function, or class, so a single handler can carry #[Flag('admin_only')] , #[Flag('chat_action', 'typing')] , and #[Flag('throttle', 0.5)] simultaneously. As a value object the same Flag instance ends up in the handler's $flags list at registration time. The dual role lets the same primitive serve both the declarative (#[Flag(...)] on the method) and imperative ($obs->register($cb, flags: [...]) ) styles. The attribute's #[Attribute(...IS_REPEATABLE...)] tagging is what makes "stack any number of flags" work; aiogram uses a dict[str, Any] because Python has no equivalent attribute mechanism.

Attaching flags at registration time

Both the attribute style and the imperative (array) style are available. The imperative flags: argument is the simpler option for closures, where PHP attributes cannot be applied:

use Gruven\PhpBotGram\Dispatcher\Dispatcher;
use Gruven\PhpBotGram\Dispatcher\Flags\Flag;
use Gruven\PhpBotGram\Types\Message;

$dispatcher = new Dispatcher();

// Imperative style: pass a flags array at registration time.
$dispatcher->message->register(
    static function (Message $event): void {
        $event->answer('hello')->emit();
    },
    flags: ['chat_action' => 'upload_photo'],
);

// Attribute style: annotate the handler function with #[Flag].
$dispatcher->message->register(
    #[Flag('admin_only')]
    static function (Message $event): void {
        $event->answer('admin only')->emit();
    },
);

Storage and lookup

Attribute-driven flags are read via PHP reflection. Imperative flags are stored in a process-wide FlagDecorator WeakMap keyed by the target closure or object. The weak-map trick exists because PHP cannot mutate arbitrary properties on a Closure — Python's cb.aiogram_flag = {...} translates to a side-table here. The weak-map evicts entries automatically when the closure is garbage-collected, so the storage is bounded by live handlers — there is no manual cleanup or registry maintenance needed even when the dispatcher rebuilds its handler graph (e.g. when a scene re-registers its method handlers).

Flags is the read API. Flags::extractFlags($target) returns both attachment styles concatenated (imperative first, then attribute-driven). Flags::getFlag($target, 'admin_only') returns the first match or null . Middlewares that read flags use these helpers — they never touch the WeakMap directly. The extractFlagsFromObject helper on the HandlerObject itself bakes the read into the dispatch hot path so a per-event lookup costs one getFlag call against a typically-small list.

Reading flags inside a middleware

The handler's resolved flags are available in $data['handler']->flags (an array<string, mixed> ) inside any inner middleware. A middleware that gates on admin_only would look like:

use Gruven\PhpBotGram\Dispatcher\Dispatcher;
use Gruven\PhpBotGram\Dispatcher\Event\HandlerObject;
use Gruven\PhpBotGram\Dispatcher\Middlewares\BaseMiddleware;

final class AdminGateMiddleware extends BaseMiddleware
{
    public function __invoke(\Closure $handler, object $event, array $data): mixed
    {
        $handlerObj = $data['handler'] ?? null;
        if (!$handlerObj instanceof HandlerObject) {
            return $handler($event, $data);
        }
        $flag = $handlerObj->flags['admin_only'] ?? null;
        if ($flag === true && !$this->isAdmin($event)) {
            return null; // short-circuit — do not invoke the handler
        }
        return $handler($event, $data);
    }

    private function isAdmin(object $event): bool
    {
        // your admin-check logic here
        return false;
    }
}

$dispatcher = new Dispatcher();
$dispatcher->message->innerMiddleware(new AdminGateMiddleware());

Framework-shipped flag-aware utilities

The framework ships two flag-aware utilities. CallbackAnswerMiddleware (in Utils/CallbackAnswer/ ) reads the callback_answer flag and auto-acknowledges the callback query before the handler runs, with the parameters from the flag's value shaping the acknowledgement text. ChatActionMiddleware (in Utils/ChatAction/ ) reads the chat_action flag and sends a chat_action API call that loops in the background until the handler returns — visible to the user as the "typing..." indicator during long-running operations. Both follow the same pattern: read the flag, optionally do prep work, delegate to the handler, then run cleanup.

The chat_action flag supports several forms. Absent means default 'typing' ; a string overrides the action; false opts the handler out entirely:

use Gruven\PhpBotGram\Dispatcher\Dispatcher;
use Gruven\PhpBotGram\Types\Message;
use Gruven\PhpBotGram\Utils\ChatAction\ChatActionMiddleware;

$dispatcher = new Dispatcher();
// Flag-aware middleware must be INNER — per-handler flags live on the
// HandlerObject ($data['handler']), which only inner middleware can see.
$dispatcher->message->innerMiddleware(new ChatActionMiddleware());

// Default: typing indicator sent automatically.
$dispatcher->message->register(static function (Message $event): void {
    $event->answer('hello')->emit();
});

// Custom action for a slow photo handler.
$dispatcher->message->register(
    static function (Message $event): void {
        $event->answer('photo coming')->emit();
    },
    flags: ['chat_action' => 'upload_photo'],
);

// Opt out entirely — no indicator for this handler.
$dispatcher->message->register(
    static function (Message $event): void {
        $event->answer('instant')->emit();
    },
    flags: ['chat_action' => false],
);

FlagGenerator is the helper that converts a flag list into a normalised form for inspection. The dispatcher does not use it on the hot path — it's exposed for tooling and tests that want to assert "this handler has exactly these flags". Production middlewares should use the Flags::getFlag shortcut instead.