Youzan Api User Bundle Laravel Package

Getting Started

Install with Composer and pin the minor version explicitly — 0.1.0 is the second ever tagged release, so treat it as pre-stable:

composer require tourze/youzan-api-user-bundle:^0.1.0

Where to look first, in this order:

1. vendor/tourze/youzan-api-user-bundle/ — read composer.json for its actual dependencies (likely a tourze/youzan-api-* core client plus a Symfony Bundle class) and src/ for the service/DTO surface. With a changelog this thin, the source is the documentation.
2. The underlying API package it wraps. Tourze splits these as *-api-* core packages with a thin *-bundle wrapper, so most of the callable behaviour lives one level down.
3. Youzan's own open-platform docs for the user/fan endpoints (token model, error codes, rate limits) — these constraints drive your integration more than the PHP code does.

First use case worth wiring end-to-end: fetch a single customer/fan record by openid or user id and persist it. That single path exercises credentials, token acquisition, the HTTP layer, the response envelope, and your DTO mapping — everything else (listing, syncing, binding) is repetition of that shape.

Because this is a Symfony bundle, do not expect Laravel auto-discovery to do anything useful. Register the services you need manually in a YouzanServiceProvider (or bind a small adapter class) rather than relying on extra.laravel.

Implementation Patterns

Put a thin adapter between your app and the package. Never let controllers or models touch the SDK. One class per shop connection, resolved through a manager:

final class YouzanUserClient
{
    public function __construct(private UserApi $api) {}

    public function findFan(string $openId): ?Fan
    {
        $response = $this->api->getUser(['open_id' => $openId]);
        // normalise: check code, map to your DTO, throw your exception
    }
}

Configuration as named connections. Youzan credentials are per-shop and per-app (client_id, client_secret, and often a kdt_id/shop id). Model them as config/youzan.php returning an array of named shops, then build one client per name. This is the single highest-leverage decision — the moment a second shop appears, a singleton configured from a flat env key becomes a rewrite.

Token lifecycle belongs in the container, not in feature code. Access tokens are long-lived-but-expiring and tied to shop + app. Cache them (Cache::remember with a TTL a few minutes under the real expiry) and centralise refresh in the client factory or a dedicated token manager. Everything downstream then behaves as if auth were free.

Queue the bulk operations. Fan/customer listing is paginated with cursors or page_no/page_size, and Youzan enforces per-app quotas. A SyncFansJob per page, dispatching the next page, survives rate limits and timeouts far better than a loop in a console command.

Persist raw payloads alongside your mapped fields (a json column) for the first few weeks. When a field maps wrong — and one will — you can re-derive records without re-calling the API and burning quota.

Test with a fake HTTP layer, not the package. Since the bundle is a thin wrapper, Http::fake() (or a Guzzle MockHandler if it uses its own client) gives you the most realistic coverage. Assert on your adapter's output DTOs, not on the package's response objects — that keeps your tests alive across future 0.x bumps.

Gotchas and Tips

• Pre-1.0 semver. 0.1.0 may contain breaking changes from 0.0.1 — the changelog link is the only record. Pin with ^0.1.0, commit the lock file, and after any bump diff vendor/tourze/youzan-api-user-bundle/src/ plus the sibling youzan-api-* packages, since the bundle inherits breaking changes from its core dependency.
• Error codes, not exceptions. Youzan-style APIs commonly return HTTP 200 with a non-success code/error_response in the body. Assume you must inspect the envelope yourself and translate it to exceptions at the adapter boundary — otherwise silent failures look like empty results.
• Symfony service wiring. Attribute-based autoconfiguration and Resources/config/services.php definitions won't be loaded by Laravel. Copy the definitions you need or construct the underlying API class directly; expect some friction here on first install.
• Token leakage. Never log raw request/response bodies at debug level in production — tokens and customer PII travel in the same payloads. Use a redacting processor.
• Clock skew and expiry. Cache TTLs slightly shorter than the documented token lifetime; a token expiring mid-request is the most common intermittent production failure in this class of integration.
• Extract, don't extend. Prefer depending on tourze/youzan-api-* (the core) and treating the bundle as a reference implementation if you hit wiring friction — you keep the same API surface with no framework coupling.
• Watch for the next release. An empty 0.1.0 changelog means the project is still settling. Subscribe to releases; re-read this assessment when 0.2.0 or 1.0.0 lands, since that's when config keys and namespaces typically stabilise.