Constellation Sdk Laravel Package

Getting Started

Install the package via Composer:

composer require darkmatterfr/constellation-sdk

Publish the configuration file (if needed) with:

php artisan vendor:publish --provider="Darkmatter\ConstellationSdk\ConstellationSdkServiceProvider"

The package now includes exception tracing and type handling, making debugging easier. Start by wrapping API calls in a try-catch block to leverage the new exception details:

use Darkmatter\ConstellationSdk\Exceptions\ConstellationException;

try {
    $response = Constellation::apiCall('endpoint', ['param' => 'value']);
} catch (ConstellationException $e) {
    // Access trace and exception type via $e->getTrace() and $e->getExceptionType()
    logger()->error('Constellation API Error', [
        'trace' => $e->getTrace(),
        'type' => $e->getExceptionType(),
    ]);
}

Implementation Patterns

Exception Handling Workflow

1. Wrap API calls in try-catch blocks to catch ConstellationException.
2. Log structured errors using the new getTrace() and getExceptionType() methods:

   catch (ConstellationException $e) {
       $this->logErrorWithContext($e->getTrace(), $e->getExceptionType());
   }
   

3. Extend exception handling by creating custom listeners for ConstellationException:

   Event::listen(ConstellationException::class, function ($e) {
       // Custom logic (e.g., Slack alerts, retries)
   });
   

Integration with Laravel Logging

Use the package’s exception details in Laravel’s logging channels:

catch (ConstellationException $e) {
    Log::channel('slack')->error('API Failed', [
        'exception' => $e->getExceptionType(),
        'trace' => $e->getTrace(),
    ]);
}

Testing

Mock exceptions in tests to verify error handling:

$mockException = new ConstellationException('Test Error', [], 'API_TIMEOUT');
$this->expectException(ConstellationException::class);
$this->expectExceptionMessage('Test Error');

Gotchas and Tips

New Features

• Exception Tracing: The getTrace() method now returns a structured array of the error’s call stack, useful for debugging.
• Exception Types: Use getExceptionType() (e.g., 'API_TIMEOUT', 'VALIDATION_ERROR') to categorize errors in logs or UI.

Debugging Tips

1. Check Exception Type First:

   if ($e->getExceptionType() === 'API_TIMEOUT') {
       // Retry logic
   }
   

2. Log Full Traces in development:

   logger()->debug('Full trace', ['trace' => $e->getTrace()]);
   

3. Avoid Overriding Core Methods: The package’s exception methods (getTrace(), getExceptionType()) are final; extend via custom exceptions if needed.

Potential Pitfalls

• Backward Compatibility: While this update is non-breaking, older code relying on raw exception messages may need updates to use the new methods.
• Performance: Deep traces can bloat logs; filter sensitive data in production:

  $filteredTrace = collect($e->getTrace())->reject(fn($item) => str_contains($item, 'password'));
  

Extension Points

• Custom Exception Classes: Extend ConstellationException to add domain-specific logic:

  class PaymentConstellationException extends ConstellationException {
      public function getSeverity(): string {
          return 'CRITICAL';
      }
  }
  

• Event Listeners: Subscribe to ConstellationException to trigger workflows (e.g., notifications):

  Event::listen(ConstellationException::class, function ($e) {
      Notification::route('mail', 'admin@example.com')
                  ->notify(new ApiFailure($e));
  });