Yandex Php Library Laravel Package

Getting Started

• Install with composer require nixsolutions/yandex-php-library. There is no Laravel service provider or auto-discovery — treat it as a plain PHP SDK you wire up yourself.
• Look first in src/Yandex/ (or vendor/nixsolutions/yandex-php-library/src/Yandex/). Services are namespaced per API, e.g. Yandex\Disk\DiskClient, Yandex\Metrika\MetrikaClient, Yandex\Translate\TranslateClient. Open the client class for the service you need and read its constructor plus public methods — that is your real API reference.
• Register an application at oauth.yandex.ru to get a client ID/secret. Most services require an OAuth token and specific scopes (Disk, Metrika, Direct, etc.). Do not request broader scopes than you need.
• Put credentials in config/services.php and .env:

  'yandex' => [
      'client_id' => env('YANDEX_CLIENT_ID'),
      'client_secret' => env('YANDEX_CLIENT_SECRET'),
      'redirect' => env('YANDEX_REDIRECT_URI'),
      'token' => env('YANDEX_TOKEN'),
  ],
  

• First use case: a Yandex.Disk integration. Obtain a token via the Authorization Code flow in a small controller, then instantiate the Disk client with that token and call a listing method (getList/getResource) to confirm connectivity before building upload/download features.
• Verify the package installs cleanly against your Laravel version before committing to it; its dependency constraints may conflict with newer framework/Guzzle versions.

Implementation Patterns

• Wrap the SDK in your own service class. Bind it as a singleton in a service provider so controllers, jobs, and commands share one configured client:

  $this->app->singleton(DiskClient::class, fn () => new DiskClient(config('services.yandex.token')));
  

  This also gives you one place to swap or mock it later.
• Keep tokens out of code. Store per-user OAuth tokens encrypted in the database and resolve them at call time. For multi-tenant apps, do not bind a token-based client as a global singleton — build it per request/user.
• Push bulk work to queues. Uploading many files to Disk, pulling Metrika statistics across counters, or batch-translating content should be jobs. Return quickly from the controller and let workers call the SDK.
• Cache read-heavy API responses. Metrika reporting and dictionary/translate lookups are good candidates for Cache::remember with short TTLs, since quotas are a real constraint.
• Adopt a thin adapter interface. Define DiskService, MetrikaService, etc., in your app and implement them with the SDK. This makes unit tests trivial and isolates the rest of the app from the library's exception types and method signatures.
• Use events for side effects. Fire a domain event after a successful upload so other parts of the app (notifications, indexing, audit logs) don't need to know about Yandex at all.
• Build Artisan commands for OAuth maintenance — token refresh, scope checks, and connectivity smoke tests. Schedule them where appropriate.
• In tests, fake the adapter, not the SDK. The SDK classes are concrete and network-bound; mocking at your interface boundary is far less brittle than mocking internals.

Gotchas and Tips

• No framework integration is provided. No facade, no config publishing, no service provider, no auto-discovery. Budget time for your own glue code.
• The package is not actively maintained. Last activity is well behind current Laravel releases. Expect potential dependency conflicts (Guzzle/PSR versions) and missing type hints. Pin versions and test upgrades carefully.
• Exception handling is coarse. SDK clients throw library-specific exceptions; catch them at your adapter boundary, log the Yandex error payload, and rethrow as your own domain exceptions. Don't let vendor exceptions leak into controllers.
• 401s are almost always scope or token problems, not code bugs. Confirm the token has the exact scope the endpoint needs, and that the redirect URI matches what is registered at oauth.yandex.ru — including trailing slashes and scheme.
• Some endpoints are locale/region sensitive. Yandex services can behave differently by region; make locale explicit where the client supports it.
• Upload methods often expect local file paths. For streamed or generated content, write to a temp file first or use the lower-level upload methods exposed by the client. Clean up temp files in a finally block.
• Rate limits and quotas differ per service (Metrika, Disk). Implement retry-with-backoff around throttled calls rather than retrying immediately.
• Debugging is manual. The SDK has no built-in logging hook. Log request context (endpoint, params minus secrets) and the response/exception body yourself; enable your HTTP transport's debug output if it is configurable.
• Extension points are limited to subclassing or wrapping. There is no plugin system or DI-friendly design. Prefer composition (your adapter holding the client) over extending SDK classes.
• For simple endpoints, consider skipping the SDK entirely. Laravel's Http client can call several Yandex REST APIs directly, removing a stale dependency and giving you better logging, retries, and testability. Use the SDK where its request signing or payload shaping genuinely saves you work.
• Watch memory on large Disk operations. Download and process in chunks/streams rather than loading whole files via the SDK's convenience methods.