Eight Bit Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require derkien/eight-bit-bundle:1.*
   

   Ensure SensioBuzzBundle is enabled in AppKernel.php (as shown in the README).

2. Configure the Bundle: Define a client service in app/config/config.yml:

   eight_bit:
       clients:
           my_client:
               url: "https://api.example.com/locations"
               auth: { token: "your_api_token" }  # Optional auth config
   

3. First Use Case: Fetch and display locations via the default controller:

   // src/AppBundle/Controller/LocationController.php
   use Derkien\EightBitBundle\Controller\LocationController;
   
   class LocationController extends LocationController
   {
       public function indexAction()
       {
           $locations = $this->get('eight_bit.client.my_client')->fetch();
           return $this->render('AppBundle:Location:index.html.twig', ['locations' => $locations]);
       }
   }
   

   Access via /location (if routing is configured).

Implementation Patterns

Core Workflows

1. Service-Based Client Configuration:

   • Define clients in config.yml under eight_bit.clients with keys like url, auth, and options (e.g., timeout).
   • Inject the client service into controllers/services:

     $client = $this->get('eight_bit.client.my_client');
     $locations = $client->fetch(); // Returns array of `EightBitBundle\Entity\Location`
     

2. Error Handling:

   • The bundle throws exceptions for:
     • CURL errors (EightBitBundle\Exception\CurlException).
     • Malformed JSON (EightBitBundle\Exception\JsonException).
     • API error responses (EightBitBundle\Exception\ApiException).
   • Catch and handle in controllers:

     try {
         $locations = $client->fetch();
     } catch (\Exception $e) {
         $this->addFlash('error', $e->getMessage());
         return $this->redirect($this->generateUrl('home'));
     }
     

3. Customizing the Entity:

   • Extend EightBitBundle\Entity\Location to add custom properties/methods:

     namespace AppBundle\Entity;
     use Derkien\EightBitBundle\Entity\Location as BaseLocation;
     
     class Location extends BaseLocation
     {
         public function getFormattedAddress()
         {
             return $this->street . ', ' . $this->city;
         }
     }
     

   • Override the bundle’s entity mapping in services.yml:

     eight_bit.entity.location.class: AppBundle\Entity\Location
     

4. Reusing Logic:

   • Create a service to encapsulate API calls:

     // src/AppBundle/Service/LocationService.php
     class LocationService
     {
         private $client;
     
         public function __construct($client)
         {
             $this->client = $client;
         }
     
         public function getNearbyLocations($lat, $lng)
         {
             $this->client->setOptions(['query' => ['lat' => $lat, 'lng' => $lng]]);
             return $this->client->fetch();
         }
     }
     

   • Register the service in services.yml:

     app.location_service:
         class: AppBundle\Service\LocationService
         arguments: ['@eight_bit.client.my_client']
     

5. Caching Responses:

   • Use Symfony’s cache system to store responses:

     $cache = $this->get('cache.app');
     $cacheKey = 'locations_' . md5($client->getUrl());
     if (!$locations = $cache->get($cacheKey)) {
         $locations = $client->fetch();
         $cache->set($cacheKey, $locations, 3600); // Cache for 1 hour
     }
     

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies:

   • The bundle relies on Symfony 3 and SensioBuzzBundle, which may have compatibility issues with newer Symfony versions (e.g., 4/5). Test thoroughly if upgrading.
   • sensio/buzz-bundle is outdated; consider replacing it with php-http/guzzle-bundle for modern projects.

2. Entity Mapping Assumptions:

   • The bundle assumes JSON responses match the structure of EightBitBundle\Entity\Location. If the API returns a nested array (e.g., {"data": [...]}), override the fetch() method in a custom client class:

     use Derkien\EightBitBundle\Client\Client;
     
     class CustomClient extends Client
     {
         protected function parseResponse($response)
         {
             return parent::parseResponse($response['data']); // Adjust as needed
         }
     }
     

3. CURL Configuration:

   • Default CURL options may not suit all APIs. Extend the client to add custom headers or timeouts:

     eight_bit:
         clients:
             my_client:
                 url: "https://api.example.com/locations"
                 options:
                     headers: { "X-API-Key": "your_key" }
                     timeout: 10
     

4. Routing Conflicts:

   • The default route (derkien-eight-bit) may conflict with existing routes. Either:
     • Rename the route in EightBitBundle/Resources/config/routing.yml.
     • Override the route in your project’s routing file:

       derkien_eight_bit_homepage:
           path: /custom-path
           defaults: { _controller: EightBitBundle:Location:index }
       

5. No Rate Limiting:

   • The bundle lacks built-in rate limiting. Implement a decorator pattern or middleware to handle API rate limits:

     // src/AppBundle/EventListener/RateLimitListener.php
     class RateLimitListener
     {
         public function onKernelRequest(GetResponseEvent $event)
         {
             if ($event->getRequest()->attributes->get('_route') === 'derkien_eight_bit') {
                 // Add rate limiting logic (e.g., using `stof/doctrine-extensions-bundle`)
             }
         }
     }
     

Debugging Tips

1. Enable CURL Debugging: Add to config.yml to log CURL requests:

   eight_bit:
       clients:
           my_client:
               options:
                   debug: true
   

   Check logs in var/log/dev.log.

2. Inspect Raw Responses: Override the fetch() method to log raw responses:

   $client->setLogger($this->get('logger')); // Inject Symfony logger
   

3. Validate JSON Structure: Use tools like JSONLint to verify API responses match the expected structure before debugging.

Extension Points

1. Custom Clients: Extend Derkien\EightBitBundle\Client\Client to support additional features (e.g., pagination, webhooks):

   class PaginatedClient extends Client
   {
       public function fetchPage($page = 1)
       {
           $this->setOptions(['page' => $page]);
           return $this->fetch();
       }
   }
   

2. Event Dispatching: Trigger events before/after API calls using Symfony’s event system:

   // In your custom client:
   $dispatcher = $this->get('event_dispatcher');
   $dispatcher->dispatch('eight_bit.fetch', new EightBitEvent($this));
   

3. Dynamic Configuration: Load client configurations dynamically (e.g., from a database) by overriding the bundle’s compiler pass:

   // src/AppBundle/DependencyInjection/Compiler/DynamicEightBitPass.php
   class DynamicEightBitPass extends CompilerPassInterface
   {
       public function process(ContainerBuilder $container)
       {
           $configs = $this->getDynamicConfigs(); // Fetch from DB/API
           foreach ($configs as $name => $config) {
               $container->setDefinition(
                   'eight_bit.client.' . $name,
                   new Definition('Derkien\EightBitBundle\Client\Client', [$config])
               );
           }
       }
   }