Php Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require badpixxel/php-sdk
   

   Verify the package loads by checking composer.json for autoloading.

2. First Use Case: Basic Initialization

   use Badpixxel\SDK\Client;
   
   $client = new Client(config([
       'api_key' => env('BADPIXXEL_API_KEY'),
       'base_uri' => env('BADPIXXEL_API_URL', 'https://api.badpixxel.example/v1'),
   ]));
   

   • Key Files: Review src/Client.php and src/Exceptions/ for core logic and error handling.

3. First API Call

   try {
       $response = $client->get('/resources');
       $data = json_decode($response->getBody(), true);
   } catch (\Badpixxel\SDK\Exception\ApiException $e) {
       // Handle API errors
   }
   

   • Documentation: Check for inline PHPDoc comments in the src/ directory (if available).

Implementation Patterns

Workflow: Request Handling

1. Standard Requests

   // GET
   $client->get('/endpoint', ['param' => 'value']);
   
   // POST with JSON body
   $client->post('/endpoint', ['key' => 'value'], [
       'headers' => ['Content-Type' => 'application/json'],
   ]);
   

   • Chaining: Use fluent methods like withHeaders() or withAuth() for reusable configurations.

2. Authentication

   $client->withAuth(env('API_TOKEN'))->get('/protected');
   

   • Token Management: Store tokens in Laravel’s config/services.php or .env.

3. Pagination

   $response = $client->get('/items', ['page' => 1, 'per_page' => 20]);
   $data = json_decode($response->getBody(), true);
   

   • Looping: Use Laravel’s collect($data['items'])->each(...) for pagination handling.

Integration with Laravel

1. Service Provider Binding

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton(Client::class, function ($app) {
           return new Client(config('services.badpixxel'));
       });
   }
   

   • Config: Define in config/services.php:

     'badpixxel' => [
         'api_key' => env('BADPIXXEL_API_KEY'),
         'timeout' => 30,
     ],
     

2. Middleware for API Calls

   // app/Http/Middleware/HandleBadpixxelApi.php
   public function handle($request, Closure $next)
   {
       $client = app(Client::class);
       $response = $client->get('/check-status');
       // Process response or redirect
       return $next($request);
   }
   

3. Events and Observers

   • Trigger custom events (e.g., BadpixxelApiCalled) after each request for logging/auditing.

Gotchas and Tips

Pitfalls

1. Error Handling

   • Issue: Silent failures if exceptions aren’t caught.
   • Fix: Wrap calls in try-catch blocks and log errors:

     catch (\Badpixxel\SDK\Exception\ApiException $e) {
         Log::error('Badpixxel API Error: ' . $e->getMessage());
     }
     

2. Rate Limiting

   • Issue: Unhandled 429 Too Many Requests responses.
   • Fix: Implement exponential backoff:

     if ($response->getStatusCode() === 429) {
         sleep(2 ** $retryCount); // Exponential backoff
     }
     

3. Deprecated Methods

   • Issue: Undocumented breaking changes in minor updates.
   • Fix: Pin the package version in composer.json:

     "badpixxel/php-sdk": "1.0.*"
     

Debugging Tips

1. Enable Guzzle Middleware

   $client = new Client([...], [
       'middleware' => [
           new \GuzzleHttp\Middleware\LogMiddleware(
               new \GuzzleHttp\HandlerStack(),
               new \Psr\Log\NullLogger()
           )
       ]
   ]);
   

   • Log File: Check Laravel’s storage/logs/laravel.log for raw request/response data.

2. Mocking for Tests

   // tests/Feature/BadpixxelTest.php
   public function test_api_call()
   {
       $mockHandler = HandlerStack::create();
       $mockHandler->push(Middleware::tap(function ($request) {
           return new Response(200, [], json_encode(['test' => true]));
       }));
   
       $client = new Client([], ['handler' => $mockHandler]);
       $response = $client->get('/test');
       $this->assertEquals(200, $response->getStatusCode());
   }
   

Extension Points

1. Custom Request Classes

   • Extend Badpixxel\SDK\Request to add domain-specific logic:

     class CustomRequest extends \Badpixxel\SDK\Request {
         public function withCustomHeader()
         {
             return $this->withHeader('X-Custom', 'value');
         }
     }
     

2. Response Decorators

   • Decorate responses for Laravel-specific needs:

     $client->get('/data')->then(function ($response) {
         return collect(json_decode($response->getBody(), true));
     });
     

3. Webhook Handling

   • Use Laravel’s route:webhook to validate and process incoming webhooks:

     Route::post('/badpixxel-webhook', function (Request $request) {
         $payload = $request->json()->all();
         // Verify signature, process payload
     });