Client Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dzangocart/client
   

   Ensure your Laravel project meets the PHP version requirement (>=5.3.3).

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

   use DzangoCart\Client;
   
   $client = new Client([
       'api_key' => env('DZANGOCART_API_KEY'),
       'api_secret' => env('DZANGOCART_API_SECRET'),
       'base_uri' => 'https://api.dzangocart.com/v1',
   ]);
   

3. First Request: Fetching Products

   $products = $client->get('/products')->json();
   

Where to Look First

• README.md: Basic usage examples (if expanded).
• Source Code: src/Client.php for core methods (e.g., get(), post()).
• Guzzle Docs: Understand HTTP client behavior (e.g., retries, middleware).

Implementation Patterns

Workflows

1. API Integration Layer Create a Laravel service class to abstract API calls:

   namespace App\Services;
   
   use DzangoCart\Client;
   
   class DzangoCartService {
       protected $client;
   
       public function __construct() {
           $this->client = new Client(config('dzangocart'));
       }
   
       public function fetchProducts() {
           return $this->client->get('/products')->json();
       }
   }
   

2. Request/Response Handling Use Laravel’s HTTP clients for consistency:

   $response = $this->client->post('/orders', [
       'json' => ['items' => $orderData]
   ]);
   $response->raiseForStatus(); // Throw on 4xx/5xx
   

3. Configuration Store credentials in .env and bind to Laravel config:

   // config/dzangocart.php
   return [
       'api_key' => env('DZANGOCART_API_KEY'),
       'api_secret' => env('DZANGOCART_API_SECRET'),
   ];
   

Integration Tips

• Middleware: Extend Guzzle middleware for logging/retries:

  $client->getStack()->push(
      \GuzzleHttp\Middleware::tap(function ($request) {
          logger()->debug('DzangoCart Request:', ['url' => $request->getUri()]);
      })
  );
  

• Events: Dispatch Laravel events on API responses (e.g., DzangoCartOrderCreated).
• Caching: Cache responses with Cache::remember():

  Cache::remember('dzangocart_products', now()->addHours(1), function () {
      return $this->client->get('/products')->json();
  });
  

Gotchas and Tips

Pitfalls

1. Deprecated Guzzle Version

   • The package requires Guzzle ~3.0, which is outdated. Upgrade to Guzzle 6/7+ and fork the package if needed.
   • Workaround: Use a wrapper or replace the dependency in composer.json.

2. No Rate Limiting

   • No built-in rate limiting. Implement middleware or use Laravel’s throttle middleware.

3. Lack of Type Safety

   • Responses are raw JSON. Use Laravel’s collect() or json_decode with strict typing:

     $products = collect($response->json())->mapInto(Product::class);
     

Debugging

• Enable Guzzle Debugging:

  $client->getStack()->push(
      \GuzzleHttp\Middleware::log(\Psr\Log\LogLevel::DEBUG, new \Monolog\Logger('guzzle'))
  );
  

• Check Headers: Ensure Authorization headers are set correctly (e.g., Bearer token).

Extension Points

1. Custom Endpoints Extend the client class to add domain-specific methods:

   class ExtendedClient extends Client {
       public function createOrder(array $data) {
           return $this->post('/orders', ['json' => $data]);
       }
   }
   

2. Webhook Handling Use Laravel’s HandleIncomingWebhook trait or a dedicated route:

   Route::post('/dzangocart/webhook', [DzangoCartWebhookController::class, 'handle']);
   

3. Testing Mock the client in tests:

   $mock = Mockery::mock(DzangoCart\Client::class);
   $mock->shouldReceive('get')->andReturn((object)['json' => fn() => []]);
   

Config Quirks

• API Secret Handling: The package uses pcrypt for secret storage. Ensure the opichon/pcrypt package is installed.
• Base URI: Override the base URI dynamically for staging/production:

  $client = new Client([
      'base_uri' => config('app.env') === 'production'
          ? 'https://api.dzangocart.com/v1'
          : 'https://staging.dzangocart.com/v1',
  ]);