Absence Io Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require chaplean/absence-io-client-bundle
   

   Add the bundle to AppKernel.php:

   new Chaplean\Bundle\AbsenceIoClientBundle\ChapleanAbsenceIoClientBundle(),
   

2. Configuration:

   • Import config in config.yml:

     imports:
         - { resource: '@ChapleanAbsenceIoClientBundle/Resources/config/config.yml' }
     

   • Set API credentials in parameters.yml:

     chaplean_absence_io_client.hawk_id: 'your_hawk_id'
     chaplean_absence_io_client.hawk_key: 'your_hawk_key'
     

3. First Use Case: Inject the client service into a controller or service:

   use Chaplean\Bundle\AbsenceIoClientBundle\Client\AbsenceIoClientInterface;
   
   class MyController extends Controller
   {
       public function __construct(AbsenceIoClientInterface $absenceIoClient)
       {
           $this->absenceIoClient = $absenceIoClient;
       }
   
       public function fetchAbsences()
       {
           $response = $this->absenceIoClient->get('/absences');
           return $this->json($response);
       }
   }
   

Implementation Patterns

Common Workflows

1. Fetching Data: Use the client to retrieve absence records:

   $absences = $this->absenceIoClient->get('/absences', [
       'start_date' => '2023-01-01',
       'end_date' => '2023-12-31',
   ]);
   

2. Creating/Updating Records: Send POST/PUT requests with payloads:

   $newAbsence = [
       'employee_id' => 123,
       'start_date' => '2023-10-01',
       'end_date' => '2023-10-05',
       'reason' => 'Sick leave',
   ];
   $this->absenceIoClient->post('/absences', $newAbsence);
   

3. Handling Responses: Parse JSON responses:

   $response = $this->absenceIoClient->get('/absences/1');
   $absenceData = json_decode($response->getBody(), true);
   

4. Error Handling: Check HTTP status codes:

   try {
       $response = $this->absenceIoClient->delete('/absences/1');
       if ($response->getStatusCode() !== 204) {
           throw new \RuntimeException('Failed to delete absence');
       }
   } catch (\Exception $e) {
       // Log or handle error
   }
   

Integration Tips

• Symfony Events: Trigger events (e.g., absence.created) after API calls.
• Doctrine Integration: Map API responses to Doctrine entities for seamless ORM usage.
• Caching: Cache frequent API calls using Symfony’s cache system.
• Logging: Log API requests/responses for debugging:

  # config/services.yml
  Chaplean\Bundle\AbsenceIoClientBundle\Client\AbsenceIoClient:
      arguments:
          - '@logger'
  

Gotchas and Tips

Pitfalls

1. Authentication:

   • Ensure hawk_id and hawk_key are correctly set in parameters.yml.
   • Verify the Hawk authentication library (php-hawk) is installed:

     composer require php-hawk
     

2. API Rate Limits:

   • Monitor HTTP 429 responses (Too Many Requests). Implement retries with exponential backoff:

     $this->absenceIoClient->setRetryStrategy(new RetryStrategy(3, 100));
     

3. Data Validation:

   • Validate payloads before sending (e.g., using Symfony Validator):

     $validator = $this->container->get('validator');
     $errors = $validator->validate($absenceData);
     if (count($errors) > 0) {
         throw new \InvalidArgumentException('Invalid absence data');
     }
     

4. Deprecation:

   • The bundle is unmaintained (0 stars, no recent commits). Test thoroughly and consider forking if critical.

Debugging

• Enable Debug Mode:

  # config/packages/dev/absence_io.yml
  chaplean_absence_io_client:
      debug: true
  

  This logs raw requests/responses to var/log/absence_io.log.

• Check Headers: Inspect the Authorization header for Hawk credentials:

  $response = $this->absenceIoClient->get('/absences', [], [
      'headers' => ['Accept' => 'application/json'],
  ]);
  

Extension Points

1. Custom HTTP Client: Override the default client (e.g., Guzzle) by binding a custom service:

   # config/services.yml
   services:
       App\Custom\AbsenceIoClient:
           arguments:
               - '@http_client' # Your custom HTTP client
   

2. Middleware: Add middleware for request/response transformation:

   $this->absenceIoClient->addMiddleware(new MyMiddleware());
   

3. Event Listeners: Subscribe to events (e.g., absence.io.response) for post-processing:

   $dispatcher->addListener('absence.io.response', function ($event) {
       $response = $event->getResponse();
       // Custom logic
   });
   

4. Configuration Overrides: Extend the bundle’s configuration in config/packages/absence_io.yml:

   chaplean_absence_io_client:
       base_uri: 'https://custom-api.absence.io'
       timeout: 30