phpbotgram

Same traversal order (depth-first, registration order) and same router => $this injection. Matches upstream emit_shutdown (router.py:295).

Injects router => $this into the kwargs bag so handlers can declare Router $router and receive the emitting router at each level — not the root. Matches upstream emit_startup (router.py:282).

Forwarded kwargs include the workflow_data and the bots[array_key_last] injection from the polling driver (spec § "Polling loop"). Lifecycle handlers are pub/sub: every handler runs; the first throw aborts the rest (matches EventObserver).

Mirrors upstream feed_raw_update (dispatcher.py:186-195). The Serializer::load call binds the bot context to the Update tree (every nested TelegramObject sees $bot via its ?Bot $bot constructor parameter), parity with upstream's Update.model_validate(..., context={"bot": bot}).

Kwargs precedence (last-wins on key collision):

1. $this->workflowData — dispatcher-scoped defaults
2. $kwargs — caller-supplied per-call overrides
3. injected event_update (always the resolved Update) and bot (always the bot argument). These two are dispatcher invariants and cannot be overridden by callers.

The Bot::setCurrent binding is wrapped in try/finally so the slot is cleared even if the dispatch raises — without that guard a handler exception would leave the binding pointing at the now-irrelevant bot for the next dispatch on the same fiber.

Middleware wiring (C1 fix): the dispatcher-level chain (UserContextMiddleware + ErrorsMiddleware) wraps the terminal propagateEvent call exactly once. Prior to the fix the chain was attached to every observer at construction, which meant propagateEvent's sub-router recursion re-wrapped each child observer's trigger() with the same chain — doubling resolveContext() runs and duplicating error handling. Wrapping once at the ingress mirrors upstream's self.update.wrap_outer_middleware shape (dispatcher.py:164-172).

Two branches:

