advanced-map.md

Advanced documentation map

Use this index when you need to customize internals: custom middleware, adapters, queue providers, tooling, or diagnostics.

Configuration and infrastructure

• Manual configuration without yiisoft/config — wiring queues, workers, and middleware factories without yiisoft/config.
• Queue provider registry — selecting and extending adapter factories.
• Loops and worker processes — implementing custom runners, heartbeat hooks, and graceful shutdown (requires pcntl).
• Worker — resolving worker dependencies and starting workers.
• Performance tuning — profiling handlers, envelopes, and adapters.

Middleware, envelopes, and handlers

• Middleware pipelines deep dive — dispatcher lifecycle, request mutations, and per-pipeline contracts.
• Callable definitions and middleware factories — container-aware definitions for middleware factories.
• Error handling internals — failure pipeline flow, built-in components, and custom middleware.
• Envelope metadata and stack reconstruction — stack resolution and metadata merging.
• Handler resolver pipeline — alternative handler lookup strategies.

Queue adapters and interoperability

• Custom queue provider implementations — bespoke selection logic, tenant registries, and fallback strategies.
• Consuming messages from external systems — contract for third-party producers.

Tooling and diagnostics

• Yii Debug collector internals — collector internals, proxies, and manual wiring.

Internals and contribution

• Internals guide — local QA tooling (PHPUnit, Infection, Psalm, Rector, ComposerRequireChecker).

Queue provider registry

When multiple queue names share infrastructure, rely on QueueProviderInterface:

• A queue name is passed to QueueProviderInterface::get($queueName) and resolved into a configured QueueInterface instance.
• Default implementation (AdapterFactoryQueueProvider) enforces a strict registry defined in yiisoft/queue.queues. Unknown names throw QueueNotFoundException.
• Alternative providers include:
  • PredefinedQueueProvider — accepts a pre-built map of queue name → QueueInterface instance.
  • QueueFactoryProvider — creates queue objects lazily from yiisoft/factory definitions.
  • CompositeQueueProvider — aggregates multiple providers and selects the first that knows the queue name.
• Implement QueueProviderInterface to introduce custom registries or fallback strategies, then register the implementation in DI.