Php Pwinty Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require pwinty/php-pwinty
   

   Verify the package is autoloaded in composer.json under "autoload": { "psr-4": { ... } }.

2. First Use Case: Authentication Initialize the client with your API credentials:

   use Pwinty\Client;
   
   $client = new Client('YOUR_API_KEY', 'YOUR_API_SECRET');
   

   Store credentials securely in .env (e.g., PWINTY_API_KEY, PWINTY_API_SECRET).

3. First API Call: Fetch Orders

   $orders = $client->orders()->all();
   

   Check the Pwinty API docs for available endpoints.

Implementation Patterns

Workflows

1. Order Management

   • Fetch, create, or update orders:

     // Fetch a single order
     $order = $client->orders()->find(123);
     
     // Create a new order
     $newOrder = $client->orders()->create([
         'product_id' => 456,
         'quantity' => 2,
     ]);
     

   • Use Laravel’s Service Provider to bind the client for dependency injection:

     $this->app->singleton(Client::class, function ($app) {
         return new Client(
             $app['config']['services.pwinty.key'],
             $app['config']['services.pwinty.secret']
         );
     });
     

2. Webhook Handling

   • Validate and process Pwinty webhooks in a Laravel route:

     Route::post('/pwinty/webhook', function (Request $request) {
         $client = app(Client::class);
         $webhook = $client->webhooks()->validate($request->input());
     
         if ($webhook->isValid()) {
             // Process the webhook (e.g., update inventory)
         }
     });
     

   • Store webhook secrets in config/services.php:

     'pwinty' => [
         'webhook_secret' => env('PWINTY_WEBHOOK_SECRET'),
     ],
     

3. Batch Operations

   • Use pagination for large datasets:

     $orders = $client->orders()->all(['per_page' => 100]);
     while ($orders->hasMore()) {
         $orders = $client->orders()->nextPage($orders);
     }
     

Integration Tips

• Laravel Queues: Offload API calls to queues for long-running tasks (e.g., bulk order updates).
• Logging: Log API responses for debugging:

  $client->setLogger(new Monolog\Logger('pwinty'));
  

• Testing: Mock the client in PHPUnit:

  $mock = $this->createMock(Client::class);
  $mock->method('orders')->willReturnSelf();
  $mock->method('all')->willReturn([...]);
  

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • The repository is archived, so expect no updates. Fork or maintain a local copy if critical.
   • Monitor for breaking changes in the Pwinty API.

2. Rate Limiting

   • Pwinty enforces rate limits. Implement exponential backoff:

     try {
         $response = $client->orders()->all();
     } catch (RateLimitExceededException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

3. Webhook Validation

   • Always validate webhook signatures:

     if (!$client->webhooks()->validate($request->input())) {
         abort(403, 'Invalid webhook signature');
     }
     

Debugging

• Enable Debug Mode:

  $client->setDebug(true); // Logs raw API requests/responses
  

• Check HTTP Status Codes:
  • Handle 4xx/5xx errors gracefully:

    try {
        $client->orders()->find(123);
    } catch (ApiException $e) {
        Log::error("Pwinty API Error: {$e->getMessage()}", ['response' => $e->getResponse()]);
    }
    

Extension Points

1. Custom Endpoints

   • Extend the client for undocumented endpoints:

     class CustomClient extends Client {
         public function customEndpoint() {
             return $this->request('GET', '/custom-path');
         }
     }
     

2. Middleware

   • Add request/response middleware:

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

3. Configuration

   • Override default API base URL (if Pwinty changes endpoints):

     $client = new Client($key, $secret, 'https://custom.pwinty.com/api');