Prokerala 占星 PHP SDK
prokerala/astrology-sdk 是 Prokerala 占星 API v2 的官方 PHP 客户端。它为每个端点提供了类型化的服务类、PSR-18/17 HTTP 抽象、可选的 PSR-16 令牌缓存以及带有 getter 方法的类型化结果对象。
源代码仓库:https://github.com/prokerala/astrology-sdk
如何使用此技能
- 消费 SDK(安装、引导、首次调用):请阅读
references/getting-started.md。 - 为某个端点查找正确的服务类:请阅读
references/services.md(所有 99 个服务都已映射到 API 路径)。 - 修改或扩展 SDK(新端点、结果类、测试):请阅读
references/maintainer-guide.md。 - 端点参数、枚举和响应模式在配套的 API 技能
prokerala-astrology-api中已有文档说明;此 SDK 技能不会重复提供它们。
要求
- PHP >= 8.0
- Composer 包:
prokerala/astrology-sdk以及 PSR-17/PSR-18 实现(例如nyholm/psr7+guzzlehttp/guzzle),并可选择 PSR-16 缓存(例如symfony/cache)用于令牌缓存。
快速参考
use GuzzleHttp\Client as HttpClient;
use Nyholm\Psr7\Factory\Psr17Factory;
use Prokerala\Common\Api\Authentication\Oauth2;
use Prokerala\Common\Api\Client;
use Prokerala\Api\Astrology\Location;
use Prokerala\Api\Astrology\Service\Kundli;
$psr17Factory = new Psr17Factory();
$httpClient = new HttpClient();
// 可选的第六个参数:任何 PSR-16 缓存;用于缓存 OAuth 令牌直到过期。
$authClient = new Oauth2($clientId, $clientSecret, $httpClient, $psr17Factory, $psr17Factory, $cache);
$client = new Client($authClient, $httpClient, $psr17Factory);
$location = new Location(23.1765, 75.7885, 0, new DateTimeZone('Asia/Kolkata'));
$datetime = new DateTimeImmutable('2022-03-17T10:50:40+05:30');
$result = (new Kundli($client))->process($location, $datetime);
$nakshatra = $result->getNakshatraDetails()->getNakshatra()->getName();
- 服务在其构造函数中接受
Client,并公开一个单一的process(...)方法。 - 通过
Location传递坐标;将日期时间作为DateTimeImmutable传递(SDK 会在内部将其格式化为 ISO 8601)。 $client->getCreditUsed()返回上次调用消耗的 API 积分(来自X-Api-Credits头)。
异常
所有异常均在 Prokerala\Common\Api\Exception 命名空间下,由 Client::process() 抛出:
| 异常类型 | HTTP 状态码 | 含义 |
|---|---|---|
ValidationException | 400 | 无效输入;包含完整的 errors 列表 |
AuthenticationException | 401 | 凭证错误或已过期 |
QuotaExceededException | 403 | API 积分不足 |
RateLimitExceededException | 429 | 请求过于频繁;请稍后重试 |
ServerException | 500 | 服务端故障 |
Exception | 其他 | 基类;捕获所有其他异常 |
TokenExpiredException 在内部处理(客户端会刷新令牌并重试一次);消费代码无需捕获它。