Darabonba Openapi Laravel Package

Getting Started

alibabacloud/darabonba-openapi is not a service SDK — it's the runtime core that every generated Alibaba Cloud PHP SDK (ECS, VPC, RDS, CMS, etc.) sits on top of. It owns credential resolution, request signing (ACS3-HMAC-SHA256, HMAC-SHA1, Bearer), endpoint/protocol handling, retries and the Guzzle transport. You reach for it directly only when there's no generated SDK for the API you need, or when you need to inspect/tune the plumbing underneath one that exists.

Install

composer require alibabacloud/darabonba-openapi

In practice you'll rarely add it explicitly — it arrives as a transitive dependency of any alibabacloud/*-* service SDK. The low star count is misleading: judge adoption by the service SDKs, not by this repo.

Where to look first

1. src/Client.php → execute() — this is the whole request lifecycle in one method. Read it before debugging anything.
2. src/Models/Config.php — every knob you can turn (timeouts, proxies, retry, TLS, credentials).
3. Any generated SDK's *WithOptions() method — it's the canonical template for how to build Params + OpenApiRequest by hand.
4. Models/Params, Models/OpenApiRequest, Darabonba\OpenApi\Models\RuntimeOptions — the three objects you assemble per call.

First use case: a hand-rolled RPC call

use AlibabaCloud\Darabonba\OpenApi\Client;
use AlibabaCloud\Darabonba\OpenApi\Models\Config;
use AlibabaCloud\Darabonba\OpenApi\Models\OpenApiRequest;
use AlibabaCloud\Darabonba\OpenApi\Models\Params;
use Darabonba\OpenApi\Models\RuntimeOptions;

$config = new Config([
    'accessKeyId'     => config('services.aliyun.key'),
    'accessKeySecret' => config('services.aliyun.secret'),
    'endpoint'        => 'ecs.cn-hangzhou.aliyuncs.com',
    'connectTimeout'  => 5000,
    'readTimeout'     => 30000,
]);

$client = new Client($config);

$params = new Params([
    'action'      => 'DescribeInstances',
    'version'     => '2014-05-26',
    'protocol'    => 'HTTPS',
    'pathname'    => '/',
    'method'      => 'POST',
    'authType'    => 'AK',
    'style'       => 'RPC',        // RPC | ROA
    'reqBodyType' => 'formData',   // formData | json | byte | stream
    'bodyType'    => 'json',       // json | xml | byte | stream | array
]);

$request = new OpenApiRequest([
    'query' => ['RegionId' => 'cn-hangzhou', 'PageSize' => 10],
    'body'  => [],
]);

$result = $client->callApi($params, $request, new RuntimeOptions([]));

$result is the decoded response body as an array. Note that Config, Params and OpenApiRequest live under AlibabaCloud\Darabonba\OpenApi\Models, while RuntimeOptions lives under Darabonba\OpenApi\Models — that asymmetry trips up auto-import in every IDE.

Implementation Patterns

Bind one configured client in the container. Don't build Config per call. Register a singleton per service + region in a service provider, and let Laravel inject it into the jobs/actions that need it.

$this->app->singleton(EcsClient::class, fn () => new Ecs(new Config([
    'credential' => Credential::getCredential(),   // see below
    'endpoint'   => 'ecs.cn-hangzhou.aliyuncs.com',
    'autoretry'  => true,
    'maxAttempts'=> 3,
])));

Prefer a credential provider over static AKs. AlibabaCloud\Credentials\Credential resolves from env vars, ~/.alicloud/config CLI profiles, ECS RAM roles, RAM role ARN, or OIDC. Passing the object as Config['credential'] means short-lived STS tokens are refreshed inside the runtime — you never touch securityToken by hand.

'credential' => new Credential([
    'type'            => 'ram_role_arn',
    'accessKeyId'     => config('services.aliyun.key'),
    'accessKeySecret' => config('services.aliyun.secret'),
    'roleArn'         => 'acs:ram::1234:role/app',
    'roleSessionName' => 'laravel-worker',
]),

Use RuntimeOptions for per-call overrides. This is the seam that makes the shared-singleton pattern workable. Long-running operations (snapshots, exports) get readTimeout: 300000; interactive lookups keep the 30s default. Anything not set in RuntimeOptions falls back to Config.

