Laravel Package Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alfaexchange/laravel-package
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="AlfaExchange\LaravelPackage\PackageServiceProvider"
   

2. Configuration Edit .env or config/alfaexchange.php with your API credentials:

   ALFAEXCHANGE_API_KEY=your_api_key_here
   ALFAEXCHANGE_API_SECRET=your_api_secret_here
   

3. First Use Case: Fetching Market Data

   use AlfaExchange\LaravelPackage\Facades\AlfaExchange;
   
   $markets = AlfaExchange::markets()->get();
   

Key Entry Points

• Facade: AlfaExchange (for quick access to API endpoints).
• Service Container: Bind the client manually if extending functionality.
• Config: config('alfaexchange') for runtime settings.

Implementation Patterns

Common Workflows

1. Authenticated Requests Use the facade to handle OAuth2 token management:

   $account = AlfaExchange::account()->get();
   

2. Pagination & Rate Limiting Handle paginated responses with ->paginate() or ->cursor():

   $orders = AlfaExchange::orders()->paginate(10);
   

   Retry failed requests with exponential backoff:

   try {
       $response = AlfaExchange::trades()->get();
   } catch (\AlfaExchange\Exceptions\RateLimitExceeded $e) {
       sleep($e->retryAfter);
       retry();
   }
   

3. Webhook Integration Validate incoming webhooks via the AlfaExchange\LaravelPackage\Webhook class:

   use AlfaExchange\LaravelPackage\Webhook;
   
   $payload = request()->all();
   $webhook = new Webhook($payload);
   if ($webhook->isValid()) {
       // Process event
   }
   

4. Custom Endpoints Extend the client for undocumented endpoints:

   $client = app(\AlfaExchange\LaravelPackage\Client::class);
   $response = $client->get('/undocumented/endpoint', ['param' => 'value']);
   

Integration Tips

• Queue Delayed Jobs: Use Laravel queues for rate-limited endpoints:

  \Queue::later(now()->addSeconds(10), fn() => $this->processAlfaExchangeData());
  

• Caching: Cache frequent requests (e.g., market data) with Laravel’s cache:

  $markets = Cache::remember('alfaexchange_markets', now()->addHours(1), fn() =>
      AlfaExchange::markets()->get()
  );
  

• Testing: Mock the client in tests:

  $this->app->instance(\AlfaExchange\LaravelPackage\Client::class, Mockery::mock());
  

Gotchas and Tips

Pitfalls

1. Deprecated API

   • The last release was in 2022-02-04. Verify endpoints against alfaexchange.io API docs for breaking changes.
   • Example: Some endpoints may require updated headers or payloads.

2. Error Handling

   • Custom exceptions (\AlfaExchange\Exceptions\*) may not cover all cases. Wrap calls in try-catch:

     try {
         $response = AlfaExchange::orders()->get();
     } catch (\Exception $e) {
         Log::error("AlfaExchange API failed: " . $e->getMessage());
         abort(503);
     }
     

3. Rate Limits

   • Default rate limits may throttle requests. Monitor responses for X-RateLimit-Remaining headers.

4. Webhook Validation

   • Always validate webhook signatures:

     if (!$webhook->isValid()) {
         abort(403, 'Invalid webhook signature');
     }
     

Debugging Tips

• Enable Debug Mode: Set ALFAEXCHANGE_DEBUG=true in .env to log raw API responses.
• Log Requests: Use Laravel’s tap to inspect requests:

  AlfaExchange::markets()->get()->tap(fn($response) => Log::debug($response));
  

• Check Headers: Ensure Authorization and Content-Type headers are correct:

  $client->withHeaders(['Authorization' => 'Bearer ' . $token]);
  

Extension Points

1. Custom Middleware Add middleware to the client for logging or auth:

   $client->withMiddleware(new \AlfaExchange\LaravelPackage\Middleware\LogRequests);
   

2. Event Listeners Listen for webhook events:

   event(new \AlfaExchange\Events\OrderFilled($webhook->payload));
   

3. Service Provider Binding Override the default client binding in your AppServiceProvider:

   $this->app->bind(\AlfaExchange\LaravelPackage\Client::class, fn($app) => new CustomAlfaClient());
   

4. Testing Utilities Extend the package’s test helpers for custom assertions:

   $this->assertAlfaExchangeResponse($response, 200, 'success');