Php Client Laravel Package

Getting Started

Minimal Setup

1. Install the package via Composer:

   composer require blitzr/php-client
   

2. Obtain an API key from Blitzr.io.
3. Initialize the client in a Laravel service provider or controller:

   use Blitzr\BlitzrClient;
   
   $blitzr = new BlitzrClient(config('services.blitzr.api_key'));
   

   • Store the API key in config/services.php for security:

     'blitzr' => [
         'api_key' => env('BLITZR_API_KEY'),
     ],
     

First Use Case: Fetching Artist Data

$artist = $blitzr->getArtist('year-of-no-light');

• Expected output: An array/object containing artist metadata (e.g., name, tracks, albums).
• Verify response:

  if ($artist) {
      dd($artist['name']); // Output: "Year of No Light"
  }
  

Laravel Integration

• Service Provider: Bind the client to the container in AppServiceProvider:

  public function register()
  {
      $this->app->singleton(BlitzrClient::class, function ($app) {
          return new BlitzrClient(config('services.blitzr.api_key'));
      });
  }
  

• Usage in Controllers:

  use Blitzr\BlitzrClient;
  
  public function showArtist(BlitzrClient $blitzr, $artistName)
  {
      $artist = $blitzr->getArtist($artistName);
      return view('artist', compact('artist'));
  }
  

Implementation Patterns

Common Workflows

1. Fetching Tracks/Albums:

   $tracks = $blitzr->getArtistTracks('year-of-no-light');
   $albums = $blitzr->getArtistAlbums('year-of-no-light');
   

   • Pagination: Use getArtistTracks($name, $page = 1) to handle paginated results.

2. Search Functionality:

   $results = $blitzr->search('darkwave');
   

   • Filter results by type (e.g., results['artists'], results['tracks']).

3. Error Handling:

   • Wrap API calls in a try-catch block:

     try {
         $artist = $blitzr->getArtist('invalid-name');
     } catch (\Blitzr\Exceptions\ApiException $e) {
         Log::error($e->getMessage());
         return response()->json(['error' => 'Artist not found'], 404);
     }
     

Laravel-Specific Patterns

• API Resources: Transform Blitzr responses into Laravel API Resources:

  namespace App\Http\Resources;
  
  use Illuminate\Http\Resources\Json\JsonResource;
  
  class ArtistResource extends JsonResource
  {
      public function toArray($request)
      {
          return [
              'name' => $this->name,
              'tracks_count' => count($this->tracks),
          ];
      }
  }
  

  • Usage:

    return new ArtistResource($blitzr->getArtist('year-of-no-light'));
    

• Caching Responses: Use Laravel’s cache to avoid redundant API calls:

  $artist = Cache::remember("blitzr_artist_{$artistName}", now()->addHours(1), function () use ($blitzr, $artistName) {
      return $blitzr->getArtist($artistName);
  });
  

• Queueing Long-Running Tasks: Dispatch a job for heavy operations (e.g., fetching all tracks for an artist):

  FetchArtistTracksJob::dispatch($blitzr, $artistName);
  

Gotchas and Tips

Pitfalls

1. API Key Exposure:

   • Never hardcode the API key in files. Always use Laravel’s .env and config/services.php.
   • Restrict access: Ensure the .env file is in your .gitignore.

2. Rate Limiting:

   • Blitzr may throttle requests. Implement exponential backoff for retries:

     use Symfony\Component\Process\Exception\TimeoutException;
     
     try {
         $artist = $blitzr->getArtist($name);
     } catch (TimeoutException $e) {
         sleep(2); // Wait before retrying
         retry();
     }
     

3. Deprecated Methods:

   • Check the Blitzr API reference for deprecated endpoints. The PHP client may not always reflect breaking changes immediately.

4. Response Format:

   • Responses may vary (e.g., stdClass vs. associative arrays). Normalize them:

     $artist = json_decode(json_encode($blitzr->getArtist($name)), true);
     

Debugging

• Enable Debug Mode:

  $blitzr = new BlitzrClient('api_key', ['debug' => true]);
  

  • Logs HTTP requests/responses to storage/logs/blitzr.log.

• Validate API Responses: Use Laravel’s Validator to check required fields:

  $validator = Validator::make($artist, [
      'name' => 'required|string',
      'tracks' => 'array',
  ]);
  

Extension Points

1. Custom Endpoints:

   • Extend the client to support undocumented endpoints:

     class ExtendedBlitzrClient extends BlitzrClient
     {
         public function getCustomData($endpoint)
         {
             return $this->request('GET', "/api/{$endpoint}");
         }
     }
     

2. Middleware:

   • Add request/response middleware for logging or modifying payloads:

     $blitzr->getMiddleware()->push(function ($request) {
         $request->headers->set('X-Custom-Header', 'value');
     });
     

3. Testing:

   • Mock the client in PHPUnit:

     $mock = Mockery::mock(BlitzrClient::class);
     $mock->shouldReceive('getArtist')
          ->once()
          ->andReturn(['name' => 'Mock Artist']);
     

   • Use Laravel’s Http facade to stub HTTP calls:

     Http::fake([
         'api.blitzr.io/*' => Http::response(['name' => 'Mock Artist']),
     ]);
     

Configuration Quirks

• Base URL:

  • Override the default API URL if Blitzr changes it:

    $blitzr = new BlitzrClient('api_key', ['base_url' => 'https://custom.blitzr.io']);
    

• Timeouts:

  • Adjust timeout settings for slow connections:

    $blitzr = new BlitzrClient('api_key', ['timeout' => 30]);
    

Pro Tips

1. Batch Processing:

   • Use Laravel’s collect() to process large datasets efficiently:

     collect($blitzr->getArtistTracks('year-of-no-light'))
         ->each(function ($track) {
             // Process each track
         });
     

2. Webhooks:

   • If Blitzr supports webhooks, create a Laravel route to handle them:

     Route::post('/blitzr-webhook', function (Request $request) {
         $payload = $request->json()->all();
         // Process webhook data
     });
     

3. Documentation Sync:

   • Cross-reference the Blitzr API reference with the PHP client’s source code to understand undocumented features or edge cases.