Placetel Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require 20steps/placetel-bundle:dev-master
   

   Add to AppKernel.php:

   new twentysteps\Bundle\PlacetelBundle\twentystepsPlacetelBundle(),
   

   Import services in config.yml:

   imports:
       - { resource: "@twentystepsPlacetelBundle/Resources/config/services.yml" }
   

2. Configure: Add to parameters.yml:

   parameters:
       twentysteps_placetel.url: "https://api.placetel.de/api/"
       twentysteps_placetel.api_key: "your_api_key_here"
       twentysteps_placetel.timeout: 10
       twentysteps_placetel.connect_timeout: 5
       twentysteps_placetel.cache_ttl: 3600
   

3. First Use Case: Inject the service in a controller or command:

   use twentysteps\Bundle\PlacetelBundle\Services\PlacetelService;
   
   class MyController extends Controller
   {
       public function indexAction(PlacetelService $placetel)
       {
           $services = $placetel->getServices();
           return $this->render('template.html.twig', ['services' => $services]);
       }
   }
   

Implementation Patterns

Core Workflow

1. Service Injection: Prefer dependency injection over manual container access for better testability:

   class MyService
   {
       private $placetel;
   
       public function __construct(PlacetelService $placetel)
       {
           $this->placetel = $placetel;
       }
   }
   

2. Caching Strategy: Leverage built-in caching (TTL: 3600 by default) to avoid rate limits:

   $calls = $this->placetel->getCalls(); // Cached for 1 hour
   

3. Error Handling: Wrap API calls in try-catch blocks to handle timeouts/errors gracefully:

   try {
       $result = $this->placetel->getSomeData();
   } catch (\RuntimeException $e) {
       $this->addFlash('error', 'Placetel API error: ' . $e->getMessage());
   }
   

4. KPI Derivation: Use derived KPIs (e.g., call durations, success rates) for dashboards:

   $kpis = $this->placetel->getKpis();
   $avgDuration = $kpis['avg_call_duration'];
   

Integration Tips

• Event Listeners: Subscribe to Placetel events (if supported) for real-time updates:

  # config.yml
  services:
      my.placetel.listener:
          class: AppBundle\EventListener\PlacetelListener
          tags:
              - { name: kernel.event_listener, event: placetel.call.created, method: onCallCreated }
  

• Command-Line Tools: Use the service in Symfony commands for bulk operations:

  use Symfony\Component\Console\Command\Command;
  use Symfony\Component\Console\Input\InputInterface;
  use Symfony\Component\Console\Output\OutputInterface;
  
  class SyncPlacetelDataCommand extends Command
  {
      protected function execute(InputInterface $input, OutputInterface $output)
      {
          $placetel = $this->getContainer()->get('twentysteps_placetel.service');
          $output->writeln('Syncing services...');
          $services = $placetel->getServices();
          // Process data...
      }
  }
  

Gotchas and Tips

Pitfalls

1. Rate Limiting:

   • The bundle caches responses by default (cache_ttl), but aggressive polling (e.g., every minute) may still hit limits.
   • Fix: Increase cache_ttl or implement exponential backoff in custom wrappers.

2. Deprecated Methods:

   • The bundle is incomplete (per README). Assume undocumented methods may break.
   • Tip: Check Services/PlacetelService.php for available methods before use.

3. Timeouts:

   • Default timeout: 10 and connect_timeout: 5 may be too low for slow networks.
   • Tip: Adjust in parameters.yml if API responses are delayed.

4. No Full API Coverage:

   • Not all Placetel endpoints are implemented (e.g., no createCall).
   • Workaround: Extend the service or use raw HTTP calls as a fallback:

     $client = new \GuzzleHttp\Client();
     $response = $client->request('GET', 'https://api.placetel.de/api/calls', [
         'auth' => ['api_key', ''],
     ]);
     

Debugging

• Enable Debug Mode: Add to config.yml to log API requests:

  twentysteps_placetel:
      debug: true
  

• Check Cache: Clear cache if stale data persists:

  php bin/console cache:clear
  

Extension Points

1. Custom Endpoints: Extend PlacetelService to add missing methods:

   // src/AppBundle/Service/ExtendedPlacetelService.php
   class ExtendedPlacetelService extends \twentysteps\Bundle\PlacetelBundle\Services\PlacetelService
   {
       public function getCustomData()
       {
           return $this->callApi('GET', '/custom/endpoint');
       }
   }
   

   Register as a service:

   services:
       app.placetel.extended:
           class: AppBundle\Service\ExtendedPlacetelService
           parent: twentysteps_placetel.service
   

2. Override Cache: Disable caching for specific methods by injecting a custom cache pool:

   services:
       app.placetel.no_cache:
           class: AppBundle\Service\NoCachePlacetelService
           arguments:
               - '@twentysteps_placetel.http_client'
               - null # Disable cache
   

3. Event Dispatching: Trigger Symfony events after API calls (e.g., for logging):

   use Symfony\Component\EventDispatcher\EventDispatcherInterface;
   
   class MyPlacetelService extends PlacetelService
   {
       private $dispatcher;
   
       public function __construct(HttpClient $client, EventDispatcherInterface $dispatcher)
       {
           parent::__construct($client);
           $this->dispatcher = $dispatcher;
       }
   
       protected function afterApiCall($response)
       {
           $this->dispatcher->dispatch('placetel.api.response', new PlacetelEvent($response));
       }
   }