Ok Php Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ailove-dev/ok-php-sdk
   

   Verify the package is autoloaded in composer.json under "autoload": { "psr-4": { "Ailove\\OkSDK\\": "vendor/ailove-dev/ok-php-sdk/src/" } }.

2. First Use Case: Authentication Initialize the SDK with your API credentials:

   use Ailove\OkSDK\Ok;
   
   $ok = new Ok([
       'client_id'     => 'YOUR_CLIENT_ID',
       'client_secret' => 'YOUR_CLIENT_SECRET',
       'redirect_uri'  => 'https://your-app.com/callback',
   ]);
   

3. Key Files to Review

   • src/Ok.php: Main SDK class (entry point for all API calls).
   • src/Exceptions/OkException.php: Error handling logic.
   • src/Traits/ApiTrait.php: Core API request methods (e.g., get(), post()).

Implementation Patterns

Workflows

1. OAuth Flow Redirect users to Odnoklassniki for auth:

   $authUrl = $ok->getAuthUrl(['scope' => 'VALUES']);
   return redirect($authUrl);
   

   Handle the callback:

   $token = $ok->getAccessToken($_GET['code']);
   

2. API Requests Fetch user data:

   $user = $ok->api('users.getCurrentUser', ['fields' => 'uid,first_name']);
   

3. Batch Operations Use apiBatch() for multiple requests:

   $results = $ok->apiBatch([
       ['method' => 'users.getCurrentUser', 'params' => []],
       ['method' => 'stats.get', 'params' => ['owner_uid' => 123]],
   ]);
   

Integration Tips

• Laravel Service Provider Bind the SDK to the container for dependency injection:

  $this->app->singleton(Ok::class, function ($app) {
      return new Ok(config('services.ok'));
  });
  

  Configure in config/services.php:

  'ok' => [
      'client_id'     => env('OK_CLIENT_ID'),
      'client_secret' => env('OK_CLIENT_SECRET'),
      'redirect_uri'  => env('OK_REDIRECT_URI'),
  ],
  

• Middleware for Auth Protect routes requiring Odnoklassniki auth:

  public function handle($request, Closure $next) {
      if (!$request->user()->token) {
          return redirect()->route('ok.auth');
      }
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Token Expiry

   • Tokens expire after ~30 days. Implement token refresh logic:

     try {
         $ok->api('users.getCurrentUser');
     } catch (\Ailove\OkSDK\Exceptions\TokenExpiredException $e) {
         $token = $ok->refreshAccessToken($e->getRefreshToken());
     }
     

2. Rate Limiting

   • Odnoklassniki enforces rate limits (e.g., 300 requests/hour). Cache responses aggressively:

     $cacheKey = 'ok_user_' . $userId;
     return Cache::remember($cacheKey, now()->addHours(1), function () use ($ok, $userId) {
         return $ok->api('users.getById', ['uid' => $userId]);
     });
     

3. Deprecated Methods

   • Some API methods may be deprecated. Check Odnoklassniki API docs for updates and use api() with explicit method names.

Debugging

• Enable Debug Mode Pass debug: true to the SDK constructor to log raw API responses:

  $ok = new Ok([...], ['debug' => true]);
  

  Logs appear in storage/logs/ok-sdk.log.

• Common Errors

  • InvalidRequestException: Validate client_id, redirect_uri, and scopes.
  • ServerErrorException: Check Odnoklassniki’s status page for outages.

Extension Points

1. Custom API Clients Extend ApiTrait to add retry logic or custom headers:

   use Ailove\OkSDK\Traits\ApiTrait;
   
   class CustomOk extends Ok {
       use ApiTrait;
   
       protected function getHeaders() {
           $headers = parent::getHeaders();
           $headers['X-Custom-Header'] = 'value';
           return $headers;
       }
   }
   

2. Webhook Handling Validate Odnoklassniki webhook signatures:

   $secret = config('services.ok.webhook_secret');
   $signature = $_SERVER['HTTP_OK_SIGNATURE'];
   if (!hash_equals($signature, hash_hmac('sha1', file_get_contents('php://input'), $secret))) {
       abort(403);
   }