Ebis Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require milestone/ebis
   

   Publish the configuration (if available):

   php artisan vendor:publish --provider="Milestone\eBis\eBisServiceProvider"
   

   Check config/ebis.php for API credentials, endpoints, or default settings.

2. Basic Usage The package likely wraps eBis API calls. Start with the client initialization:

   use Milestone\eBis\Facades\eBis;
   
   $client = eBis::client(['api_key' => 'your_key_here']);
   

   Verify the facade/class structure in src/ or facades/.

3. First API Call Example: Fetch a report or entity (adjust based on package docs):

   $response = $client->get('/reports/123');
   $data = $response->json();
   

   Check the src/Client.php or src/HttpClient.php for available methods.

Where to Look First

• src/: Core logic (client, models, exceptions).
• config/ebis.php: Default settings (API endpoints, timeouts, etc.).
• tests/: Example usage and edge cases.
• README.md: May include quick-start examples (though minimal for this package).

First Use Case

Scenario: Fetch and display a customer’s order history.

$client = eBis::client(['api_key' => config('ebis.api_key')]);
$orders = $client->get('/customers/123/orders')->json();

// Process orders (e.g., loop and store in DB)
foreach ($orders['data'] as $order) {
    Order::create([
        'customer_id' => 123,
        'ebis_order_id' => $order['id'],
        'amount' => $order['total'],
    ]);
}

Implementation Patterns

Common Workflows

1. API Client Initialization Reuse the client across requests (avoid re-authenticating):

   $client = eBis::client(['api_key' => config('ebis.api_key')]);
   

2. Handling Responses Normalize responses with a helper:

   $response = $client->get('/entities');
   if ($response->successful()) {
       return response()->json($response->json());
   }
   throw new \Exception($response->error());
   

3. Pagination If the API supports pagination, implement a loop:

   $page = 1;
   do {
       $response = $client->get("/entities?page=$page");
       $data = $response->json();
       // Process $data['data']
       $page = $data['next_page'] ?? null;
   } while ($page);
   

4. Webhook Listeners If eBis supports webhooks, create a listener:

   // In EventServiceProvider
   $this->listenForWebhooks();
   

Integration Tips

• Laravel Services: Bind the client to the container for dependency injection:

  $this->app->singleton('ebis.client', function () {
      return eBis::client(['api_key' => config('ebis.api_key')]);
  });
  

• Queues: Offload heavy API calls to queues:

  SyncEbisData::dispatch($client, $entityId)->onQueue('ebis');
  

• Caching: Cache frequent API responses:

  $data = Cache::remember("ebis_report_{$reportId}", now()->addHours(1), function () use ($client, $reportId) {
      return $client->get("/reports/$reportId")->json();
  });
  

• Events: Trigger Laravel events after API calls:

  event(new EbisDataFetched($data));
  

Testing Patterns

• Mock the Client: Use Laravel’s HTTP testing or Mockery:

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

• Test Responses: Validate API responses in feature tests:

  $response = $this->get('/api/ebis-data');
  $response->assertJsonStructure(['data' => ['id', 'name']]);
  

Gotchas and Tips

Common Pitfalls

1. API Key Management

   • Gotcha: Hardcoding API keys in code (use .env).
   • Fix: Store in config/ebis.php and reference via config('ebis.api_key').

2. Rate Limiting

   • Gotcha: eBis may throttle requests. Implement retries:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     
     $client = new RetryableHttpClient(
         eBis::client()->getHttpClient(),
         [
             'max_retries' => 3,
             'delay' => 1000,
         ]
     );
     

3. Deprecated Methods

   • Gotcha: The package is outdated (last release 2022). Check for breaking changes.
   • Fix: Override methods in a service class:

     class CustomEbisClient extends \Milestone\eBis\Client {
         public function get($endpoint) {
             // Custom logic
         }
     }
     

4. Error Handling

   • Gotcha: Generic exceptions. Catch specific ones:

     try {
         $response = $client->get('/invalid-endpoint');
     } catch (\Milestone\eBis\Exceptions\ApiException $e) {
         Log::error($e->getMessage());
     }
     

Debugging Tips

• Log Requests/Responses:

  $client->getHttpClient()->getProgressiveLogger()->tap(
      fn($log) => Log::debug('eBis API Call', ['log' => $log])
  );
  

• Enable Verbose Output: Add to config/ebis.php:

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

• Check Headers: Ensure headers like Accept: application/json are set:

  $client->withOptions(['headers' => ['Accept' => 'application/json']]);
  

Extension Points

1. Custom Endpoints Extend the client to add missing endpoints:

   class ExtendedEbisClient extends \Milestone\eBis\Client {
       public function customEndpoint($params) {
           return $this->request('GET', '/custom', $params);
       }
   }
   

2. Middleware Add request/response middleware:

   $client->getHttpClient()->getEventDispatcher()->addListener(
       'request',
       fn($event) => $event->getRequest()->headers->set('X-Custom-Header', 'value')
   );
   

3. Models If the package includes Eloquent models, extend them:

   class CustomEbisModel extends \Milestone\eBis\Models\EbisModel {
       protected $casts = ['created_at' => 'datetime:Y-m-d H:i:s'];
   }
   

4. Service Providers Override bindings in a service provider:

   $this->app->bind('ebis.client', fn() => new CustomEbisClient());
   

Configuration Quirks

• Default Endpoint: Check if the package uses a default endpoint (e.g., config('ebis.api_url')).
• Timeouts: Adjust in config/ebis.php:

  'timeout' => 30, // seconds
  

• SSL Verification: Disable if needed (not recommended for production):

  $client->withOptions(['verify_peer' => false]);