Beonpopapibundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require adanfm/beonpopapibundle
   

   Add to config/bundles.php:

   return [
       // ...
       Adanfm\BeOnPopApiBundle\BeOnPopApiBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Adanfm\BeOnPopApiBundle\BeOnPopApiBundle" --tag="config"
   

   Update config/beonpopapi.php with your API credentials:

   return [
       'api_key' => env('BEONPOP_API_KEY'),
       'base_uri' => env('BEONPOP_API_BASE_URI', 'https://api.beonpop.com/v1'),
   ];
   

3. First Use Case: Fetching a Customer Inject the client into a service/controller:

   use Adanfm\BeOnPopApiBundle\Client\BeOnPopApiClient;
   
   class CustomerService {
       protected $client;
   
       public function __construct(BeOnPopApiClient $client) {
           $this->client = $client;
       }
   
       public function getCustomer($id) {
           return $this->client->get('/customers/' . $id);
       }
   }
   

Implementation Patterns

Dependency Injection

• Service Container Binding: The bundle auto-registers BeOnPopApiClient as a singleton. Use constructor injection for type safety:

  public function __construct(BeOnPopApiClient $client) { ... }
  

• Custom Clients: Extend the base client for domain-specific logic:

  class CustomBeOnPopClient extends BeOnPopApiClient {
      public function getCustomerOrders($customerId) {
          return $this->get("/customers/{$customerId}/orders");
      }
  }
  

  Bind it in a service provider:

  $this->app->bind(CustomBeOnPopClient::class, function ($app) {
      return new CustomBeOnPopClient($app->make('config'));
  });
  

API Workflows

1. Pagination Handling Use the paginate() method for collections:

   $orders = $this->client->paginate('/orders', ['limit' => 50]);
   while ($orders->hasMore()) {
       $orders = $this->client->nextPage($orders);
   }
   

2. Webhook Validation Validate incoming webhooks with the validateWebhook method:

   $valid = $this->client->validateWebhook(
       $request->getContent(),
       $request->getHeader('X-Signature')
   );
   

3. Batch Operations Use the batch() method for bulk requests:

   $this->client->batch([
       'get' => ['/orders/1', '/orders/2'],
       'post' => ['/refunds', ['data' => ['order_id' => 1]]],
   ]);
   

Integration Tips

• Laravel Events: Dispatch events for API responses:

  $this->client->onResponse(function ($response) {
      event(new ApiResponseReceived($response));
  });
  

• Caching: Cache frequent API calls with Laravel’s cache:

  $customer = Cache::remember("beonpop_customer_{$id}", now()->addHours(1), function () use ($id) {
      return $this->client->get("/customers/{$id}");
  });
  

• Queue Jobs: Offload long-running API calls to queues:

  dispatch(new SyncBeOnPopOrders($this->client));
  

Gotchas and Tips

Common Pitfalls

1. API Key Exposure

   • Never hardcode api_key in config files. Use Laravel’s .env:

     BEONPOP_API_KEY=your_key_here
     

   • Restrict .env file permissions (chmod 600 .env).

2. Rate Limiting

   • The bundle does not auto-retry on rate limits. Implement exponential backoff:

     try {
         $response = $this->client->get('/orders');
     } catch (RateLimitExceededException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

3. Deprecated Endpoints

   • Monitor the BeOnPop API changelog for breaking changes. Update endpoints in your codebase proactively.

Debugging

• Enable Debug Mode Set debug: true in config/beonpopapi.php to log raw requests/responses:

  'debug' => env('BEONPOP_DEBUG', false),
  

• Logging Middleware Add a middleware to log all API calls:

  $this->client->withMiddleware(function ($request, $next) {
      \Log::debug('BeOnPop Request:', [
          'url' => $request->getUri(),
          'method' => $request->getMethod(),
          'data' => $request->getBody(),
      ]);
      return $next($request);
  });
  

Extension Points

1. Custom HTTP Client Replace the default Guzzle client by binding a custom instance:

   $this->app->bind(BeOnPopApiClient::class, function ($app) {
       $client = new BeOnPopApiClient($app['config']);
       $client->setHttpClient($app->make(CustomGuzzleClient::class));
       return $client;
   });
   

2. Response Transformers Override response handling for specific endpoints:

   $this->client->addTransformer('customers', function ($response) {
       return collect($response->getData())->map(function ($item) {
           $item['formatted_name'] = ucwords($item['name']);
           return $item;
       });
   });
   

3. Webhook Handlers Register custom webhook handlers:

   $this->client->onWebhook('order.created', function ($payload) {
       // Handle order creation
   });
   

Configuration Quirks

• Base URI Overrides Override the base URI per request:

  $this->client->setBaseUri('https://sandbox.beonpop.com/v1')->get('/orders');
  

• Timeouts Configure request timeouts in config/beonpopapi.php:

  'timeout' => [
      'connect' => 5,  // seconds
      'read'    => 10,
  ],
  

• SSL Verification Disable SSL verification only for testing (not production):

  $this->client->setVerifyPeer(false);