Gar Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require edumedia/gar-api-bundle
   

   Register the bundle in config/app.php under providers:

   Edumedia\GarApiBundle\GarApiBundle::class,
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Edumedia\GarApiBundle\GarApiBundle" --tag="config"
   

   Update .env with your GAR API credentials (e.g., GAR_API_KEY, GAR_API_URL).

3. First Use Case Inject the GarApiClient into a service/controller:

   use Edumedia\GarApiBundle\Client\GarApiClient;
   
   class MyController extends Controller
   {
       public function __construct(private GarApiClient $garApi)
       {
       }
   
       public function fetchUserData()
       {
           $response = $this->garApi->get('/users/123');
           return response()->json($response);
       }
   }
   

Implementation Patterns

Common Workflows

1. API Requests Use the client for standard HTTP methods:

   $this->garApi->get('/endpoint', ['param' => 'value']);
   $this->garApi->post('/endpoint', ['data' => 'payload']);
   $this->garApi->put('/endpoint', ['data' => 'payload']);
   $this->garApi->delete('/endpoint');
   

2. Authentication Attach tokens automatically via middleware (if configured):

   // In config/gar_api.php
   'auth' => [
       'header' => 'X-API-Key',
       'value' => env('GAR_API_KEY'),
   ],
   

3. Response Handling Parse responses with built-in helpers:

   $response = $this->garApi->get('/users');
   $users = $response->getData(); // Parsed JSON
   $status = $response->getStatusCode();
   

4. Pagination Handle paginated results:

   $response = $this->garApi->get('/users', ['page' => 1, 'limit' => 10]);
   $users = $response->getData();
   $total = $response->getHeader('X-Total-Count');
   

5. Webhooks (If Supported) Configure webhook endpoints in config/gar_api.php:

   'webhooks' => [
       'endpoint' => '/api/gar/webhook',
       'events' => ['user.created', 'order.paid'],
   ],
   

Integration Tips

• Laravel HTTP Client Extend the bundle’s client for custom logic:

  $this->garApi->extend(function ($client) {
      $client->withOptions(['debug' => true]);
  });
  

• Service Layer Create a dedicated service for GAR operations:

  class GarUserService
  {
      public function __construct(private GarApiClient $garApi) {}
  
      public function createUser(array $data)
      {
          return $this->garApi->post('/users', $data);
      }
  }
  

• Testing Mock the client in tests:

  $mock = Mockery::mock(GarApiClient::class);
  $mock->shouldReceive('get')->andReturn(new GarResponse(['data' => []], 200));
  

Gotchas and Tips

Pitfalls

1. Rate Limiting The API may throttle requests. Implement retry logic:

   $this->garApi->withRetry(3, 500)->get('/endpoint');
   

2. Deprecated Endpoints Check the GAR API docs for breaking changes. The bundle may not auto-update endpoints.

3. Caching Responses Avoid caching sensitive data (e.g., tokens). Use Cache::remember for non-sensitive endpoints:

   Cache::remember('gar_users', now()->addHours(1), function () {
       return $this->garApi->get('/users')->getData();
   });
   

4. Error Handling Customize error responses in config/gar_api.php:

   'exceptions' => [
       '429' => \Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException::class,
   ],
   

Debugging

• Enable Logging Add to config/gar_api.php:

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

  Logs will appear in storage/logs/laravel.log.

• HTTP Dump Use Laravel’s HTTP client debug tools:

  $this->garApi->withDebug()->get('/endpoint');
  

Extension Points

1. Custom Responses Extend GarResponse for domain-specific parsing:

   class CustomGarResponse extends GarResponse
   {
       public function getUser()
       {
           return $this->getData()['user'];
       }
   }
   

2. Middleware Add middleware to the client:

   $this->garApi->withMiddleware(new CustomGarMiddleware());
   

3. Event Dispatching Trigger events on API responses:

   $this->garApi->onResponse(function ($response) {
       event(new GarApiResponseEvent($response));
   });
   

Configuration Quirks

• Base URL Override Set dynamically in runtime:

  $this->garApi->setBaseUrl('https://custom-gar-api.com');
  

• Timeouts Adjust in config:

  'timeout' => 30, // seconds