Collmex Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   Add to AppKernel.php:

   new twentysteps\Bundle\CollmexBundle\twentystepsCollmexBundle(),
   

   Import services in config.yml:

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

2. Configure API Credentials (parameters.yml):

   parameters:
       twentysteps_collmex.url: "https://www.collmex.de"
       twentysteps_collmex.account_id: "YOUR_ACCOUNT_ID"
       twentysteps_collmex.api_key: "YOUR_API_KEY"  # Add if required (not in README)
   

3. First Use Case: Inject the collmex.client service into a controller/service and call a basic API method:

   use twentysteps\Bundle\CollmexBundle\Service\CollmexClient;
   
   class MyController extends Controller
   {
       public function index(CollmexClient $collmex)
       {
           $response = $collmex->get('/api/v1/accounts'); // Example endpoint
           return new JsonResponse($response);
       }
   }
   

Implementation Patterns

Service-Oriented Workflows

1. Dependency Injection:

   • Inject CollmexClient into controllers/services to avoid hardcoding API calls.
   • Example:

     public function __construct(private CollmexClient $collmex) {}
     

2. Request/Response Handling:

   • Use the client’s methods to interact with Collmex endpoints (e.g., get(), post()).
   • Parse responses with Symfony’s JsonResponse or custom DTOs:

     $data = $collmex->get('/api/v1/invoices')->getData();
     

3. Configuration Overrides:

   • Override default parameters in config.yml:

     twentysteps_collmex:
         url: "%env(COLLMEX_API_URL)%"
         timeout: 30
     

4. Caching (Future-Proofing):

   • Extend the bundle’s caching layer (placeholder in README) by implementing a decorator:

     $collmex->setCache(new SymfonyCacheAdapter());
     

5. Error Handling:

   • Wrap API calls in try-catch blocks to handle CollmexException:

     try {
         $collmex->post('/api/v1/transactions', $payload);
     } catch (\Exception $e) {
         $this->addFlash('error', $e->getMessage());
     }
     

Gotchas and Tips

Pitfalls

1. Missing API Key:

   • The README omits api_key in parameters.yml, but Collmex likely requires it. Add it or risk 403 errors.

2. Rate Limiting:

   • No built-in caching (marked as "incomplete" in features). Implement a decorator or use Symfony’s HttpCache to avoid hitting limits.

3. Endpoint Documentation:

   • The bundle lacks endpoint examples. Refer to Collmex’s API docs (if public) or contact support for valid paths.

4. Symfony 2 vs. 4+:

   • The bundle targets Symfony2. For newer versions, alias services in config/services.yaml:

     services:
         twentysteps_collmex.client:
             alias: twentystepsCollmexBundle.collmex.client
     

5. Debugging:

   • Enable Guzzle’s debug middleware to inspect raw requests/responses:

     $collmex->setClient(new \GuzzleHttp\Client([
         'handler' => \GuzzleHttp\HandlerStack::create(new \GuzzleHttp\Middleware::tap(function ($request) {
             error_log($request->getUri());
         })),
     ]));
     

Tips

1. Environment Variables:

   • Store sensitive data (e.g., api_key) in .env:

     parameters:
         twentysteps_collmex.api_key: "%env(COLLMEX_API_KEY)%"
     

2. Testing:

   • Mock the CollmexClient in PHPUnit:

     $this->collmex = $this->createMock(CollmexClient::class);
     $this->collmex->method('get')->willReturn(new Response(json_encode(['test' => true])));
     

3. Extending Functionality:

   • Create a custom service to wrap the client for domain-specific logic:

     class InvoiceService {
         public function __construct(private CollmexClient $client) {}
     
         public function fetchInvoices() {
             return $this->client->get('/api/v1/invoices')->getData();
         }
     }
     

4. Logging:

   • Log API responses for auditing:

     $response = $collmex->get('/api/v1/accounts');
     $this->logger->info('Collmex API Response', ['data' => $response->getData()]);
     

5. Fallbacks:

   • Implement retry logic for transient failures using Guzzle’s RetryMiddleware.