• In-time: the chain completes within WEBHOOK_TIMEOUT_SECONDS. If the result is a TelegramMethod, return it so the caller (the webhook HTTP adapter) can encode it as the response body. Any other return value (string, sentinel, null) collapses to null — the adapter then writes an empty JSON }.
• Deadline expired: the chain has NOT completed by the time the 55-second timer fires. We emit trigger_error("Detected slow response into webhook…", E_USER_WARNING) (parity with upstream's warnings.warn(..., RuntimeWarning) at dispatcher.py:462-468), attach a continuation that routes any eventual TelegramMethod through silentCallRequest (so the side effect still reaches Telegram via a normal API call), and return null immediately so the webhook adapter doesn't keep the HTTP socket open past the deadline.

Update|array overload (Fix I3): the $update parameter accepts either an already-deserialised Update instance or a wire-shaped associative array (the typical HTTP body decoded via json_decode($body, true)). The array form hydrates via Serializer::load(Update::class, ...) before the dispatch runs — mirrors upstream's dispatcher.py:443-444 overload.

Implementation notes:

• The race is implemented via Amp\Future\awaitFirst against an async(fn() => $this->feedUpdate(...)) task and an async(delay) timer. Upstream uses loop.call_later + loop.create_future to model the same primitive; awaitFirst is the canonical amphp v3 equivalent and reads cleaner than spinning a manual DeferredFuture.
• We deliberately do NOT use Amp\TimeoutCancellation here: cancellation would interrupt the dispatch fiber, but the spec requires the dispatch to continue running in the background so the fall-through continuation can route any eventual TelegramMethod. The race-with-a-timer pattern preserves the in-flight fiber.
• The timer task uses ignore() so a never-awaited timeout future (the happy path where the dispatch wins) doesn't surface an "unhandled future" warning at GC time.
• The dispatch task's map() callback is attached after the race resolves. amphp guarantees the callback fires on completion even if the future is already complete — but in the timeout branch the dispatch is still in flight at attachment time. The callback runs on the same event loop driver that's hosting the dispatch fiber, so no cross-thread synchronisation is needed.

1. Self-attachment — a router cannot include itself. Upstream raises RuntimeError; we use LogicException because PHP doesn't have a Runtime/Logic distinction this fine, and "you wired your router tree wrong" is unambiguously a programming bug.
2. Re-parenting — once a router has a parent it stays put. The alternative (detach + re-attach) would silently leave the old parent's subRouters array holding a dangling reference.
3. Cycles — A→B→C→A would make propagateEvent infinitely recurse. We walk our own ancestor chain (parentRouter upward) and confirm the candidate isn't already in it.

Returns the included router so callers can chain fluent registrations: $root->includeRouter($child)->message->register(...). Matches upstream include_router(...) -> Router.

Each is validated independently; the first failure throws and already-attached siblings stay attached (matches upstream's for router in routers: self.include_router semantics — no transaction).

Returns $this for fluent chaining at the parent (note: upstream's include_routers returns None; the port returns the parent so users can write (new Dispatcher())->includeRouters(...)->runPolling(...)).

Implementation is a Generator (PHP generators are Fiber-safe under Revolt). Each iteration calls getUpdates(timeout: pollingTimeout) inside a try/catch. On success the backoff is reset, every returned Update is yielded to the caller, and offset advances by updateId + 1 (Telegram's confirm-by-incrementing-offset protocol).

Retry semantics on failure mirror upstream:

• TelegramRetryAfter: sleep for the exact retryAfter seconds the API advertised, then retry without consulting the backoff. This is the explicit flood-wait contract — backoff growth would be wrong.
• RestartingTelegram / TelegramNetworkException: route through Backoff::asleep() so concurrent bots don't retry in lockstep.
• Any other Throwable is re-raised — it's a bug at the dispatch layer, not a transient API hiccup. Upstream catches everything; the port narrows the catch because a typed dispatch path is in scope here (TelegramApiException hierarchy), and ErrorsMiddleware will already have unwound user-level errors before they reach this loop.

Loop termination: between rounds we inspect $stopSignal->isComplete(). Inside a Telegram long-poll the loop is parked in the HTTP transport (or in delay() during a retry sleep). The signal fires the fiber that called stopPolling; the polling fiber notices on its next round.

Three modes (collapsed from upstream's handle_as_tasks bool + tasks_concurrency_limit int|None pair):

• handleAsTasks === null => serial. Each feedUpdate runs inline; the next Update is consumed only after the previous handler returns.
• handleAsTasks === int n => concurrent with LocalSemaphore of size n. Each Update spawns a fiber that acquires the semaphore, runs feedUpdate, and releases on completion.

Spawned fibers are tracked in $this->handleUpdateTasks keyed by spl_object_id so a future Future::cancel pass on shutdown (added in the spec but not exposed by amphp v3's Future directly) can reap them. The keyed map is also opportunistically purged each round so a long-running polling session doesn't accumulate completed-future references.

Handler exceptions are not caught here — ErrorsMiddleware (wired onto every observer at Dispatcher construction) already does the catch and either invokes the error observer or re-raises. A truly uncaught exception will surface to the awaiter of the spawned fiber's Future or, in serial mode, terminate the polling loop. The latter matches upstream's _process_update semantics, where the Exception logger swallows everything inside the inner try.

Intended for Scene::asRouter(); exposed as a tiny fluent method so tests and custom scene wiring can opt into the same traversal rule.

Contract:

1. Inject event_router => $this into the kwargs bag so handlers and middlewares can see which router is currently dispatching (router.py:153). The inner-most claiming router is the value handlers see — each recursion overwrites the kwarg.
2. Look up the observer; throw LogicException on an unknown update type. Upstream silently returns UNHANDLED for unknown keys; the port is strict because our observer map is schema-derived and a missing key is unambiguously a bug (typo'd literal, stale code after a Phase 2 regen, …).
3. Compose the local observer's outer middleware ONCE around an inner closure that runs the local observer's raw trigger() AND, on UNHANDLED, the depth-first sub-router walk. This is the Fix I2 shape — the parent observer's outer middleware covers sub-router handlers too. Mirrors upstream Router.propagate_event (router.py:152-166) which wraps _wrapped (containing the sub-router walk inside _propagate_event) with observer.wrap_outer_middleware(...).
4. Non-UNHANDLED return short-circuits and is returned verbatim — including null, false, TelegramMethod instances, etc.

Middleware integration: outer middleware on a router observer wraps the entire local dispatch plus the sub-router walk. The Dispatcher subclass wires UserContextMiddleware / ErrorsMiddleware at the feedUpdate ingress layer (above propagateEvent), so those middlewares run once per ingress regardless of where the claiming handler lives. Per-observer outer middleware registered via $observer->outerMiddleware(...) runs once per propagateEvent call on the owning router (so a parent's outer middleware wraps a child router's claiming handler too).

$event is typed object (not TelegramObject) because the same propagation primitive carries synthetic dispatcher events such as ErrorEvent, which deliberately do not extend TelegramObject.

Used by the polling driver to compute allowed_updates for getUpdates — Telegram only sends updates of types the bot cares about, so this minimizes bandwidth. Matches upstream resolve_used_update_types exactly:

• Excludes the error channel (and the meta update type) regardless of handlers — they're internal, not wire types.
• Honors $skipEvents for caller-driven filtering on top of the internal exclusion.
• Walks the full sub-router subtree (depth-first), de-duped via associative-array keys (PHP's set substitute).

Upstream returns a sorted list; the port returns the keys in walk order so the result is deterministic per tree shape. Callers that need sorting can sort($result) themselves.

Signal handling is best-effort: EventLoop::onSignal requires the pcntl extension at minimum, and may throw UnsupportedFeatureException on Windows or in PHP builds without pcntl. We swallow the throw silently — parity with upstream's with suppress(NotImplementedError): block.

Public instance method (deviation from upstream's @classmethod) so tests can override it via RecordingDispatcher to capture the fall-through invocations without driving a real network call. Upstream's unittest.mock.patch of a class method does not translate cleanly to PHP. See spec § "Webhook response contract" for the rationale.

Return type deviation from spec: the port returns mixed, not void. Upstream's silent_call_request returns whatever await bot(result) resolves to (the TelegramMethod's ReturnsType), so a typed mixed is faithful to upstream — the spec's void was incorrect. Subclasses such as RecordingDispatcher lean on the mixed to return a sentinel (null) without driving the real bot call.

TelegramApiException handling: a transient API failure from the underlying call (chat gone, message already deleted, bot blocked, etc.) MUST NOT kill the caller. In serial polling the next update is unrelated and the loop should keep going; on the webhook fall-through path the request lifecycle is already over and the failure has nowhere to surface. We mirror upstream's silent_call_request (aiogram/dispatcher/dispatcher.py:294-301) which catches TelegramAPIError and logs — the port emits an E_USER_WARNING (the project-wide RuntimeWarning analogue, see also Fix C2 / Fix I1) and returns null. Any non-API throwable (programming errors, fiber-level failures) still propagates so the upstream layers / ErrorsMiddleware can react.

The spec mandates (PollingOptions $options, Bot ...$bots) order because PHP forbids any parameter following a variadic — the mission brief's (Bot $bot, ..., Bot ...$additionalBots) shape would also trigger a "Variadic parameter must be the last parameter" parse error.

Concurrency contract:

1. The $runningLock mutex serialises the isPolling check / set so a second concurrent startPolling call sees the flag and raises LogicException. Mirrors upstream async with self._running_lock: at dispatcher.py:558.
2. emitStartup and emitShutdown are called once each, around the fan-out, with bots => $bots injected per spec § "Polling loop". The shutdown closes every bot's session as a final cleanup step.
3. Per-bot polling fibers are spawned via Amp\async; the returned Future awaits all of them (success or first error).

Fix I3: contract mirrors upstream's stop_polling at dispatcher.py:497-509:

• Never started: no startPolling has been seen on this Dispatcher ($hasEverStarted === false). We raise RuntimeException("Polling is not started") — parity with upstream's if not self._running_lock.locked(): raise RuntimeError("Polling is not started").
• Active polling: $stopSignal is present. We complete it (if not already complete — multi-stop is idempotent) and then await $drainedSignal outside the lock so the caller observes a fully-drained dispatcher on return.
• Already cleanly stopped: $hasEverStarted === true && $drainedSignal === null — the dispatcher ran a polling round to completion before. We return silently (no throw, no await), parity with upstream's if not self._stop_signal or not self._stopped_signal: return at dispatcher.py:506-507.

Inside the polling fiber: calling stopPolling from a handler is supported via the $insidePollingFiber FiberLocal flag — the drain await is skipped, so the call completes the stop signal synchronously and returns immediately. The polling fiber's post-yield check then unwinds the loop. Without the flag the call would deadlock (the drain only completes when the polling fiber exits, but the polling fiber would be parked here).

The mutex round-trip is the canonical way to read/mutate the $stopSignal slot without a torn read between concurrent fibers (e.g. a SIGTERM handler firing while a user-level stopPolling call is mid-flight). The drain await happens OUTSIDE the lock so a stop fiber doesn't deadlock against the awaiter's finally block (which itself acquires the lock to reset state).

Mirrors upstream Dispatcher.storage property (dispatcher.py:108).