Currency Api Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bigoen/currency-api-bundle
   

   Enable the bundle in config/bundles.php:

   Bigoen\CurrencyApiBundle\BigoenCurrencyApiBundle::class => ['all' => true],
   

2. Configure API Key: Add to .env:

   CURRENCY_BEACON_API_KEY=your_api_key_here
   

3. First Use Case: Inject CurrencyBeaconService into a controller/service and fetch currencies:

   use Bigoen\CurrencyApiBundle\Service\CurrencyBeaconService;
   
   class CurrencyController extends AbstractController
   {
       public function __construct(private CurrencyBeaconService $currencyService) {}
   
       public function index(): Response
       {
           $currencies = $this->currencyService->getCurrencies();
           return $this->json($currencies);
       }
   }
   

Implementation Patterns

Core Workflows

1. Automated Updates: Schedule console commands via cron or Symfony’s CronExpression:

   # config/packages/schedule.yaml
   schedule:
       update_currencies:
           command: 'exchange-rate:currency-beacon:currency-update'
           every: '1 day'
   

2. Service Integration: Use dependency injection for reusable logic:

   class OrderService
   {
       public function __construct(
           private CurrencyBeaconService $currencyService,
           private EntityManagerInterface $em
       ) {}
   
       public function calculateTotal(float $amount, string $currency): float
       {
           $rate = $this->currencyService->getLatestRate('USD', $currency);
           return $amount * $rate;
       }
   }
   

3. Historical Data: Fetch historical rates for reporting:

   $rates = $this->currencyService->getHistoricalRates('EUR', 'USD', '2024-01-01');
   

4. Caching: Leverage Symfony’s cache system to reduce API calls:

   $this->currencyService->setCacheLifetime(3600); // 1 hour
   

Gotchas and Tips

Pitfalls

1. API Rate Limits:

   • Monitor CURRENCY_BEACON_API_KEY usage. Implement retry logic for 429 responses:

     try {
         $this->currencyService->updateDailyExchangeRates();
     } catch (RateLimitExceededException $e) {
         sleep(60); // Wait and retry
         retry();
     }
     

2. Data Freshness:

   • Default updates may not reflect real-time changes. Use updateCurrencies() manually if needed.

3. Environment-Specific Config:

   • Override .env values per environment (e.g., .env.test for staging keys).

Debugging

• Enable Debug Mode:

  $this->currencyService->setDebug(true); // Logs API responses to `var/log/currency_api.log`
  

• Validate API Key: Test connectivity with:

  php bin/console debug:container bigoen_currency_api_bundle.service
  

Extension Points

1. Custom Endpoints: Extend the service to support additional API endpoints:

   class CustomCurrencyService extends CurrencyBeaconService
   {
       public function getCustomEndpointData(): array
       {
           return $this->httpClient->get('https://api.example.com/custom');
       }
   }
   

2. Database Storage: Override default storage (Doctrine entities) by implementing CurrencyStorageInterface:

   class CustomStorage implements CurrencyStorageInterface
   {
       public function saveCurrencies(array $currencies): void
       {
           // Custom logic (e.g., Elasticsearch, Redis)
       }
   }
   

3. Event Listeners: Subscribe to currency.updated events for post-update actions:

   use Bigoen\CurrencyApiBundle\Event\CurrencyUpdatedEvent;
   
   class CurrencyListener
   {
       public function onCurrencyUpdated(CurrencyUpdatedEvent $event): void
       {
           // Notify users or update UI
       }
   }