Handle SENDER_ID_MISMATCH with a dedicated exception

[QuenHengLee]

Resolves #1123

What this does

FCM rejects messages sent to a registration token that belongs to a different Firebase project with 403 PERMISSION_DENIED and the error code SENDER_ID_MISMATCH. Until now, MessagingApiExceptionConverter::convertResponse() converted this response to the same AuthenticationError as 401 responses, although the two conditions require opposite handling: a 401 is a service-level credential problem (alert an operator), while a sender ID mismatch is a permanent, per-token failure that should be handled like an unregistered token (prune the token, no alert).

With this change, 403 responses carrying the SENDER_ID_MISMATCH error code in the error details (with the "SenderId mismatch" message as a fallback marker) are converted to a new, dedicated Kreait\Firebase\Exception\Messaging\SenderIdMismatch exception:

try {
    $messaging->send($message);
} catch (SenderIdMismatch $e) {
    // permanent per-token failure: remove the token from the target list
} catch (AuthenticationError $e) {
    // actual credential problem: alert an operator
}

This mirrors the official Admin SDKs (messaging/sender-id-mismatch in Node.js, MessagingErrorCode.SENDER_ID_MISMATCH in Java, IsSenderIDMismatch() in Go) and follows the existing precedent of NotFound for UNREGISTERED tokens.

Backward compatibility

All other 401/403 responses are still converted to AuthenticationError; only the specific SENDER_ID_MISMATCH case gets the new type. The new exception implements MessagingException like every other messaging exception, so generic catch (MessagingException $e) handlers are unaffected.

Included

• SenderIdMismatch exception (same shape as the existing AuthenticationError/NotFound)
• Detection in MessagingApiExceptionConverter (error details first, message as fallback)
• 3 unit tests (detection by error code, by message, and a guard that other 403s remain AuthenticationError)
• Docs section "Mismatched registration tokens" in docs/cloud-messaging.rst + error-handling example update
• CHANGELOG entry under Unreleased

Checks

• test:unit: 361 tests OK
• analyze (PHPStan): no errors
• lint (PHP-CS-Fixer + Rector): clean

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

❗ There is a different number of reports uploaded between BASE (324b923) and HEAD (78e1ef7). Click for more details.

HEAD has 3 uploads less than BASE

Flag	BASE (324b923)	HEAD (78e1ef7)
grpc	1	0
emulator	1	0
integration	1	0

@@              Coverage Diff              @@
##                8.x    #1126       +/-   ##
=============================================
- Coverage     87.78%   40.91%   -46.87%     
- Complexity     1489     1497        +8     
=============================================
  Files           146      147        +1     
  Lines          4183     4184        +1     
=============================================
- Hits           3672     1712     -1960     
- Misses          511     2472     +1961     

[jeromegamez]

Thanks for the contribution. SendReport::messageWasSentToUnknownToken() didn't cover the new exception, I added that, including a test that ensures that both exceptions are covered.