Karmacracy Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cayetanosoriano/karmacracy-bundle:dev-master
   

   Ensure composer.json includes the dependency under "require".

2. Enable Bundle: Add to AppKernel.php:

   new cayetanosoriano\KarmacracyBundle\cayetanosorianoKarmacracyBundle(),
   

3. Configure: Add to config.yml:

   cayetanosoriano_karmacracy:
       keypass: "%env(KARMACRACY_KEYPASS)%"  # Use env vars for security
       appkey: "%env(KARMACRACY_APPKEY)%"
   

4. First Use: Inject the service in a controller/service:

   use Symfony\Component\DependencyInjection\ContainerInterface;
   
   class MyController extends Controller {
       public function index(ContainerInterface $container) {
           $kcy = $container->get('kcy');
           $result = $kcy->getBalance(); // Example method (verify actual API)
           return $this->render('balance.html.twig', ['balance' => $result]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Service Injection: Prefer dependency injection over get() calls for testability:

   class PaymentService {
       private $kcy;
   
       public function __construct(KarmacracyService $kcy) {
           $this->kcy = $kcy;
       }
   }
   

2. API Wrapping: Use the bundle to abstract Karmacracy’s API calls (e.g., payments, refunds, balance checks). Example:

   $payment = $this->kcy->createPayment([
       'amount' => 100.00,
       'currency' => 'EUR',
       'description' => 'Order #123'
   ]);
   

3. Event-Driven Hooks: Extend the bundle by listening to Karmacracy events (if supported). Example:

   # config.yml
   services:
       app.karmacracy.listener:
           class: AppBundle\EventListener\KarmacracyListener
           tags:
               - { name: kernel.event_listener, event: karmacracy.payment.created, method: onPaymentCreated }
   

4. Configuration Overrides: Override defaults via config.yml or environment variables:

   cayetanosoriano_karmacracy:
       keypass: "%env(KARMACRACY_KEYPASS)%"
       appkey: "%env(KARMACRACY_APPKEY)%"
       timeout: 30  # Custom timeout in seconds
   

5. Error Handling: Wrap API calls in try-catch blocks to handle Karmacracy-specific exceptions:

   try {
       $response = $this->kcy->execute('webhook', ['data' => $payload]);
   } catch (\Karmacracy\Exception\ApiException $e) {
       $this->logger->error('Karmacracy API error: ' . $e->getMessage());
       throw new \RuntimeException('Payment processing failed', 0, $e);
   }
   

Gotchas and Tips

Pitfalls

1. Deprecated Symfony 2.x: The bundle targets Symfony 2.x. For Symfony 3/4/5, verify compatibility or fork the package. Use symfony/flex or auto-wiring for modern DI.

2. Missing Documentation: The README lacks examples for core methods (e.g., getBalance(), createPayment). Check the underlying karmacracy-php lib for undocumented features.

3. Environment Variables: Hardcoding keypass/appkey in config.yml is insecure. Always use %env() or .env files:

   keypass: "%env(KARMACRACY_KEYPASS)%"
   

4. Service Naming: The service is registered as kcy. If this conflicts with other services, override the ID in services.yml:

   services:
       karmacracy:
           alias: kcy
           public: true
   

5. Rate Limiting: Karmacracy may throttle requests. Implement exponential backoff for retries:

   use Symfony\Component\Stopwatch\Stopwatch;
   
   $stopwatch = new Stopwatch();
   $event = $stopwatch->start('karmacracy_retry');
   
   while (true) {
       try {
           $response = $this->kcy->execute('api_endpoint', $data);
           break;
       } catch (\Karmacracy\Exception\RateLimitException $e) {
           $event->lap();
           if ($event->getDuration() > 60_000) { // 1 minute max
               throw $e;
           }
           sleep(2 ** $event->getLapNumber());
       }
   }
   

Tips

1. Logging: Enable debug logging for Karmacracy requests/responses:

   # config.yml
   monolog:
       handlers:
           karmacracy:
               type: stream
               path: "%kernel.logs_dir%/karmacracy.log"
               level: debug
   

2. Testing: Mock the kcy service in PHPUnit:

   $this->container->set('kcy', $this->createMock(KarmacracyService::class));
   

3. Webhooks: If using Karmacracy webhooks, validate signatures manually:

   $signature = $_SERVER['HTTP_X_KARMACRACY_SIGNATURE'];
   $expected = hash_hmac('sha256', $payload, $this->kcy->getKeypass());
   if (!hash_equals($signature, $expected)) {
       throw new \RuntimeException('Invalid webhook signature');
   }
   

4. Performance: Cache frequent API calls (e.g., balance checks) with symfony/cache:

   $cache = $this->container->get('cache.app');
   $balance = $cache->get('karmacracy_balance', function() {
       return $this->kcy->getBalance();
   });
   

5. Extensions: Extend the bundle by creating a custom service that wraps kcy:

   class CustomKarmacracyService {
       private $kcy;
   
       public function __construct(KarmacracyService $kcy) {
           $this->kcy = $kcy;
       }
   
       public function createSubscription(array $data) {
           return $this->kcy->execute('subscriptions', $data);
       }
   }