Aliyun Vod Bundle Laravel Package

Getting Started

This package wraps Alibaba Cloud's Video on Demand (VOD) service for PHP. It exposes the Aliyun SDK's upload, transcoding, playback, and media-management capabilities behind a container-managed service so you can inject a client instead of wiring the raw SDK yourself.

1. composer require tourze/aliyun-vod-bundle
2. Locate the bundle entry point under src/ — Tourze packages are Symfony bundles, so look for the *Bundle class plus Resources/config/services.yaml. That service definition is your map of what actually gets registered.
3. Publish/define the connection config: access_key_id, access_key_secret, region_id (or endpoint), and any default transcode template group / storage location.
4. First use case: inject the VOD client into a service and generate a playback URL for an existing video_id. That exercises credentials + endpoint + signing in one shot and confirms the bundle is wired correctly before you touch uploads.

Because the package is at 0.1.0, read the src/ tree before assuming a Laravel-style facade exists — there is no stable public API contract yet.

Implementation Patterns

• Bind the client explicitly. In Laravel, register the bundle's service in a ServiceProvider and alias it to an interface. Inject that interface into controllers/jobs rather than calling the Aliyun SDK statically — it keeps you testable and lets you swap config per environment.
• Separate upload from processing. Treat the "get upload credential / signature" step and the "wait for transcode + fetch playback URL" step as distinct flows. Uploads are usually done client-side (web or app) using a signed credential; your Laravel backend only issues the credential and later handles the transcode-complete callback.
• Handle the callback as a job. Aliyun posts transcode/upload status to your endpoint. Verify the payload, persist the status transition, then dispatch a queued job for downstream work (thumbnail generation, search indexing, notifications). Don't do heavy work in the webhook request.
• Wrap playback URL generation in a small helper/service so auth-key expiry and CDN domain logic live in one place. This is the piece you'll call most often day-to-day.
• Config-driven behavior in tests. Point a fake endpoint / mock the client for unit tests; you rarely want real VOD calls in CI.
• STS vs. long-lived keys. For anything user-facing (browser/app upload), issue temporary STS credentials scoped to a bucket/path rather than shipping the master access_key_secret.

Gotchas and Tips

• Symfony bundle, not a Laravel package. There's no auto-discovery in the Laravel sense. Expect to manually register the service provider and merge config yourself. This is the single biggest integration surprise.
• 0.x = unstable API. Anything can change between minor releases; pin the version in composer.json and skim the diff before bumping. No changelog detail is shipped with 0.1.0 beyond a compare link, so treat release notes as informational only.
• Region/endpoint mismatch is the most common runtime error — the region_id, bucket, and CDN domain must all belong to the same VOD region.
• Playback URL signing (auth_key / expiry) is easy to get subtly wrong: clock skew and URL-encoding of special characters cause silent 403s. Log the exact signed URL and expiry when debugging.
• Credentials hygiene: never commit access_key_*; use .env + config() and fail fast on missing values at boot.
• Transcode timing: upload success ≠ video playable. Poll or rely on the callback for transcode completion before handing out playback URLs.
• Extension point: if the bundle's default template group or storage location doesn't fit, set it explicitly in config rather than overriding classes — forks of a 0.x bundle are maintenance traps.
• Debugging tip: enable SDK-level logging (or a middleware around the injected client) so failed API calls surface the request ID — Aliyun support and error messages reference it.