Dnspod Laravel Package

Getting Started

The package is a generated Tencent Cloud SDK client for the DNSPod DNS API. It is a thin, typed wrapper over HTTPS — no ORM, no config publishing, no facade. Everything you need to know about the API surface is visible in the source tree.

composer require tencentcloud/dnspod

Minimal working call:

use TencentCloud\Common\Credential;
use TencentCloud\Common\Profile\ClientProfile;
use TencentCloud\Common\Profile\HttpProfile;
use TencentCloud\Dnspod\V20210323\DnspodClient;
use TencentCloud\Dnspod\V20210323\Models\DescribeDomainListRequest;

$cred = new Credential(
    config('services.dnspod.secret_id'),
    config('services.dnspod.secret_key')
);

$http = (new HttpProfile())
    ->setEndpoint('dnspod.tencentcloudapi.com')
    ->setConnTimeout(5)
    ->setReqTimeout(30);

$client = new DnspodClient($cred, '', (new ClientProfile())->setHttpProfile($http));

$req = new DescribeDomainListRequest();
$req->Offset = 0;
$req->Limit  = 20;

$resp = $client->DescribeDomainList($req);
foreach ($resp->DomainList ?? [] as $domain) {
    echo $domain->Name, PHP_EOL;
}

Where to look first. Two files, both in vendor/tencentcloud/dnspod/src/TencentCloud/Dnspod/V20210323/:

• DnspodClient.php — every action method, one per API. This is your authoritative list of what the API can do.
• Models/ — one *Request class per action. The public properties are the API parameters, including exact casing (SubDomain, RecordLine, RecordLineId, TTL, MX, Weight). Read the request class instead of hunting for docs; it is the same schema.

First real use case. Read-then-write on a single record — list a domain's records, create an A record, then list again to confirm. Do this against a throwaway subdomain on a domain you already have delegated to DNSPod nameservers, because record writes to a domain that isn't using DNSPod NS will succeed at the API level but never resolve.

Prefer Credential::defaultCredential() if you already export TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY / TENCENTCLOUD_TOKEN; it also picks up instance-role credentials on CVM. That removes secret handling from your code path entirely.

Implementation Patterns

Centralize the client, not the calls. Construct the DnspodClient once per process (in a container binding or a small DnspodFactory) and inject it. The client is stateless and safe to reuse; building a Credential + ClientProfile + client per API call is pure overhead and makes it harder to change timeouts and endpoints later.

Wrap raw calls in a domain service. Model your own intent (DnsService::pointHostTo($fqdn, $ip), DnsService::listRecordsFor($domain)) and keep request/response models out of your controllers. This is also what makes the whole thing testable — swap the service for a fake and you never touch the SDK in tests.

Paginate explicitly. Every list action takes Offset/Limit with a per-action cap. Loop until the returned count is smaller than the requested limit; never assume one page. Cache the results (domains change rarely) rather than re-listing on every request.

Read-modify-write for updates. ModifyRecord accepts partial fields, but if you change RecordType you must also send Value, and the interaction between MX, Weight, and record line on a partial update is easy to get wrong. Fetch the record, mutate the specific field, send the full field set back. It costs one extra read and eliminates a whole class of silent corruption.

Prefer batch endpoints. ModifyRecordBatch / DeleteRecordBatch exist for the bulk cases. When you must loop single calls, throttle yourself — a queue worker with a per-domain token bucket is the standard shape, because DNSPod's per-action rate limits are per account, not per process.

Deduplicate writes yourself. There is no idempotency token on CreateRecord. Before creating, call DescribeRecordList filtered by Subdomain and RecordType and reconcile. This matters a lot for retry-on-timeout paths, where the write may have landed even though your client got an error.

Logging. Every response model has toJsonString() and serialize(). Log the JSON at debug level alongside TencentCloudSDKException::getRequestId() — Tencent support asks for the RequestId, and it is the only reliable way to correlate a failure with their side.

Testing. Two viable approaches: (a) fake your own service layer, which is what you want for 95% of tests; (b) point HttpProfile::setEndpoint() at a local stub server for genuine serialization coverage. Do not hit the real API from CI — record limits and rate limits make it flaky.

Gotchas and Tips

RecordLine is Chinese, and its default is not what you think. The default line is 默认. If you hardcode an empty string you get an InvalidParameter for something that looks perfectly valid. Send RecordLineId = "0" instead — it is the default line expressed as an ID and survives encoding issues in terminals, logs, and YAML configs.

Region must be an empty string. DNSPod is a global service. Passing a region like ap-guangzhou puts a value in the signed credential scope that has no meaning for this endpoint. new DnspodClient($cred, '') — note the second argument.

Catch the right exception class. Failures surface as TencentCloud\Common\Exception\TencentCloudSDKException, with getErrorCode() giving you the specific code (AuthFailure, InvalidParameter.DomainIdInvalid, RequestLimitExceeded, ResourceNotFound.NoDataOfRecord). Branch on the code, never on the message string — messages are localized and change. Distinguish "bad input, don't retry" from "rate limited, retry with backoff."

There is no automatic retry. Set ConnTimeout and ReqTimeout on HttpProfile explicitly (defaults are generous) and implement retries only around idempotent reads. For writes, retry only after re-reading state to see whether the first attempt succeeded.

Rate limits are real and per-interface. Free-tier accounts are tightly capped on record operations, and RequestLimitExceeded will appear under load. Queue DNS writes off the request path; users should not wait on an HTTP round trip to a DNS API during a web request.

Plan quotas bite before the API does. Free plans impose a minimum TTL (600s), cap record counts per domain, and restrict record types (URL forwarding, NS delegation for the root). These come back as validation errors that read like API bugs but are account-tier limits. Check the domain's grade via DescribeDomain before promising a feature.

Delegation, not the API, decides whether anything resolves. Creating records via API on a domain whose NS records still point at another registrar does nothing user-visible. Verify the domain is actually served by DNSPod nameservers before treating an API "success" as a deployed change. And remember propagation delay — confirming via the API only confirms DNSPod accepted the record, not that the internet sees it.

Limit caps differ per action. Record listing allows a much larger page than domain listing, and the caps have changed over time. Don't hardcode an assumption; clamp to something safe and loop.

It is a generated package — don't patch vendor/. Treat any gap as a wrapper-layer problem. Pin the version ("tencentcloud/dnspod": "^3.x") and let Composer keep tencentcloud/common in sync; a mismatched common will produce confusing signature failures. If you need a private endpoint or gateway, HttpProfile::setRootDomain() is the supported extension point — subclassing the client is not.