Volcano Ark Api Bundle Laravel Package

Getting Started

tourze/volcano-ark-api-bundle 0.0.1 is the first public tag — the release notes contain nothing but a compare link, so there is no documented feature list, upgrade path, or BC promise. Treat the tagged source as the spec.

1. Pin the exact version. A 0.0.x package can break on any patch bump, and you have no changelog to diff against.

   composer require tourze/volcano-ark-api-bundle:0.0.1
   

   Commit composer.lock.

2. Read these three things before writing any code, in this order:

   • src/*Bundle.php — reveals the intended service wiring and constructor dependencies.
   • config/*.yaml (or DependencyInjection/Configuration.php) — the only reliable source of config key names, since there is no README-level documentation at this version.
   • The client/service class under src/ — its constructor signature is what you will be instantiating by hand in Laravel.

3. Expect Symfony conventions, not Laravel ones. Tourze packages are Symfony bundles: a *Bundle class, a DI extension, YAML service definitions. Laravel does not read any of that. You get the PHP classes; you do not get auto-registration, config merging, or tagged services.

4. First use case — a single chat/completion call against Volcengine Ark, wrapped in your own binding rather than injected raw:

   // config/services.php
   'ark' => [
       'api_key'  => env('ARK_API_KEY'),
       'base_uri' => env('ARK_BASE_URI', 'https://ark.cn-beijing.volces.com/api/v3'),
       'endpoint' => env('ARK_ENDPOINT_ID'), // e.g. ep-2024xxxxxxxx
   ],
   

   // app/Providers/AppServiceProvider.php
   public function register(): void
   {
       // class name/FQCN: verify in src/ — do not copy from memory
       $this->app->singleton(ArkClient::class, fn () => new ArkClient(
           apiKey:   config('services.ark.api_key'),
           baseUri:  config('services.ark.base_uri'),
       ));
   }
   

If the bundle's client has a wide constructor (logger, HTTP client, serializer), construct it once as a singleton rather than per-request; most of those collaborators are stateless.

Implementation Patterns

Wrap it behind your own interface. This is the single highest-value pattern for a 0.0.1 dependency: define App\Contracts\LlmClient with one complete() method, implement ArkLlmClient delegating to the bundle, and bind the interface. When 0.0.2 renames a method or a constructor argument, you change one file.

$this->app->bind(LlmClient::class, ArkLlmClient::class);

Config-first, never literals. Everything the bundle needs (key, base URI, endpoint ID, timeout, model) belongs in config/services.php reading env() — otherwise php artisan config:cache will silently freeze or miss values.

Keep an endpoint-ID map. Ark commonly addresses deployments by endpoint ID (ep-...) rather than a raw model name. A small config map lets you route by intent ('summarise' => env('ARK_EP_SUMMARY')) instead of scattering IDs through jobs.

Push calls into queued jobs. These are slow, rate-limited, external HTTP calls. A ShouldQueue job with $tries/backoff() and a per-request timeout gives you retries and isolation for free; doing it inline in a controller ties up a PHP-FPM worker for the full latency.

Fake at your own boundary, not the vendor's. Since you own LlmClient, tests bind a stub returning canned payloads — no HTTP mocking, no knowledge of the bundle's transport. If you skip the interface and mock the bundle directly, every internal refactor breaks your test suite.

Decorate for observability. Logging, metrics, and prompt/response redaction belong in a decorator around your interface, not inside the vendor client — you cannot patch a vendor/ class safely across 0.0.x upgrades.

Gotchas and Tips

• The empty changelog is the main risk. No features or fixes are enumerated for 0.0.1, so you cannot distinguish "initial extraction" from "unstable experiment." Before adopting, skim composer.json for version constraints on symfony/* and tourze/* siblings — sibling bundles pinned to ^0.0 will drift independently of this one.
• Nothing auto-registers. Laravel ignores *Bundle classes and DI extensions. If the package's service definitions rely on Symfony compiler passes, tagged services, or parameter resolution, you must reproduce that wiring manually in a service provider. Budget for it.
• Config keys are not guessable. The bundle expects an array shaped by its own Configuration class, not Laravel's config('services.ark'). Read the YAML/PHP config definition and pass that exact shape into the constructor; do not assume api_key is the right key name.
• Auth confusion is the most common 401. Ark uses a bearer API key. Volcengine IAM access-key/secret pairs are a different credential system — mixing them produces opaque auth failures, not a clear message.
• Endpoint ID vs model name. Passing a doubao-* model string where an ep-* endpoint ID is expected typically yields a 400/404 that reads like a client bug. Confirm which the deployed bundle sends.
• Set explicit timeouts. Default Guzzle/PSR-18 connect timeouts are often unset. Configure connect (~5s) and read (~60s, longer for streaming) separately; streaming responses need the read timeout raised or they truncate mid-token.
• Don't ->throw() straight to the user. Ark returns structured errors (error.code, error.message) that may include request IDs. Catch, log with the request ID, and surface a generic message — otherwise you leak quota/account details into your UI.
• Debugging transport: if the client takes a PSR-18/PSR-7 client as a constructor argument, bind a logging middleware/decorator around it in a local provider rather than adding dump() calls. That is also the cleanest extension point for retries and circuit breaking.
• Upgrade discipline: diff src/ between tags before every bump (git diff 0.0.1..0.0.2 -- vendor/tourze/volcano-ark-api-bundle), because the release notes will not tell you what changed.