Darabonba Laravel Package

Getting Started

alibabacloud/darabonba is not an SDK you call by name — it's the runtime client that every Darabonba-generated Alibaba Cloud PHP SDK (SMS, OSS, OCR, Live, DingTalk, etc.) extends. You almost never install it deliberately; it arrives as a transitive dependency of something like alibabacloud/dysmsapi-20170525. If you are evaluating it directly, you are probably either (a) building a generic OpenAPI caller that can hit any Alibaba Cloud product without adding a per-product package, or (b) debugging why a generated SDK behaves oddly.

Look here first

Minimal working call (generic OpenAPI, no product SDK)

composer require alibabacloud/darabonba guzzlehttp/guzzle

use Darabonba\OpenApi\OpenApiClient;
use Darabonba\OpenApi\Models\Config;
use Darabonba\OpenApi\Models\Params;
use Darabonba\OpenApi\Models\OpenApiRequest;
use Darabonba\OpenApi\Models\RuntimeOptions;
use Darabonba\Utils;

$client = new OpenApiClient(new Config([
    'accessKeyId'     => config('services.alicloud.key'),
    'accessKeySecret' => config('services.alicloud.secret'),
    'endpoint'        => 'dysmsapi.aliyuncs.com',
]));

$params = new Params([
    'action'      => 'SendSms',
    'version'     => '2017-05-25',
    'protocol'    => 'HTTPS',
    'pathname'    => '/',
    'method'      => 'POST',
    'authType'    => 'AK',
    'style'       => 'RPC',
    'reqBodyType' => 'formData',
    'bodyType'    => 'json',
]);

$request = new OpenApiRequest([
    'query' => ['PhoneNumbers' => '13800138000', 'SignName' => 'X', 'TemplateCode' => 'Y'],
]);

$response = $client->callApi($params, $request, new RuntimeOptions([]));
$data = Utils::readAsJSON($response->body);   // array, already decoded

Your first realistic use case is exactly this: one generic client, an action + version string pair, and no new Composer package per product. That is the entire reason to touch Darabonba directly.

Implementation Patterns

1. Wrap it once, inject everywhere

Never let OpenApiClient leak into controllers. Bind a single configured instance in a service provider and expose a narrow, product-specific API:

// app/Services/AliCloud/AliCloudClientFactory.php
final class AliCloudClientFactory
{
    public function make(?string $endpoint = null): OpenApiClient
    {
        return new OpenApiClient(new Config([
            'accessKeyId'     => config('services.alicloud.key'),
            'accessKeySecret' => config('services.alicloud.secret'),
            'endpoint'        => $endpoint ?? config('services.alicloud.endpoint'),
            'protocol'        => 'HTTPS',
            'connectTimeout'  => 5000,
            'readTimeout'     => 10000,
        ]));
    }
}

Darabonba has no service provider, no facade, no publishable config of its own — you supply all of that.

2. A reusable callApi helper for RPC-style products

Most Alibaba Cloud products are RPC-style and differ only in action/version/endpoint. Encode that once:

trait CallsAliCloud
{
    protected function rpc(string $action, string $version, array $query, array $runtime = []): array
    {
        $params = new Params([
            'action' => $action, 'version' => $version, 'protocol' => 'HTTPS',
            'pathname' => '/', 'method' => 'POST', 'authType' => 'AK',
            'style' => 'RPC', 'reqBodyType' => 'formData', 'bodyType' => 'json',
        ]);

        $response = $this->client->callApi(
            $params,
            new OpenApiRequest(['query' => $query]),
            new RuntimeOptions($runtime),
        );

        return Utils::readAsJSON($response->body) ?? [];
    }
}

3. RuntimeOptions as your resilience layer

Retry, timeout, and proxy behaviour are per call, not per client. Set them explicitly at every call site — the defaults are stingy:

new RuntimeOptions([
    'autoretry'      => true,
    'maxAttempts'    => 3,
    'readTimeout'    => 10000,   // ms
    'connectTimeout' => 5000,    // ms
    'retryOptions'   => ['maxAttempts' => 3],
])

Because autoretry only retries on the throttling/5xx error codes Darabonba recognises, pair it with your own try/catch for transient socket failures.

4. Credentials beyond a static AK

For STS / RAM role assumption, don't rebuild the client — hand Config a credential object:

use Darabonba\OpenApi\Credentials\AccessKeyCredential;

$config = new Config(['endpoint' => $endpoint]);
$config->credential = new AccessKeyCredential($stsId, $stsSecret, $token);

