feat: add Messenger class for multiple adapter failover support

[deepshekhardas]

Port of PR #115 by TorstenDittmann.

Adds Messenger class that orchestrates multiple messaging adapters with automatic failover. If one adapter fails, it falls back to the next in the list.

Changes:

• New Messenger class with failover orchestration
• Adapter compatibility validation (same type/message type)
• 14 comprehensive tests
• Updated README with usage example

[greptile-apps]

Greptile Summary

This PR introduces a Messenger class that wraps multiple Adapter instances and provides automatic failover: adapters are tried in sequence, and the first successful response is returned; an exception is thrown only when all adapters fail.

• Messenger class (src/Utopia/Messaging/Messenger.php): constructor validates adapter count, element types, and cross-adapter type compatibility; exposes send(), getType(), getMessageType(), and getMaxMessagesPerRequest() (returns the conservative minimum across adapters).
• Tests (tests/Messaging/MessengerTest.php): 14 PHPUnit tests covering the happy path, multi-step fallback, all-fail error aggregation, validation rejection, soft-failure pass-through, and per-method return values.
• README update: adds a "Multiple Adapters (Failover)" section with a working PHP example and a plain-English description of the failover contract.

Confidence Score: 4/5

The Messenger class is well-structured and the tests are thorough, but several defects flagged in earlier review rounds remain unaddressed in the code.

Three issues noted in prior review threads are still present: the catch block in send() only catches \Exception so any \Error bypasses failover; $this->adapters[0] is accessed directly in multiple methods, silently breaking for non-zero-indexed input arrays; and the constructor does not call array_values() to normalise keys.

Files Needing Attention: src/Utopia/Messaging/Messenger.php — the catch-block scope and array-key normalisation issues need to be fixed before the failover contract can be considered reliable.

Important Files Changed

Filename	Overview
src/Utopia/Messaging/Messenger.php	New Messenger class orchestrating multi-adapter failover; catch block scope, array-key normalization, and soft-failure pass-through issues noted in prior review rounds remain open.
tests/Messaging/MessengerTest.php	14 PHPUnit tests covering happy-path, failover, validation, soft-failure behaviour, and helper methods; coverage is comprehensive and assertions are correct.
README.md	Adds a "Multiple Adapters (Failover)" section with a clear PHP usage example and a brief description of Messenger behaviour.

_{Reviews (5): Last reviewed commit: "feat: add Messenger class for multiple a..." | Re-trigger Greptile}

[greptile-apps]

Failover skipped on \Error subclasses

The catch block only catches \Exception, so any \TypeError or other \Error thrown by an adapter will propagate immediately without trying the next adapter, defeating the purpose of failover. Changing to \Throwable would cover both \Exception and \Error hierarchies.

[greptile-apps]

Soft-failure responses bypass failover silently

Messenger::send() only falls back on thrown exceptions, so an adapter that returns a response with deliveredTo: 0 and all-failure results is treated as "success" — the second adapter is never tried. This is documented by the test, but the behaviour may surprise callers who expect the Messenger to be smarter about delivery failures. At minimum, the PHPDoc and README should warn that "failure" payloads without an exception are returned as-is without attempting the next adapter, so callers must inspect deliveredTo themselves.

[deepshekhardas]

Following up - this PR adds Messenger class for multiple adapter failover. Ready for review.