Add getPhoneNumber method to MiniApp Utils (#2961)

* Initial plan

* Add getPhoneNumber method to MiniApp Utils with tests and documentation

Co-authored-by: overtrue <[email protected]>

* Address code review feedback: improve error handling in getPhoneNumber

Co-authored-by: overtrue <[email protected]>

* Fix PHPStan error: use isset() instead of !empty() for errcode validation

Co-authored-by: overtrue <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: overtrue <[email protected]>

Author: Copilot

docs/src/6.x/mini-app/utils.md

@@ -43,3 +43,27 @@ $session = $utils->decryptSession($sessionKey, $iv, $encryptedData);
 //    }
 //}
 ```
+
+### 获取手机号
+
+获取用户绑定的手机号，需先调用 `wx.login` 接口，然后通过 `getPhoneNumber` 方法获取用户手机号。
+
+参考文档：https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/user-info/phone-number/getPhoneNumber.html
+
+```php
+$response = $utils->getPhoneNumber($code);
+
+//{
+//    "errcode": 0,
+//    "errmsg": "ok",
+//    "phone_info": {
+//        "phoneNumber": "13800138000",
+//        "purePhoneNumber": "13800138000",
+//        "countryCode": "86",
+//        "watermark": {
+//            "timestamp": 1637744274,
+//            "appid": "xxxx"
+//        }
+//    }
+//}
+```

src/MiniApp/Utils.php

@@ -35,4 +35,26 @@ public function decryptSession(string $sessionKey, string $iv, string $ciphertex
     {
         return Decryptor::decrypt($sessionKey, $iv, $ciphertext);
     }
+
+    /**
+     * @throws HttpException
+     */
+    public function getPhoneNumber(string $code): array
+    {
+        $response = $this->app->createClient()->request('POST', '/wxa/business/getuserphonenumber', [
+            'json' => [
+                'code' => $code,
+            ],
+        ])->toArray(false);
+
+        if (isset($response['errcode']) && $response['errcode'] !== 0) {
+            throw new HttpException('getPhoneNumber error: '.json_encode($response, JSON_UNESCAPED_UNICODE));
+        }
+
+        if (empty($response['phone_info'])) {
+            throw new HttpException('getPhoneNumber error: '.json_encode($response, JSON_UNESCAPED_UNICODE));
+        }
+
+        return $response;
+    }
 }

tests/MiniApp/UtilsTest.php

@@ -86,4 +86,68 @@ public function test_decrypt_session()
             ],
         ], $utils->decryptSession($sessionKey, $iv, $encryptedData));
     }
+
+    public function test_get_phone_number()
+    {
+        $response = [
+            'errcode' => 0,
+            'errmsg' => 'ok',
+            'phone_info' => [
+                'phoneNumber' => '13800138000',
+                'purePhoneNumber' => '13800138000',
+                'countryCode' => '86',
+                'watermark' => [
+                    'timestamp' => 1637744274,
+                    'appid' => 'xxxx',
+                ],
+            ],
+        ];
+
+        $httpClient = new MockHttpClient([
+            new MockResponse(json_encode(['access_token' => 'mock-access-token', 'expires_in' => 7200])),
+            new MockResponse(json_encode($response)),
+        ]);
+
+        $app = new Application([
+            'app_id' => 'mock-appid',
+            'secret' => 'mock-secret',
+            'token' => 'mock-token',
+            'aes_key' => 'mock-aes_key',
+        ]);
+        $app->setHttpClient($httpClient);
+
+        $utils = new Utils($app);
+
+        $result = $utils->getPhoneNumber('mock-phone-code');
+
+        $this->assertSame($response, $result);
+    }
+
+    public function test_get_phone_number_with_error()
+    {
+        $this->expectException(\EasyWeChat\Kernel\Exceptions\HttpException::class);
+        $this->expectExceptionMessage('getPhoneNumber error:');
+
+        $errorResponse = [
+            'errcode' => 40029,
+            'errmsg' => 'invalid code',
+        ];
+
+        $httpClient = new MockHttpClient([
+            new MockResponse(json_encode(['access_token' => 'mock-access-token', 'expires_in' => 7200])),
+            new MockResponse(json_encode($errorResponse)),
+        ]);
+
+        $app = new Application([
+            'app_id' => 'mock-appid',
+            'secret' => 'mock-secret',
+            'token' => 'mock-token',
+            'aes_key' => 'mock-aes_key',
+        ]);
+        $app->setHttpClient($httpClient);
+
+        $utils = new Utils($app);
+
+        $utils->getPhoneNumber('invalid-code');
+    }
 }