Alchemyapi Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require codag/alchemyapi-bundle:dev-master
   

   Add to config/bundles.php:

   return [
       // ...
       Codag\AlchemyApiBundle\CodagAlchemyApiBundle::class => ['all' => true],
   ];
   

2. Configuration: Add to config/packages/codag_alchemy_api.yaml:

   codag_alchemy_api:
       api_key: '%env(ALCHEMY_API_KEY)%'
       default_options: { outputMode: 'json' }
   

3. First Use Case: Inject the service and call extractEntities:

   use Codag\AlchemyApiBundle\Service\AlchemyApiService;
   
   class MyController extends AbstractController
   {
       public function analyzeText(AlchemyApiService $alchemyApi)
       {
           $response = $alchemyApi->extractEntities('https://example.com');
           return $this->json($response);
       }
   }
   

Implementation Patterns

Core Workflows

1. Text/URL Processing: Use the service for entity extraction from text or URLs:

   $alchemyApi->extractEntities('Sample text about Laravel');
   $alchemyApi->extractEntities('https://laravel.com/docs');
   

2. Response Handling: Normalize responses with getResponseData():

   $data = $alchemyApi->getResponseData($response);
   

3. Custom Options: Override default options per request:

   $alchemyApi->extractEntities('https://example.com', [
       'outputMode' => 'xml',
       'showSourceText' => true
   ]);
   

Integration Tips

• Event Dispatching: Extend the bundle by listening to alchemy.api.response events:

  // src/EventListener/AlchemyResponseListener.php
  public function onAlchemyResponse(AlchemyResponseEvent $event)
  {
      $event->setData($event->getData() + ['custom_field' => true]);
  }
  

• Caching Responses: Cache API calls using Symfony’s cache system:

  $cache = $this->get('cache.app');
  $cacheKey = 'alchemy_' . md5($url);
  $response = $cache->get($cacheKey, function() use ($alchemyApi, $url) {
      return $alchemyApi->extractEntities($url);
  });
  

• Form Integration: Process user-uploaded text via a form:

  // src/Form/AlchemyType.php
  public function buildForm(FormBuilderInterface $builder, array $options)
  {
      $builder->add('text', TextType::class);
      $builder->add('analyze', SubmitType::class, [
          'attr' => ['onclick' => 'analyzeText(this.form)']
      ]);
  }
  

Gotchas and Tips

Pitfalls

1. API Key Management:

   • Hardcoding keys violates security. Always use env():

     api_key: '%env(ALCHEMY_API_KEY)%'
     

   • Validate the key in config/validator/constraints.yaml:

     Codag\AlchemyApiBundle\Validator\Constraints\ApiKey: ~
     

2. Rate Limiting:

   • AlchemyAPI enforces rate limits. Handle 429 responses gracefully:

     try {
         $response = $alchemyApi->extractEntities($url);
     } catch (RateLimitExceededException $e) {
         $this->addFlash('error', 'API rate limit exceeded. Retry later.');
     }
     

3. Deprecated Methods:

   • The bundle only supports extractEntities (WebAPI). For other methods (e.g., sentiment analysis), use the raw API or extend the service:

     // src/Service/AlchemyApiService.php (extend)
     public function analyzeSentiment($text)
     {
         $url = 'https://api.alchemyapi.com/api/sentiment';
         return $this->makeRequest($url, ['text' => $text]);
     }
     

Debugging

• Enable Debug Mode: Set debug: true in config to log raw API responses:

  codag_alchemy_api:
      debug: true
  

• Common Errors:

  • Invalid API Key: Verify ALCHEMY_API_KEY in .env.
  • Invalid URL: Sanitize inputs with filter_var($url, FILTER_VALIDATE_URL).
  • Empty Response: Check for typos in endpoint names (e.g., extractEntities vs. extractEntity).

Extension Points

1. Custom Endpoints: Extend the service to support unsupported methods:

   // src/Service/AlchemyApiService.php
   public function customMethod($params)
   {
       return $this->makeRequest('https://api.alchemyapi.com/api/custom', $params);
   }
   

2. Response Transformers: Override getResponseData() to normalize responses:

   // src/Service/AlchemyApiService.php
   protected function getResponseData($response)
   {
       $data = parent::getResponseData($response);
       return $this->transformData($data);
   }
   

3. Event-Driven Extensions: Dispatch events for pre/post-processing:

   // src/Event/AlchemyRequestEvent.php
   class AlchemyRequestEvent extends Event
   {
       public function setParams(array $params) { /* ... */ }
   }
   

   Trigger in AlchemyApiService:

   $event = new AlchemyRequestEvent($params);
   $this->dispatcher->dispatch($event, 'alchemy.api.request');