Evc Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require alexandret/evc-bundle
   

   For Symfony Flex projects, this auto-configures the bundle. For manual setups, add to config/bundles.php:

   Alexandre\EvcBundle\AlexandreEvcBundle::class => ['all' => true],
   

2. Configure Environment Variables Add to .env:

   ###> alexandret/evc-bundle ###
   EVC_API="your_api_key"
   EVC_USERNAME="your_username"
   EVC_PASSWORD="your_api_password"  # NOT your evc.de account password
   ###< alexandret/evc-bundle ###
   

3. Verify Configuration Create config/packages/alexandre_evc.yaml:

   alexandre_evc:
       api_id: '%env(EVC_API)%'
       username: '%env(EVC_USERNAME)%'
       password: '%env(EVC_PASSWORD)%'
   

4. First Use Case: Check Customer Status Inject EvcService and call:

   $customerId = '12345';
   $isPersonal = $this->evcService->isPersonal($customerId);
   $credits = $this->evcService->getCredits($customerId);
   

Implementation Patterns

Core Workflows

1. Customer Lookup Use getCustomer() to fetch details (e.g., credits, status):

   $customer = $this->evcService->getCustomer('12345');
   

2. Personal Customer Filtering Fetch all personal customers with getPersonalCustomers():

   $personalCustomers = $this->evcService->getPersonalCustomers();
   

3. Credit Management Check credits for a customer:

   $credits = $this->evcService->getCredits('12345');
   

4. Dependency Injection Register EvcService in your controller/service:

   use Alexandre\EvcBundle\Service\EvcService;
   
   public function __construct(private EvcService $evcService) {}
   

Integration Tips

• Event-Driven Workflows Trigger actions (e.g., credit alerts) via Symfony events when customer data changes:

  $this->evcService->getCustomer($id)->then(function ($customer) {
      if ($customer->getCredits() < 5) {
          $this->dispatchEvent('low_credits', $customer);
      }
  });
  

• Command-Line Automation Use Symfony Console commands to sync customer data:

  use Symfony\Component\Console\Command\Command;
  use Alexandre\EvcBundle\Service\EvcService;
  
  protected function execute(InputInterface $input, OutputInterface $output): int {
      $customers = $this->evcService->getPersonalCustomers();
      // Process customers...
  }
  

• Caching Responses Cache API responses (e.g., with Symfony Cache) to reduce calls:

  $cache = $this->container->get('cache.app');
  $customer = $cache->get("evc_customer_{$id}", function() use ($id) {
      return $this->evcService->getCustomer($id);
  });
  

Gotchas and Tips

Pitfalls

1. Credential Mismatch

   • Error: CredentialException if EVC_USERNAME/EVC_PASSWORD are incorrect.
   • Fix: Verify credentials with EVC support. Use the emulation service in dev:

     # config/packages/dev/service.yaml
     alexandre_evc_request:
         class: Alexandre\EvcBundle\Service\EmulationService
         arguments:
             $api: '%env(EVC_API)%'
             $username: '%env(EVC_USERNAME)%'
             $password: '%env(EVC_PASSWORD)%'
     

2. Network Issues

   • Error: NetworkException if EVC API is unreachable.
   • Fix: Implement retry logic or fallback to cached data:

     try {
         $customer = $this->evcService->getCustomer($id);
     } catch (NetworkException $e) {
         $customer = $this->getCachedCustomer($id);
     }
     

3. API Response Changes

   • Error: LogicException if the API response format changes.
   • Fix: Update the bundle or extend EmulationService to mock new responses.

4. PHPUnit Version Conflicts

   • Issue: Bundle requires PHPUnit 8.5.4+ (due to PHP 7.3+ dependency).
   • Fix: Align your phpunit version in composer.json:

     "require-dev": {
         "phpunit/phpunit": "^8.5.4"
     }
     

Debugging Tips

• Enable Emulation in Dev/Test Use predefined test customers (11111, 22222, etc.) to simulate edge cases without hitting the real API.

• Log API Responses Extend RequesterService to log raw responses:

  use Psr\Log\LoggerInterface;
  
  public function __construct(
      private LoggerInterface $logger,
      private string $apiId,
      private string $username,
      private string $password
  ) {}
  
  protected function sendRequest(string $endpoint, array $params): array {
      $response = parent::sendRequest($endpoint, $params);
      $this->logger->debug('EVC API Response', ['endpoint' => $endpoint, 'response' => $response]);
      return $response;
  }
  

• Handle Exceptions Gracefully Catch specific exceptions to provide user-friendly messages:

  try {
      $this->evcService->getCustomer($id);
  } catch (CredentialException $e) {
      $this->addFlash('error', 'Invalid EVC credentials. Contact support.');
  } catch (NetworkException $e) {
      $this->addFlash('error', 'EVC service unavailable. Try again later.');
  }
  

Extension Points

1. Custom Emulation Logic Extend EmulationService to add test cases:

   class CustomEmulationService extends EmulationService {
       protected function getMockedResponse(string $customerId): array {
           if ($customerId === '99999') {
               return ['credits' => 0, 'is_personal' => true];
           }
           return parent::getMockedResponse($customerId);
       }
   }
   

2. Add API Endpoints Extend EvcService to wrap new API methods:

   public function getCustomerTransactions(string $customerId, int $limit = 10): array {
       $response = $this->requester->sendRequest(
           '/transactions',
           ['customer_id' => $customerId, 'limit' => $limit]
       );
       return $this->mapTransactions($response);
   }
   

3. Webhook Integration Use Symfony Messenger to process EVC webhook events:

   use Symfony\Component\Messenger\Attribute\AsMessageHandler;
   
   #[AsMessageHandler]
   public function handleEvcWebhook(EvcWebhook $webhook) {
       // Process webhook (e.g., credit updates)
   }