Imasys Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require comsolit/imasys-php
   

   Add the service provider to config/app.php under providers:

   Comsolit\Imasys\ImasysServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Comsolit\Imasys\ImasysServiceProvider" --tag="imasys-config"
   

   Update config/imasys.php with your API credentials (client ID, secret, and endpoint).

3. First Use Case: Authentication Authenticate via the facade:

   use Comsolit\Imasys\Facades\Imasys;
   
   $token = Imasys::auth()->getToken();
   

Implementation Patterns

Workflow: API Integration

1. Service Initialization Use dependency injection or the facade to instantiate the client:

   // In a controller/service
   public function __construct(private ImasysClient $imasys) {}
   
   // Or via facade
   $response = Imasys::endpoint('patients')->get();
   

2. CRUD Operations

   • Create:

     $patient = Imasys::endpoint('patients')->create([
         'firstName' => 'John',
         'lastName' => 'Doe'
     ]);
     

   • Read:

     $patients = Imasys::endpoint('patients')->get(['limit' => 10]);
     

   • Update:

     Imasys::endpoint('patients/{id}')->update(['status' => 'active']);
     

   • Delete:

     Imasys::endpoint('patients/{id}')->delete();
     

3. Pagination Handling Loop through paginated results:

   $patients = Imasys::endpoint('patients')->get();
   foreach ($patients->getCollection() as $patient) {
       // Process each patient
   }
   

4. Error Handling Wrap API calls in a try-catch:

   try {
       $response = Imasys::endpoint('patients')->get();
   } catch (ImasysException $e) {
       Log::error('Imasys API Error: ' . $e->getMessage());
       return response()->json(['error' => 'Failed to fetch data'], 500);
   }
   

Integration Tips

• Laravel Events: Trigger events after successful API calls:

  event(new PatientCreated($patient));
  

• Queues: Offload long-running API operations to queues:

  dispatch(new SyncPatientsJob());
  

• Testing: Mock the client in PHPUnit:

  $this->mock(Imasys::class)->shouldReceive('endpoint')->andReturnSelf();
  

Gotchas and Tips

Pitfalls

1. Token Expiry

   • The package does not auto-refresh tokens. Handle 401 Unauthorized responses by re-authenticating:

     if ($response->status() === 401) {
         Imasys::auth()->refreshToken();
         return $this->handleRequest(); // Retry the request
     }
     

2. Rate Limiting

   • Monitor HTTP 429 Too Many Requests responses. Implement exponential backoff:

     if ($response->status() === 429) {
         sleep($retryAfter ?? 1);
         return $this->handleRequest();
     }
     

3. Endpoint Caching

   • Avoid caching responses with sensitive data (e.g., tokens, PII). Use Cache::forget() when needed.

Debugging

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

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

• Log Requests Use Laravel’s logging to track API calls:

  Imasys::setLogger(function ($message) {
      Log::debug($message);
  });
  

Extension Points

1. Custom Endpoints Extend the ImasysClient to add domain-specific endpoints:

   class CustomImasysClient extends ImasysClient {
       public function customEndpoint() {
           return $this->request('GET', '/custom');
       }
   }
   

2. Middleware Add middleware to modify requests/responses:

   Imasys::middleware(function ($request) {
       $request->header('X-Custom-Header', 'value');
   });
   

3. Response Transformation Override the default response handling:

   Imasys::transformer(function ($response) {
       return $response->json()['data'];
   });
   

Config Quirks

• Base URL: Ensure the base_url in config/imasys.php ends with a trailing slash (/).
• Timeouts: Adjust connect_timeout and timeout in the config for slow networks:

  'timeout' => 30, // seconds
  'connect_timeout' => 5,