Getting Started

Minimal Steps

Installation

composer require baks-dev/yandex-support

Verify PHP 8.4+ compatibility with:

php -v

Publish Configuration Run the publish command to generate the config file:
```
php artisan vendor:publish --provider="BaksDev\YandexSupport\YandexSupportServiceProvider" --tag="config"
```
Update config/yandex-support.php with your Yandex API credentials (e.g., client_id, client_secret, redirect_uri).

First Use Case: OAuth Authentication Register a route for Yandex OAuth redirection:

use BaksDev\YandexSupport\Facades\YandexAuth;

Route::get('/auth/yandex', [YandexAuth::class, 'redirectToYandex']);
Route::get('/auth/yandex/callback', [YandexAuth::class, 'handleCallback']);

Test the Flow
- Visit /auth/yandex to trigger the OAuth redirect.
- After authorization, verify the callback returns a valid Yandex user token.

Implementation Patterns

Common Workflows

1. OAuth Integration

Use the facade for seamless OAuth handling:

// Redirect user to Yandex for authentication
$authUrl = YandexAuth::getAuthorizationUrl();
return redirect()->to($authUrl);

// Handle callback after authorization
$user = YandexAuth::handleCallback($request);

2. API Client Usage

Initialize a Yandex API client (e.g., for Marketplace or Cloud):

use BaksDev\YandexSupport\Clients\MarketplaceClient;

$client = new MarketplaceClient(config('yandex-support.marketplace.api_key'));
$products = $client->getProducts(['limit' => 10]);

3. Service Provider Binding

Bind the Yandex client to Laravel’s container for dependency injection:

// app/Providers/YandexSupportServiceProvider.php
public function register(): void
{
    $this->app->singleton(MarketplaceClient::class, function ($app) {
        return new MarketplaceClient(config('yandex-support.marketplace.api_key'));
    });
}

4. Webhook Handling

Route::post('/yandex/webhook', function (Request $request) {
    $payload = YandexWebhook::verifyAndProcess($request->getContent());
    // Handle payload (e.g., payment confirmation, VM status change)
});

5. Job Queues for Async Tasks

Offload long-running Yandex API calls to Laravel queues:

use BaksDev\YandexSupport\Jobs\ProcessYandexOrder;

ProcessYandexOrder::dispatch($orderId)
    ->onQueue('yandex');

Integration Tips

Laravel-Specific Patterns

Use Facades for Simplicity Leverage the package’s facades (e.g., YandexAuth, YandexMarketplace) to reduce boilerplate in controllers:
```
public function syncProducts()
{
    $products = YandexMarketplace::getProducts();
    // Process products...
}
```

Middleware for Authenticated Requests Protect routes requiring Yandex authentication:

Route::middleware(['auth.yandex'])->group(function () {
    Route::get('/dashboard', 'DashboardController@index');
});

Event Listeners for Yandex Events Listen for Yandex webhook events and trigger Laravel events:

// app/Listeners/HandleYandexPaymentEvent.php
public function handle(YandexPaymentEvent $event)
{
    event(new PaymentReceived($event->payload));
}

Testing Strategies

Mock Yandex API Responses Use Laravel’s HTTP testing to mock Yandex API calls:

$response = Http::fake([
    'api.yandex.ru/*' => Http::response(['data' => 'test'], 200),
]);

$this->get('/sync-products')->assertOk();

Test OAuth Flow Simulate OAuth callbacks in tests:

$callbackResponse = Http::fake([
    'your-app.com/auth/yandex/callback' => Http::response($userData),
]);

$this->get('/auth/yandex/callback?code=test')->assertRedirect('/dashboard');

Configuration Management

Environment-Specific Configs Use Laravel’s .env for environment-specific Yandex credentials:

YANDEX_MARKETPLACE_API_KEY=your_key_prod
YANDEX_MARKETPLACE_API_KEY_TEST=your_key_test

Load the correct key in config/yandex-support.php:

'api_key' => env('YANDEX_MARKETPLACE_API_KEY_' . config('app.env')),

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch

Issue: The package requires PHP 8.4+, which may conflict with existing Laravel dependencies or custom code.
Fix: Upgrade PHP incrementally or use a polyfill for deprecated features. Test thoroughly after upgrading.

2. Undocumented API Limits

Issue: Yandex APIs often enforce rate limits (e.g., 100 requests/minute). The package may not handle retries or caching by default.

Fix: Implement exponential backoff in your code:

use Symfony\Component\HttpClient\RetryStrategy;

$client = HttpClient::create([
    'base_uri' => 'https://api.yandex.ru',
    'options' => [
        'retries' => 3,
        'timeout' => 30,
        'retry_strategy' => new RetryStrategy(3, 1000),
    ],
]);

3. Token Expiration Handling

Issue: OAuth tokens expire, and the package may not auto-refresh them silently.

Fix: Add a middleware to refresh tokens before making requests:

public function handle($request, Closure $next)
{
    if (YandexAuth::isTokenExpired()) {
        YandexAuth::refreshToken();
    }
    return $next($request);
}

4. Lack of English Documentation

Issue: The README and tests are in Russian, which may hinder onboarding.
Fix: Create internal documentation or translate critical sections. Use the tests as a reference for usage patterns.

5. Service Provider Conflicts

Issue: The package may not register its service provider automatically, leading to "Class not found" errors.

Fix: Manually register the provider in config/app.php:

'providers' => [
    // ...
    BaksDev\YandexSupport\YandexSupportServiceProvider::class,
],

6. Webhook Verification

Issue: Yandex webhooks require signature verification. The package may not include this by default.

Fix: Manually verify signatures in your webhook handler:

use Illuminate\Support\Facades\Http;

public function handleWebhook(Request $request)
{
    $signature = $request->header('X-Yandex-Signature');
    $payload = $request->getContent();

    if (!YandexWebhook::verifySignature($payload, $signature)) {
        abort(403, 'Invalid signature');
    }
    // Process payload...
}

Debugging Tips

1. Enable Debug Logging

Configure Laravel to log Yandex API requests/responses:

'logging' => [
    'enabled' => env('YANDEX_DEBUG', false),
    'channel' => 'single',
],

Add to AppServiceProvider:

if (config('yandex-support.logging.enabled')) {
    \Monolog\Logger::addHandler(new \Monolog\Handler\StreamHandler(storage_path('logs/yandex.log')));
}

2. Inspect Raw API Responses

Use Laravel’s tap method to debug API responses:

$response = YandexMarketplace::getProducts()->tap(function ($response) {
    \Log::debug('Raw response:', ['data' => $response->getData()]);
});

3. Test with Sandbox APIs

Use Yandex’s sandbox environments (e.g., api.sb.yandex.ru) to avoid hitting rate limits or real data:

$client = new MarketplaceClient(config('yandex-support.marketplace.sandbox_key'));

Yandex Support Laravel Package