Skip to content

Fix documentation references to non-existent API - #339

Open
KalimeroMK wants to merge 2 commits into
yiisoft:masterfrom
KalimeroMK:docs-fix-api-drift
Open

KalimeroMK wants to merge 2 commits into
yiisoft:masterfrom
KalimeroMK:docs-fix-api-drift

Conversation

@KalimeroMK

Copy link
Copy Markdown
Q A
Is bugfix? ❌
New feature? ❌
Breaks BC? ❌

What does this PR do?

Brings the guide back in line with the code on master. Every item below was checked against src/ and reproduced by running the package, not read off the prose.

  • Yiisoft\Queue\Message\EnvelopeInterface does not exist — envelopes extend the abstract Envelope.
  • getMetadata() does not exist — MessageInterface declares getMeta(). It appeared in two copy-paste-ready snippets (performance-tuning.md, best-practices.md).
  • Envelope::fromPayload() was documented as a second way to create an envelope; it is final and always throws LogicException.
  • The push pipeline section documented PushRequest, withAdapter() and Yiisoft\Queue\Exception\AdapterNotConfiguredException. None exist: processPush() takes and returns a MessageInterface, and the adapter is fixed when the producer is built.
  • envelopes-metadata-internals.md described an envelope stack kept under ENVELOPE_STACK_KEY ("envelopes") and rebuilt by the serializer. There is no such key or logic anywhere in src/. The page is rewritten to describe what the code does: envelopes merge into meta and flatten (getMessage() returns the innermost message), serialization carries type/payload/meta only, and the wrapper classes are not rebuilt — values are read back through IdEnvelope::fromMessage() / DelayEnvelope::fromMessage().
  • configuration-manual.md mapped DownloadFileMessage::TYPE to FileDownloader, which is the handler's injected dependency everywhere else in the docs; the handler is RemoteFileHandler.

The rewritten page also warns against registering an Envelope subclass in the message class resolver: unserialize() then calls Envelope::fromPayload() and dies with a LogicException.

Note on #338

The push pipeline section is written against master. If #338 lands and reintroduces PushRequest, that section needs another pass — happy to follow up either way.

- `EnvelopeInterface` does not exist; envelopes extend the abstract `Envelope`.
- `getMetadata()` is `getMeta()` on `MessageInterface`.
- `Envelope::fromPayload()` always throws, it is not an alternative way to build an envelope.
- The push pipeline no longer carries a `PushRequest` or an adapter, and
  `AdapterNotConfiguredException` does not exist.
- Envelope stack reconstruction is not implemented: envelopes flatten into metadata and are
  not rebuilt on unserialize. Rewrite the internals page to describe what actually happens.
- `configuration-manual.md` mapped the message type to `FileDownloader`, which is the handler's
  dependency elsewhere in the docs, not the handler.
The overview still promised push middlewares an adapter and a queue to switch, which
`processPush(MessageInterface, PushHandlerInterface)` does not offer; `FailureHandlingRequest`
carries a queue name, not an instance; and the envelope-stacking tip warned about per-layer
overhead that cannot exist, since `Envelope::__construct()` flattens.

`new Message(...)` also appeared in 15 examples across two files. `Message` is abstract and holds
only metadata; the examples mean `GenericMessage`.
@KalimeroMK

Copy link
Copy Markdown
Author

Second pass, after re-reading the files the first commit touches:

  • the overview still told push middlewares they can "switch queue, choose a different adapter", 55 lines above the section this PR replaced with "the adapter is not part of the pipeline" — processPush() receives a MessageInterface and returns one, so neither is reachable
  • FailureHandlingRequest is described as carrying "the queue instance"; it holds string $queueName
  • the "Avoid deep envelope stacking" tip warns about per-layer overhead, while Envelope::__construct() flattens — getMeta(), getType() and getPayload() cost the same at any wrapping depth
  • new Message(...) appears in 15 examples across best-practices.md and performance-tuning.md; Message is abstract and holds only metadata, so those mean GenericMessage, whose (string $type, $payload) signature the examples already match

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant