Yandex Direct Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require biplane/yandex-direct
   

2. Configure credentials (replace placeholders):

   use Biplane\YandexDirect\ConfigBuilder;
   
   $config = ConfigBuilder::create()
       ->setAccessToken('YOUR_ACCESS_TOKEN')
       ->setClientLogin('YOUR_CLIENT_LOGIN')
       ->setLocale('ru') // or 'en'
       ->getConfig();
   

3. First API call (e.g., fetch campaigns):

   use Biplane\YandexDirect\ApiServiceFactory;
   use Biplane\YandexDirect\Api\V5\Campaigns;
   
   $factory = new ApiServiceFactory();
   $service = $factory->createService($config, Campaigns::class);
   
   $response = $service->get(Contract\GetCampaignsRequest::create());
   

Key First Use Cases

• Campaign management: Fetch/modify campaigns, ad groups, or ads.
• Report generation: Pull performance data (e.g., impressions, clicks).
• Bulk operations: Use Changes service for batch updates.

Implementation Patterns

Core Workflow

1. Service Initialization:

   $factory = ApiServiceFactoryBuilder::create()
       ->setLogger(new PsrLogger($psrLogger)) // Optional: PSR-3 logging
       ->getFactory();
   

2. Request Construction (Builder Pattern):

   $request = Contract\GetAdsRequest::create()
       ->setSelectionCriteria(
           Contract\AdsSelectionCriteria::create()
               ->setCampaignIds([123, 456])
               ->setStates([Contract\StateEnum::ON])
       )
       ->setFieldNames([Contract\AdFieldEnum::ID, Contract\AdFieldEnum::STATUS]);
   

3. Execute & Process:

   $response = $service->get($request);
   foreach ($response->getAds() as $ad) {
       $ad->getStatus(); // Access fields via getters
   }
   

Integration Tips

• Dependency Injection: Register the factory in Laravel’s service container:

  $app->bind(ApiServiceFactory::class, function ($app) {
      return ApiServiceFactoryBuilder::create()
          ->setLogger($app->make(PsrLogger::class))
          ->getFactory();
  });
  

• Report Handling (Async):

  $reportService = $reportFactory->createService($config);
  $report = $reportService->getReady(
      Reports\ReportRequestBuilder::create()
          ->setReportDefinition(
              Reports\ReportDefinition::create()
                  ->setReportType(Reports\ReportTypeEnum::CAMPAIGN_PERFORMANCE_REPORT)
          )
          ->getReportRequest()
  );
  $report->saveToFile(storage_path('reports/demo.tsv'));
  

• Error Handling:

  try {
      $response = $service->get($request);
  } catch (Biplane\YandexDirect\Exception\ApiException $e) {
      Log::error('Yandex Direct API Error: ' . $e->getMessage());
  }
  

Common Patterns

Gotchas and Tips

Pitfalls

1. SOAP-Specific Issues:

   • 64-bit PHP Required: Fails on 32-bit PHP (check phpinfo()).
   • Timeouts: Default SOAP timeout may be too short for large reports. Override via:

     $factory = ApiServiceFactoryBuilder::create()
         ->setSoapOptions(['connection_timeout' => 30])
         ->getFactory();
     

   • Null Responses: Methods like getUnits() may return null (e.g., no balance data).

2. Report Service Quirks:

   • HTTP Client Dependency: Requires PSR-18 client (e.g., guzzlehttp/guzzle). Install via:

     composer require guzzlehttp/guzzle
     

   • Ready State Polling: getReady() blocks until the report is ready (no custom interval control).

3. Deprecations:

   • ConfigBuilder::setSoapOptions() is deprecated (use ApiServiceFactoryBuilder instead).
   • ReportRequest state-modifying methods removed (use ReportRequestBuilder).

Debugging Tips

• Enable Logging:

  $factory = ApiServiceFactoryBuilder::create()
      ->setLogger(new PsrLogger(new Monolog\Logger('yandex_direct', [new Monolog\Handler\StreamHandler(storage_path('logs/yandex.log'))])))
      ->getFactory();
  

  • Logs SOAP requests/responses with DEBUG (success) or ERROR (failure) levels.

• Validate SOAP Responses:

  • Use SoapFault handling:

    try {
        $response = $service->get($request);
    } catch (SoapFault $fault) {
        Log::error('SOAP Fault: ' . $fault->getMessage());
    }
    

• Field Enums:

  • Always use Contract\AdFieldEnum::ID (not strings) to avoid typos. Autocomplete helps:

    // IDE will suggest available fields
    Contract\AdFieldEnum::
    

Extension Points

1. Custom SOAP Options:

   $factory = ApiServiceFactoryBuilder::create()
       ->setSoapOptions([
           'trace' => 1, // Enable SOAP tracing
           'exceptions' => true,
       ])
       ->getFactory();
   

2. Override HTTP Client for Reports:

   use Http\Client\Common\Plugin\HeaderHandlerPlugin;
   use Http\Client\Common\PluginClient;
   
   $httpClient = new PluginClient(
       new GuzzleClient(),
       [new HeaderHandlerPlugin('User-Agent', 'MyApp/1.0')]
   );
   
   $reportFactory = new ReportServiceFactory($httpClient);
   

3. Batch Processing:

   • Use Changes service for bulk operations:

     $changes = Contract\ChangeOperation::create()
         ->setCreate([
             Contract\AdCreate::create()
                 ->setCampaignId(123)
                 ->setText('Promo text')
         ]);
     $service->apply($changes);
     

4. Testing:

   • Mock the ApiServiceFactory to return stubbed responses:

     $mockFactory = Mockery::mock(ApiServiceFactory::class);
     $mockFactory->shouldReceive('createService')
         ->andReturn(new MockAdsService([/* stubbed data */]));
     

Performance Tips

• Minimize Field Requests: Only request fields you need (e.g., setFieldNames([AdFieldEnum::ID])).
• Batch Reports: Combine multiple reports into one request where possible.
• Cache Responses: Store frequent queries (e.g., campaign lists) in Laravel’s cache:

  $cacheKey = 'yandex_campaigns_' . $clientLogin;
  return Cache::remember($cacheKey, now()->addHours(1), function () use ($service) {
      return $service->get(Contract\GetCampaignsRequest::create());
  });