Blizzard Sdk Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require ajardin/blizzard-sdk-bundle

For Symfony Flex, this auto-registers the bundle. For manual setup, add to config/bundles.php:

Ajardin\BlizzardSdkBundle\AjardinBlizzardSdkBundle::class => ['all' => true],

2. Configure Credentials: Add to .env:

   BLIZZARD_CLIENT_ID=your_client_id
   BLIZZARD_SECRET=your_client_secret
   

   Then configure in config/packages/ajardin_blizzard_sdk.yaml:

   ajardin_blizzard_sdk:
       blizzard:
           client_id: '%env(BLIZZARD_CLIENT_ID)%'
           client_secret: '%env(BLIZZARD_SECRET)%'
   

3. First Use Case: Fetch WoW realms for a region (e.g., us):

   use Ajardin\BlizzardSdkBundle\BlizzardApi\WorldOfWarcraft\RealmApi;
   
   class RealmService {
       public function __construct(private RealmApi $realmApi) {}
   
       public function getRealms(): array {
           $response = $this->realmApi->realmIndex('us');
           return $response->toArray()['realms'] ?? [];
       }
   }
   

Implementation Patterns

Dependency Injection

• Autowire Services: All API endpoints are autowireable (e.g., AchievementApi, CharacterProfileApi).

  use Ajardin\BlizzardSdkBundle\BlizzardApi\WorldOfWarcraft\AchievementApi;
  
  class AchievementService {
      public function __construct(private AchievementApi $achievementApi) {}
  }
  

Asynchronous Requests

• Non-blocking Calls: Use Symfony’s HttpClient responses asynchronously:

  $response = $this->itemApi->itemIndex('us', 'en_US');
  // Process other logic while the request completes in the background.
  $data = $response->toArray(); // Fetch data when ready.
  

Region Handling

• Region-Specific Endpoints: Pass region codes (us, eu, kr, tw) to all methods:

  $this->realmApi->realmIndex('eu'); // Europe
  

Response Processing

• DTOs vs. Raw Data: Decide between:
  • Raw arrays: $response->toArray()
  • Custom DTOs (extend the bundle or use JsonSerializable wrappers).

Common Workflows

1. Fetch Game Data:

   $this->itemApi->itemIndex('us', 'en_US', 12345); // Item ID
   

2. Profile Data:

   $this->characterProfileApi->characterProfile('us', 'Area52', 'DeathKnight');
   

3. Paginated Results: Use limit and offset parameters where supported (e.g., realmIndex).

Gotchas and Tips

Pitfalls

1. Rate Limits:

   • Blizzard enforces strict rate limits. Cache responses aggressively:

     $cacheKey = 'blizzard_realms_us';
     if (!$cached = $cache->get($cacheKey)) {
         $cached = $this->realmApi->realmIndex('us')->toArray();
         $cache->set($cacheKey, $cached, 3600); // Cache for 1 hour
     }
     

   • Tip: Use Symfony’s CacheInterface or Psr\Cache\CacheItemPoolInterface.

2. Region Support:

   • Only us, eu, kr, and tw are supported. Avoid hardcoding unsupported regions (e.g., cn).

3. Missing Endpoints:

   • Battle.net API and Diablo III/Hearthstone/SC2 are unsupported. For these, use raw HttpClient:

     $client = $this->container->get('http_client');
     $response = $client->request('GET', 'https://api.battle.net/...');
     

4. Authentication:

   • Credentials Leaks: Never commit .env files. Use Symfony’s ParameterBag for sensitive data in tests:

     # config/packages/test/ajardin_blizzard_sdk.yaml
     ajardin_blizzard_sdk:
         blizzard:
             client_id: '%env(resolve:BLIZZARD_CLIENT_ID)%'
             client_secret: '%env(resolve:BLIZZARD_SECRET)%'
     

Debugging

1. Response Errors:

   • Check HTTP status codes:

     if ($response->getStatusCode() === 401) {
         throw new \RuntimeException('Invalid credentials');
     }
     

   • Log raw responses for debugging:

     file_put_contents(
         'debug_blizzard.json',
         $response->getContent(false)
     );
     

2. Deprecation Warnings:

   • The bundle is actively maintained (last release: Dec 2023). Monitor GitHub Issues for breaking changes.

Extension Points

1. Custom API Endpoints:

   • Extend the bundle by creating a new service:

     use Ajardin\BlizzardSdkBundle\BlizzardApi\AbstractApi;
     
     class CustomApi extends AbstractApi {
         public function customEndpoint(string $region, string $locale) {
             return $this->client->request('GET', $this->buildUrl($region, '/custom', $locale));
         }
     }
     

   • Register as a service in services.yaml:

     services:
         App\Service\CustomApi:
             arguments:
                 $client: '@ajardin_blizzard_sdk.http_client'
     

2. Response Transformers:

   • Override response handling with a decorator:

     use Ajardin\BlizzardSdkBundle\BlizzardApi\WorldOfWarcraft\RealmApiInterface;
     
     class RealmApiDecorator implements RealmApiInterface {
         public function __construct(private RealmApiInterface $decorated) {}
     
         public function realmIndex(string $region): ResponseInterface {
             $response = $this->decorated->realmIndex($region);
             return new DecoratedResponse($response); // Custom logic
         }
     }
     

3. Testing:

   • Mock the HttpClient in tests:

     $mockResponse = new MockResponse(json_encode(['realms' => []]));
     $this->httpClient->__call('request', ['GET', '...'], $mockResponse);
     

Performance Tips

1. Batch Requests:

   • Use HttpClient's stream() for parallel requests:

     $promises = [];
     foreach ($realms as $realm) {
         $promises[] = $this->characterProfileApi->characterProfile('us', $realm, 'Paladin');
     }
     $results = yield from $this->httpClient->stream($promises);
     

2. Locale Handling:

   • Always specify locale (e.g., 'en_US', 'ko_KR') to avoid API defaults.

3. Environment-Specific Config:

   • Override config per environment (e.g., config/packages/dev/ajardin_blizzard_sdk.yaml):

     ajardin_blizzard_sdk:
         blizzard:
             debug: true # Enable debug mode
     

---