Check Book Io Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require beyerz/check-book-io-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   Beyerz\CheckBookIOBundle\CheckBookIOBundle::class => ['all' => true],
   

2. Configuration Add to .env:

   CHECKBOOK_PUBLISHABLE_KEY=your_publishable_key
   CHECKBOOK_SECRET_KEY=your_secret_key
   CHECKBOOK_SANDBOX=true
   CHECKBOOK_DEBUG=false
   CHECKBOOK_MERCHANT_NAME="Your Merchant"
   CHECKBOOK_OAUTH_CLIENT_ID=your_client_id
   

   Publish the default config (if needed):

   php bin/console config:dump-reference check_book_io
   

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

   use Beyerz\CheckBookIOBundle\Service\CheckBookIOService;
   
   public function __construct(private CheckBookIOService $checkBookIO) {}
   
   public function createCustomer(Request $request)
   {
       $customer = $this->checkBookIO->createCustomer([
           'first_name' => 'John',
           'last_name' => 'Doe',
           'email' => 'john@example.com',
       ]);
       return new JsonResponse($customer);
   }
   

Implementation Patterns

Core Workflows

1. Customer Management

   // Create
   $customer = $checkBookIO->createCustomer($data);
   
   // Retrieve
   $customer = $checkBookIO->getCustomer($customerId);
   
   // Update
   $updated = $checkBookIO->updateCustomer($customerId, $data);
   
   // List
   $customers = $checkBookIO->listCustomers(['limit' => 10]);
   

2. Payment Processing

   // Create a payment
   $payment = $checkBookIO->createPayment($customerId, [
       'amount' => 100.00,
       'currency' => 'USD',
       'description' => 'Subscription',
   ]);
   
   // Capture a payment
   $captured = $checkBookIO->capturePayment($paymentId, $amount);
   

3. Webhooks & Events Subscribe to events via Symfony’s event dispatcher:

   $dispatcher->addListener(
       'checkbookio.payment.created',
       [$this, 'handlePaymentCreated']
   );
   

Integration Tips

• Sandbox Mode: Always test in sandbox (CHECKBOOK_SANDBOX=true) before going live.
• Error Handling: Wrap API calls in try-catch blocks to handle CheckBookIOException:

  try {
      $payment = $checkBookIO->createPayment(...);
  } catch (CheckBookIOException $e) {
      $this->addFlash('error', $e->getMessage());
  }
  

• OAuth Customization: Override the default OAuth handler by configuring oauth.handler in config.yml:

  oauth:
      handler: App\Service\CustomOAuthHandler
  

Gotchas and Tips

Common Pitfalls

1. Deprecated API: The package was last updated in 2017. Verify API endpoints (/customers, /payments) still match checkbook.io’s current docs.
2. Missing Dependencies: Ensure symfony/http-client or guzzlehttp/guzzle (if used internally) is installed.
3. Configuration Overrides: If using Symfony Flex, manually publish the config:

   php bin/console config:dump-reference check_book_io > config/packages/check_book_io.yaml
   

Debugging

• Enable Debug Mode: Set CHECKBOOK_DEBUG=true to log raw API responses.
• CheckBookIOException: Inspect the getResponse() method for raw API errors:

  try {
      $checkBookIO->createPayment(...);
  } catch (CheckBookIOException $e) {
      error_log($e->getResponse()->getContent());
  }
  

Extension Points

1. Custom Responses: Extend the base response handler:

   class CustomResponseHandler extends \Beyerz\CheckBookIOBundle\Response\Handler
   {
       protected function transformResponse($response, $data)
       {
           // Custom logic
           return parent::transformResponse($response, $data);
       }
   }
   

   Then configure in config.yml:

   oauth:
       handler: App\Service\CustomResponseHandler
   

2. Event Subscribers: Create a subscriber for webhook events:

   class CheckBookIOWebhookSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'checkbookio.payment.created' => 'onPaymentCreated',
           ];
       }
   
       public function onPaymentCreated(CheckBookIOEvent $event) { ... }
   }
   

Performance

• Caching: Cache customer/payment lists if they’re frequently accessed:

  $customers = $this->cache->get('checkbook_customers', function() use ($checkBookIO) {
      return $checkBookIO->listCustomers();
  });