BearerTokenCredential covers OAuth-style products (e.g. DingTalk). This is the cleanest integration point for multi-tenant apps where each tenant has its own STS token.

5. Queue-friendly job shape

final class SendSmsJob implements ShouldQueue
{
    public int $tries = 3;
    public array $backoff = [5, 30, 120];

    public function handle(AliCloudSms $sms): void
    {
        $sms->send($this->phone, $this->template, $this->payload);
    }
}

Let the queue own retry/backoff and keep autoretry off inside jobs — double-retrying produces duplicate SMS/charges.

6. Testing pattern

There is no HTTP mocking hook in Darabonba. Do not try to fake Guzzle middleware through it. Instead:

• Define an interface (AliCloudSmsContract) that your service implements.
• In tests, bind a stub implementation; assert on the arguments you would have sent.
• Reserve one slow, @group integration test that hits the real endpoint with a test AK in a sandbox region.

Gotchas and Tips

Namespace is Darabonba\, not AlibabaCloud\. Every tutorial you find online mixes these up (AlibabaCloud\SDK\... is the generated product SDK, Darabonba\... is this runtime). Grep for the exact use line rather than trusting your memory.

$response->body is frequently a stream, not a string or array. json_encode($response->body) silently produces {}. Always go through Utils::readAsJSON(), Utils::readAsString(), or Utils::readAsBytes(). For binary products (OSS, OCR) you must use readAsBytes — anything else corrupts the payload.

Errors are Tea\Exception\TeaError / TeaUnableRetryError, not HTTP exceptions. Guzzle's RequestException never escapes. Catch TeaError and read $e->getCode() / $e->getMessage() / $e->data — the raw cloud error body is usually in $e->data, and the human-readable Message field needs decoding from that array:

try {
    $data = $this->rpc('SendSms', '2017-05-25', $query);
} catch (\Tea\Exception\TeaError $e) {
    $detail = json_decode($e->getMessage(), true) ?? [];
    Log::warning('aliyun.api_error', ['code' => $detail['Code'] ?? $e->getCode(), 'raw' => $e->getMessage()]);
    throw new AliCloudException($detail['Message'] ?? $e->getMessage(), (int) $e->getCode(), $e);
}

TeaUnableRetryError means autoretry exhausted its attempts — treat it as an outage signal, not a validation error.

Timeouts: readTimeout and connectTimeout are milliseconds, and live on RuntimeOptions and Config. If you set them only on the client Config, a per-call RuntimeOptions with an empty array may not inherit what you expect — set both. A hung Alibaba Cloud call will pin a PHP-FPM worker for the default 60s otherwise.

Endpoint is not inferred for generic calls. Generated SDKs carry _endpointRule functions; a bare OpenApiClient does not. You must pass the correct endpoint in Config (e.g. dysmsapi.aliyuncs.com, ocr-api.cn-hangzhou.aliyuncs.com). Wrong endpoint → confusing InvalidAccessKeyId or SignatureDoesNotMatch, never a 404.

Params::$style must match the product. RPC vs ROA vs restful changes signature computation. A signature error almost always means you copied the wrong style/pathname/reqBodyType triplet from a sibling product. Copy all nine Params fields verbatim from a generated SDK's Client.php.

Pin the version indirectly. Product SDKs pin Darabonba tightly; adding alibabacloud/darabonba to your own composer.json is a fast route to a conflict. Add the product SDK, or if you truly need the generic client, require * and let Composer resolve.

License is NOASSERTION on Packagist — Packagist could not detect an SPDX identifier. The upstream repo is Apache-2.0, but confirm with your legal/compliance review before shipping in a commercial product; do not assume MIT.

Zero stars / zero dependents is misleading. The package is a build artefact of Alibaba's SDK generator; the ecosystem lives in the hundreds of generated alibabacloud/* packages. Judge it by the generated SDKs' health, not this repo's.

Extension points are narrow, by design. You can subclass OpenApiClient, set Config::$credential, override endpoint/protocol, and pass arbitrary RuntimeOptions. You cannot swap the HTTP transport, add middleware, or hook request signing. If you need that, don't use Darabonba — talk to the REST API with Guzzle and implement the RPC signature yourself (it's HMAC-SHA1 over a canonicalised query string, ~30 lines).

Debugging tip: log the Params array plus the query/body you passed, alongside $response->statusCode and $response->headers['x-acs-request-id']. Alibaba Cloud support can trace a request by that ID alone, and it's the only field that survives their opaque error messages.