Wrap generated SDKs behind your own interface. Because the transport is Guzzle — not Laravel's HTTP client — Http::fake() will not intercept these calls. Define a small CloudCompute interface, implement it with the generated SDK, and bind a fake in tests. This is the single highest-leverage integration tip here.

Override execute() for observability. Subclass the SDK client and wrap the parent call to log action, version, latency and request ID. It's the only place where all of it is visible in one shot:

class TracedEcsClient extends \AlibabaCloud\SDK\Ecs\V20140526\Ecs
{
    public function execute($params, $request, $runtime)
    {
        $t = microtime(true);
        try {
            return parent::execute($params, $request, $runtime);
        } finally {
            Log::info('aliyun.openapi', [
                'action'    => $params->action,
                'ms'        => (int) ((microtime(true) - $t) * 1000),
            ]);
        }
    }
}

Paginate explicitly. There's no iterator. Loop with the API's PageNumber/PageSize (RPC) or NextToken/MaxResults (ROA), checking for empty pages or a null token. Set a hard iteration cap — a bug in the token comparison is an infinite loop against a rate-limited API.

Gotchas and Tips

endpoint is required and is a bare host. regionId alone does not resolve an endpoint in the PHP runtime (unlike some other language runtimes). Use ecs.cn-hangzhou.aliyuncs.com, not https://ecs.cn-hangzhou.aliyuncs.com — including the scheme can produce a doubled scheme or a Host header that mismatches the signature and yields SignatureDoesNotMatch.

style and pathname must match the API's actual style. RPC → pathname is / and params go in query/body form fields. ROA → pathname is the resource path (e.g. /clusters/{id}), params go in query, payload in body. Getting this wrong produces signature errors, not helpful validation errors.

bodyType vs reqBodyType are not the same field. reqBodyType describes what you send; bodyType describes what you expect back. A JSON-expecting bodyType against an XML API returns an empty or garbled array rather than a clear failure.

Timeouts don't always have safe defaults. If readTimeout is unset it can fall through to Guzzle's "wait forever". Always set connectTimeout and readTimeout explicitly in Config — a hung worker in a queue is far worse than a failed call.

autoretry retries more than you'd expect and less than you'd hope. Network errors and specific HTTP statuses are retried; application-level throttling errors (Throttling, ServiceUnavailable) may or may not be, depending on the SDK version. Don't rely on it for exactly-once semantics — make your own operations idempotent, and read backoffPolicy / maxAttempts behaviour in execute() for the version you're on.

Proxy config is easy to get almost right. httpProxy/httpsProxy take full URLs, noProxy is a comma-separated host list, and SOCKS5 additionally needs a curl build with socks support. Corporate TLS-inspecting proxies need ignoreSSL => true (or a ca bundle) — prefer the CA bundle; ignoreSSL in production silently disables a real defence.

Guzzle version conflicts are the most common install failure. Older darabonba-openapi releases pin guzzlehttp/guzzle ^6.3, which is incompatible with Laravel 9+ (^7.0.1). If Composer refuses to solve, bump alibabacloud/darabonba-openapi and the service SDKs together, and don't force a downgrade of Guzzle.

Don't pin the runtime independently of the SDKs. Generated SDKs have tight constraints on both this package and alibabacloud/tea-utils. Run composer update alibabacloud/* as a group; a lone composer update alibabacloud/darabonba-openapi is how you get a mismatched callApi/execute signature after a major bump.

Nested query arrays aren't auto-flattened. RPC APIs expecting Tag.1.Key=env need you to build that flattened key yourself; passing ['Tags' => [['Key' => 'env']]] will be silently mis-serialised. Check the API's documented parameter style before writing the array.

Use a proxy to inspect traffic. Since there's no debug flag on RuntimeOptions, point httpsProxy at mitmproxy/Charles (plus ignoreSSL for the MITM cert). It's faster than adding logging to execute() when you need to see the exact signed request.

Version pinning caveat: the doRPCRequest/doROARequest helpers are the legacy surface; callApi/execute is what current SDKs use. If you're writing new code against a v2-era SDK, use callApi and treat anything else as a signal that you're looking at a stale tutorial.