Alpha Vantage Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cheesaw/alpha-vantage-bundle
   

   Add the bundle to config/bundles.php:

   CheeSaW\AlphaVantageBundle\AlphaVantageBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference CheeSaWAlphaVantageBundle
   

   Update config/packages/cheesaw_alpha_vantage.yaml with your Alpha Vantage API key:

   cheesaw_alpha_vantage:
       api_key: '%env(ALPHA_VANTAGE_API_KEY)%'
       base_url: 'https://www.alphavantage.co/query'
   

3. First Use Case Fetch real-time stock data (e.g., AAPL):

   use CheeSaW\AlphaVantageBundle\Service\AlphaVantageService;
   
   class StockController extends AbstractController
   {
       public function show(AlphaVantageService $alphaVantage): Response
       {
           $data = $alphaVantage->getStockQuote('AAPL');
           return $this->json($data);
       }
   }
   

Implementation Patterns

Core Workflows

1. Service Injection Inject AlphaVantageService into controllers/services for API calls:

   public function __construct(private AlphaVantageService $api) {}
   

2. Common Endpoints

   • Stock Data:

     $quote = $this->api->getStockQuote('MSFT');
     $timeSeries = $this->api->getTimeSeries('GOOG', 'DAILY');
     

   • Crypto Data:

     $crypto = $this->api->getCryptoQuote('BTC', 'USD');
     

   • News:

     $news = $this->api->getNews('Apple');
     

3. Rate Limiting & Caching

   • Use Symfony’s cache system to avoid hitting API limits:

     # config/packages/cheesaw_alpha_vantage.yaml
     cheesaw_alpha_vantage:
         cache_enabled: true
         cache_pool: 'app.cache.array'
     

   • Cache TTL (default: 300s):

     cache_ttl: 600  # 10 minutes
     

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

   try {
       $data = $this->api->getStockQuote('INVALID_TICKER');
   } catch (\CheeSaW\AlphaVantageBundle\Exception\ApiException $e) {
       $this->addFlash('error', $e->getMessage());
   }
   

Gotchas and Tips

Pitfalls

1. API Key Leaks

   • Never hardcode the API key in PHP files. Always use %env() in YAML or .env.
   • Validate the key via:

     php bin/console debug:config cheesaw_alpha_vantage
     

2. Rate Limits

   • Alpha Vantage enforces 5 requests/minute for free tier. Cache aggressively or use a paid plan.
   • Monitor usage with:

     $this->api->getRateLimitStatus();
     

3. Data Format Quirks

   • Responses are JSON arrays/objects, but some endpoints (e.g., TIME_SERIES_DAILY) return nested structures. Flatten with:

     $flattened = $this->api->flattenTimeSeries($rawData);
     

4. Deprecated Endpoints

   • Some endpoints (e.g., GLOBAL_QUOTE) may be deprecated. Check Alpha Vantage’s docs for updates.

Debugging Tips

• Enable Verbose Logging:

  cheesaw_alpha_vantage:
      debug: true
  

  Logs will appear in var/log/dev.log.

• Validate Responses: Use var_dump() or dd() to inspect raw API responses:

  $raw = $this->api->rawRequest('FUNCTION=TIME_SERIES_DAILY', ['symbol' => 'AAPL']);
  

Extension Points

1. Custom Endpoints Extend the service by creating a decorator:

   use CheeSaW\AlphaVantageBundle\Service\AlphaVantageServiceInterface;
   
   class CustomAlphaVantageService implements AlphaVantageServiceInterface
   {
       public function __construct(private AlphaVantageService $decorated) {}
   
       public function getCustomData(string $symbol): array
       {
           $data = $this->decorated->rawRequest('FUNCTION=CUSTOM_FUNCTION', ['symbol' => $symbol]);
           // Transform data here
           return $data;
       }
   }
   

   Bind it in services.yaml:

   services:
       CheeSaW\AlphaVantageBundle\Service\AlphaVantageServiceInterface: '@custom_alpha_vantage'
   

2. Override Base URL For testing/staging, override the base URL:

   cheesaw_alpha_vantage:
       base_url: '%env(ALPHA_VANTAGE_TEST_URL)%'