Taobao Top Client Laravel Package

Getting Started

This package wraps the official Taobao TOP (Taobao Open Platform) PHP SDK in a Laravel service provider. It gives you a singleton client you can pull from the container or a facade, so you are not hand-rolling signing, timestamps, and cURL calls for every API call.

Install and wire it up

composer require orzcc/taobao-top-client

Publish the config (the tag is usually config, but check the README for the exact provider name):

php artisan vendor:publish --provider="Orzcc\TaobaoTop\TaobaoTopServiceProvider"

This drops config/taobao.php (or taobao-top.php) with placeholders for appkey, secretkey, format, gateway_url, and related options. If the package does not support auto-discovery on your Laravel version, register it manually:

// config/app.php
'providers' => [Orzcc\TaobaoTop\TaobaoTopServiceProvider::class],
'aliases'   => ['TopClient' => Orzcc\TaobaoTop\Facades\TopClient::class],

Keep credentials out of the config file — read them from .env:

TAOBAO_APP_KEY=your_app_key
TAOBAO_APP_SECRET=your_app_secret

Where to look first

Open vendor/orzcc/taobao-top-client/config/ and src/ — you want to see (a) the config keys the wrapper actually reads and (b) whether the wrapper re-exposes the underlying TopClient object. Most real work happens by calling arbitrary TOP methods through one generic entry point, so identify that method before writing any business code.

First realistic use case

The lowest-friction smoke test is an app-level API that requires no user session, e.g. taobao.time.get or taobao.item.get for a public item id:

$result = app('topclient')->execute('taobao.time.get', []);
// or, depending on the wrapper's API:
// TopClient::execute('taobao.time.get');

If you get a signed response back, credentials and config are correct. From there, move to a store-sync script (pull items, orders, or inventory for a set of shop sessions) — that is the pattern 90% of users of this package end up with.

Implementation Patterns

Wrap the singleton in a domain service, not in controllers. The client is stateful-ish (config, session key, format) and easy to misuse. Create one class per bounded concern:

class TaobaoItemService
{
    public function __construct(private $client) {}

    public function getItem(int $numIid): array
    {
        $raw = $this->client->execute('taobao.item.get', [
            'fields'  => 'num_iid,title,price,num',
            'num_iid' => $numIid,
        ]);
        return $this->unwrap($raw);
    }
}

Bind it in a service provider so tests can swap it:

$this->app->bind(TaobaoItemService::class, fn ($app) =>
    new TaobaoItemService($app->make('topclient'))
);

Normalize the two response shapes. TOP returns a normal payload on success and an error_response node on failure. Depending on the wrapper version and format config, you may get a SimpleXMLElement, a stdClass, or an array. Write one unwrap() helper and use it everywhere — do not sprinkle ->isSuccessful() checks through your app.

Separate app-level and user-level calls. Public methods (taobao.item.get, taobao.time.get) only need the app key/secret. Anything touching a merchant's own data (taobao.trades.sold.get, taobao.items.onsale.get) requires a session (access token) from the OAuth flow. Model that explicitly: store tokens per shop, pass the session key into the call params, and refresh through TOP's token endpoint on expiry. Baking the session into a global config value will bite you as soon as a second shop is added.

Batch work belongs in the queue. TOP enforces per-app QPS and daily call quotas. A nightly sync over thousands of items should be a ShouldQueue job per chunk, with retry, backoff, and a dead-letter table for permanently failing ids. This also gives you a natural place to throttle.

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

    public function handle(TaobaoItemService $items): void
    {
        $item = $items->getItem($this->numIid);
        Item::updateOrCreate(['num_iid' => $item['num_iid']], $item);
    }
}

Cache aggressively for read-heavy calls. Item detail, category trees, and shop info change slowly. Cache keyed on method + sorted params + shop_session_hash, and invalidate on your own write operations. This is the single biggest lever on your daily TOP quota.

Gotchas and Tips

Version compatibility is the biggest risk. This package is old (105 stars, long gap in releases). It targets Laravel 5.x-era conventions and the official SDK vendored a decade ago. Before committing, verify the composer.json illuminate/* constraint against your Laravel version. On Laravel 9+ you will likely need a fork or to copy the config + a thin wrapper around a current taobao-sdk/php release.

Signature failures are almost never a code bug. They are, in order of frequency: (1) the secret key has trailing whitespace from .env, (2) the server clock is skewed by more than a few minutes, (3) you built params with http_build_query somewhere in the chain and introduced encoding differences, or (4) the API method name is misspelled. Log the raw outgoing params on failure and compare against a working call.

Errors do not throw. The SDK returns ['error_response' => ['code' => ..., 'msg' => ..., 'sub_msg' => ...]]. Wrap every call in a helper that throws a proper exception. Otherwise your item sync silently stores nothing and the job "succeeds".

Charset must be UTF-8. Chinese titles and seller nicknames will come back mojibake if format/charset in the config is anything other than utf-8. Set it once in the config; do not rely on per-call overrides.

Watch the gateway and timeout. The default endpoint is in mainland China. If your app runs outside China, latency can push calls past the default timeout — raise it explicitly and put the sync calls behind the queue rather than in a request/response cycle.

QPS limits are per app key, not per IP or per process. Running five queue workers does not give you 5× throughput; it gives you rate-limit errors. Use Laravel's RateLimiter or Bus::batch with a throttle to keep the whole fleet under your contracted QPS.

Inspect, don't guess, the wrapper's API. Some versions expose $client->execute($method, $params); others forward typed methods onto the underlying TopClient ($client->taobaoItemGet(...)). Read src/ before writing anything. The underlying TopClient instance is usually reachable via a getter — that is your escape hatch for setting format, checkRequest, or a non-default gateway without editing the vendor config.

Testing: bind a fake into the container in your test suite rather than hitting TOP. Because the client is registered as a singleton string key, a single app()->instance('topclient', $fake) in a base test case covers most of your call sites. Assert on the method name and params your service produced — that is where bugs actually live.

Extension point: if you need to add a new endpoint the wrapper does not name, do not fork the package. Call the generic execute() method with the raw TOP method name and params. The wrapper is thin; almost every API is reachable that way.