Pando Account Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require blackboxcode/pando-account-bundle
   

   Register the bundle in config/bundles.php (Symfony):

   BlackBoxCode\PandoAccountBundle\PandoAccountBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="BlackBoxCode\PandoAccountBundle\PandoAccountBundle" --tag="config"
   

   Update config/pando_account.php with your Pando API credentials and environment settings.

3. First Use Case: Fetching an Account Inject the PandoAccountService into a controller or service:

   use BlackBoxCode\PandoAccountBundle\Service\PandoAccountService;
   
   class AccountController extends Controller
   {
       public function __construct(private PandoAccountService $accountService) {}
   
       public function show(string $accountId)
       {
           $account = $this->accountService->getAccount($accountId);
           return response()->json($account);
       }
   }
   

Implementation Patterns

Core Workflows

1. Account Management

   • Create/Update: Use createAccount() or updateAccount() with an array of Pando-compatible attributes.

     $accountData = [
         'name' => 'Test Account',
         'email' => 'test@example.com',
         'metadata' => ['custom_field' => 'value']
     ];
     $this->accountService->createAccount($accountData);
     

   • Retrieve: Fetch single or multiple accounts via getAccount() or listAccounts().

     $accounts = $this->accountService->listAccounts(['status' => 'active']);
     

2. Webhook Integration

   • Subscribe to Pando events by configuring the webhook section in config/pando_account.php:

     'webhook' => [
         'url' => 'https://your-app.com/pando-webhook',
         'events' => ['account.created', 'account.updated'],
     ],
     

   • Handle incoming webhooks in a Symfony controller:

     public function handleWebhook(Request $request, PandoWebhookHandler $handler)
     {
         $handler->process($request);
     }
     

3. Event-Driven Extensions

   • Listen to Pando events via Symfony’s event dispatcher:

     use BlackBoxCode\PandoAccountBundle\Event\AccountEvent;
     
     public function __construct(private EventDispatcherInterface $dispatcher) {}
     
     public function createAccount(array $data)
     {
         $account = $this->accountService->createAccount($data);
         $this->dispatcher->dispatch(new AccountEvent($account, 'created'));
     }
     

Integration Tips

• Laravel-Specific: Use the PandoAccountFacade for cleaner syntax in Blade or controllers:

  use BlackBoxCode\PandoAccountBundle\Facades\PandoAccount;
  
  $account = PandoAccount::getAccount($id);
  

• Testing: Mock the PandoAccountService in unit tests:

  $this->mock(PandoAccountService::class)
       ->shouldReceive('getAccount')
       ->once()
       ->andReturn(['id' => 123, 'name' => 'Test']);
  

Gotchas and Tips

Common Pitfalls

1. API Rate Limits

   • Pando enforces rate limits. Cache responses aggressively:

     $account = Cache::remember("pando_account_{$accountId}", now()->addHours(1), function () use ($accountId) {
         return $this->accountService->getAccount($accountId);
     });
     

   • Monitor limits via the PandoAccountService's getRateLimitStatus() method.

2. Webhook Idempotency

   • Always verify webhook signatures using the PandoWebhookHandler:

     $handler = new PandoWebhookHandler($request, config('pando_account.webhook.secret'));
     if (!$handler->isValid()) {
         abort(403, 'Invalid webhook signature');
     }
     

   • Use idempotency_keys in the config to handle duplicate webhook deliveries.

3. Data Mismatches

   • Pando’s API may return fields in snake_case while your app uses camelCase. Normalize responses:

     $account = $this->accountService->getAccount($id);
     $normalized = (object) array_map('str_replace', ['_', ''], (array) $account);
     

Debugging Tips

• Enable Verbose Logging Set debug: true in config/pando_account.php to log raw API responses:

  'debug' => env('PANDO_DEBUG', false),
  

• Use the PandoDebugController The bundle includes a debug endpoint at /_pando/debug to inspect API calls and responses.

Extension Points

1. Custom Account Mappers Override the default mapper to transform Pando data:

   // config/pando_account.php
   'mappers' => [
       'account' => App\Services\CustomAccountMapper::class,
   ];
   

   Implement BlackBoxCode\PandoAccountBundle\Mapper\AccountMapperInterface.

2. Add Custom Fields Extend the Account entity by adding a custom_fields array to your config:

   'custom_fields' => [
       'tax_id' => 'string',
       'preferred_language' => 'string',
   ],
   

   These will be included in create/update operations.

3. Batch Operations Use the batchProcess() method for bulk operations (e.g., updating 100+ accounts):

   $this->accountService->batchProcess(
       'update',
       ['id' => [1, 2, 3]],
       ['status' => 'active']
   );
   

   Note: Pando’s API may impose batch size limits.