Yandex Oauth Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require clarity-project/yandex-oauth-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Clarity\YandexOAuthBundle\ClarityYandexOAuthBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console clarity:yandex-oauth:install
   

   Update config/packages/clarity_yandex_oauth.yaml with your Yandex OAuth credentials:

   clarity_yandex_oauth:
       client_id: 'your_client_id'
       client_secret: 'your_client_secret'
       redirect_uri: 'https://your-app.com/connect/yandex/check'
   

3. First Use Case: Authentication Flow

   • Add a route to initiate OAuth:

     # config/routes.yaml
     yandex_oauth_connect:
         path: /connect/yandex
         controller: Clarity\YandexOAuthBundle\Controller\AuthController::connectAction
     

   • Redirect users to Yandex for authorization:

     // In your controller
     return $this->redirect($this->generateUrl('yandex_oauth_connect'));
     

   • Handle the callback (auto-configured by the bundle).

Implementation Patterns

Workflow: Token Management

1. Fetching Tokens Use the service to retrieve or refresh tokens:

   $tokenManager = $this->get('clarity_yandex_oauth.token_manager');
   $token = $tokenManager->getAccessToken(); // Auto-refreshes if expired
   

2. Storing Tokens in Doctrine The bundle provides an entity (Clarity\YandexOAuthBundle\Entity\Token) for persistence. Extend or use it directly:

   $tokenEntity = new Token();
   $tokenEntity->setAccessToken($token->getAccessToken());
   $tokenEntity->setRefreshToken($token->getRefreshToken());
   $em->persist($tokenEntity);
   $em->flush();
   

3. API Integration Use the YandexApiClient service to interact with Yandex APIs:

   $client = $this->get('clarity_yandex_oauth.api_client');
   $response = $client->get('/v1/user/info'); // Example endpoint
   $data = $response->getData(); // Serialized via JMSSerializer
   

Common Patterns

• Event Listeners: Extend token logic by subscribing to events (e.g., TokenRefreshedEvent).
• Custom Serialization: Override default serialization by configuring jm_serializer in config/packages/clarity_yandex_oauth.yaml.
• Multi-Tenant Tokens: Store additional metadata (e.g., tenant_id) in the Token entity for shared environments.

Gotchas and Tips

Pitfalls

1. Redirect URI Mismatch

   • Yandex OAuth strictly validates the redirect_uri. Ensure it matches exactly (including https:// vs. http://).
   • Fix: Double-check clarity_yandex_oauth.yaml and Yandex Developer Console settings.

2. Token Expiry Handling

   • The bundle auto-refreshes tokens, but network issues (e.g., proxy blocks) may break silently.
   • Debug: Enable Guzzle logging in config/packages/misd_guzzle.yaml:

     misd_guzzle:
         plugins:
             - Clarity\YandexOAuthBundle\Plugin\LoggingPlugin
     

3. Doctrine Entity Conflicts

   • If you already have a Token entity, namespace collisions may occur.
   • Fix: Alias the bundle’s entity in config/packages/doctrine.yaml:

     doctrine:
         orm:
             entity_managers:
                 default:
                     mappings:
                         ClarityYandexOAuthBundle: ~
     

Tips

1. Testing OAuth Flows Use Yandex’s sandbox mode for local development:

   clarity_yandex_oauth:
       sandbox: true
   

2. Custom API Responses Extend the YandexApiResponse class to handle Yandex-specific data formats:

   // src/Service/YandexCustomResponse.php
   class YandexCustomResponse extends YandexApiResponse
   {
       public function getUserId()
       {
           return $this->data['id'] ?? null;
       }
   }
   

   Register it in services.yaml:

   services:
       clarity_yandex_oauth.api_response:
           class: App\Service\YandexCustomResponse
           tags: ['clarity_yandex_oauth.api_response']
   

3. Logging Enable debug logs for token operations:

   clarity_yandex_oauth:
       debug: true
   

4. Performance Cache token refresh operations if using high-frequency APIs:

   $token = $tokenManager->getAccessToken(['cache_key' => 'yandex_token']);