Find Firebase user(s) by federated user id

phpunit.xml.dist

@@ -6,6 +6,10 @@
     bootstrap="tests/bootstrap.php"
     colors="true"
 >
+    <php>
+        <ini name="date.timezone" value="UTC"/>
+    </php>
+
     <testsuites>
         <testsuite name="unit">
             <directory>tests/Unit</directory>

src/Firebase/Auth.php

@@ -59,7 +59,7 @@
 /**
  * @internal
  */
-final class Auth implements Contract\Auth
+final class Auth implements Contract\Auth, Contract\Transitional\FederatedUserFetcher
 {
     private readonly Parser $jwtParser;
 
@@ -210,6 +210,22 @@
         return UserRecord::fromResponseData($data['users'][0]);
     }
 
+    public function getUserByProviderUid(Stringable|string $providerId, Stringable|string $providerUid): UserRecord
+    {
+        $providerId = (string) $providerId;
+        $providerUid = (string) $providerUid;
+
+        $response = $this->client->getUserByProviderUid($providerId, $providerUid);
+
+        $data = Json::decode((string) $response->getBody(), true);
+
+        if (empty($data['users'][0])) {
+            throw new UserNotFound("No user with federated account ID '{$providerId}:{$providerUid}' found.");
+        }
+
+        return UserRecord::fromResponseData($data['users'][0]);
+    }
+
     public function createAnonymousUser(): UserRecord
     {
         return $this->createUser(CreateUser::new());

src/Firebase/Auth/ApiClient.php

@@ -118,6 +118,16 @@ public function getUserByPhoneNumber(string $phoneNumber): ResponseInterface
         return $this->requestApi($url, ['phoneNumber' => [$phoneNumber]]);
     }
 
+    /**
+     * @throws AuthException
+     */
+    public function getUserByProviderUid(string $providerId, string $uid): ResponseInterface
+    {
+        $url = $this->awareAuthResourceUrlBuilder->getUrl('/accounts:lookup');
+
+        return $this->requestApi($url, ['federatedUserId' => [['providerId' => $providerId, 'rawId' => $uid]]]);
+    }
+
     /**
      * @throws AuthException
      */

src/Firebase/Contract/Transitional/FederatedUserFetcher.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kreait\Firebase\Contract\Transitional;
+
+use Kreait\Firebase\Auth\UserRecord;
+use Kreait\Firebase\Exception;
+use Stringable;
+
+/**
+ * @TODO: This interface is intended to be integrated into the Auth interface on the next major release.
+ */
+interface FederatedUserFetcher
+{
+    /**
+     * @param Stringable|non-empty-string $providerId
+     * @param Stringable|non-empty-string $providerUid
+     *
+     * @throws Exception\AuthException
+     * @throws Exception\FirebaseException
+     */
+    public function getUserByProviderUid(Stringable|string $providerId, Stringable|string $providerUid): UserRecord;
+}

tests/Integration/AuthTestCase.php

@@ -14,6 +14,7 @@
 use Kreait\Firebase\Auth\SignIn\FailedToSignIn;
 use Kreait\Firebase\Auth\UserRecord;
 use Kreait\Firebase\Contract\Auth;
+use Kreait\Firebase\Contract\Transitional\FederatedUserFetcher;
 use Kreait\Firebase\Exception\Auth\InvalidOobCode;
 use Kreait\Firebase\Exception\Auth\RevokedIdToken;
 use Kreait\Firebase\Exception\Auth\RevokedSessionCookie;
@@ -520,6 +521,21 @@ public function getUserByNonExistingPhoneNumber(): void
         $this->auth->getUserByPhoneNumber($phoneNumber);
     }
 
+    #[Test]
+    public function getUserByNonExistingProviderUid(): void
+    {
+        if ($this->auth instanceof FederatedUserFetcher) {
+            $provider = 'test.com';
+            $uid = 'u' . random_int(1000000, 9999999);
+
+            $this->expectException(UserNotFound::class);
+            /** @phpstan-ignore method.notFound */
+            $this->auth->getUserByProviderUid($provider, $uid);
+        } else {
+            $this->fail("{\$this->auth} does not implement FederatedUserFetcher as expected - cannot test");
+        }
+    }
+
     #[Test]
     public function createUser(): void
     {