Pando Account Ticket Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require blackboxcode/pando-account-ticket-bundle
   

   Register the bundle in config/bundles.php:

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

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=pando-account-ticket-config
   

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

3. First Use Case Generate an account ticket via the facade:

   use BlackBoxCode\PandoAccountTicketBundle\Facades\PandoAccountTicket;
   
   $ticket = PandoAccountTicket::create([
       'email' => 'user@example.com',
       'first_name' => 'John',
       'last_name' => 'Doe',
       'company' => 'Acme Inc.',
   ]);
   

   Redirect users to the generated ticket URL:

   return redirect()->away($ticket->getUrl());
   

Implementation Patterns

Workflow Integration

1. User Onboarding Trigger ticket creation post-registration:

   // In UserObserver or RegistrationController
   event(new Registered($user));
   // ...
   PandoAccountTicket::createForUser($user);
   

2. API-Driven Workflows Use the service directly in controllers or services:

   public function createTicket(Request $request)
   {
       $data = $request->validate([
           'email' => 'required|email',
           'first_name' => 'required',
           // ...
       ]);
   
       $ticket = PandoAccountTicket::create($data);
       return response()->json(['url' => $ticket->getUrl()]);
   }
   

3. Queue-Based Processing Offload ticket creation to a queue job:

   // app/Jobs/CreatePandoTicket.php
   public function handle()
   {
       PandoAccountTicket::create($this->data);
   }
   

   Dispatch in your workflow:

   CreatePandoTicket::dispatch($userData);
   

Common Patterns

• Data Transformation Use the transform() method to map Eloquent models to Pando’s expected format:

  $ticket = PandoAccountTicket::create(
      PandoAccountTicket::transform($user)
  );
  

• Webhook Handling Listen for Pando webhook events (e.g., ticket status updates):

  // routes/web.php
  Route::post('/pando/webhook', [PandoWebhookController::class, 'handle']);
  

• Testing Mock the Pando client in tests:

  $this->mock(PandoClient::class, function ($mock) {
      $mock->shouldReceive('createTicket')->andReturn($fakeResponse);
  });
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • Pando’s API may throttle requests. Implement exponential backoff in your PandoClient or use Laravel’s retry helper.
   • Example:

     try {
         $ticket = PandoAccountTicket::create($data);
     } catch (RateLimitException $e) {
         retry()->times(3)->later(2000)->try(fn() => PandoAccountTicket::create($data));
     }
     

2. Data Validation Mismatches

   • Pando’s API expects specific fields (e.g., company_name vs. company). Use the transform() method to ensure consistency.
   • Validate input against Pando’s schema early:

     $validator = Validator::make($data, PandoAccountTicket::rules());
     

3. Webhook Verification

   • Always verify Pando webhook signatures to avoid spoofing. The bundle provides a verifyWebhook method:

     if (!PandoAccountTicket::verifyWebhook($request)) {
         abort(403);
     }
     

Debugging

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

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

• HTTP Client Inspection Use Laravel’s tap() to inspect the HTTP client:

  $client = app(PandoClient::class)->tap(function ($client) {
      \Log::debug('Client config:', $client->getConfig());
  });
  

Extension Points

1. Custom Fields Extend the TicketData class to add custom attributes:

   class CustomTicketData extends \BlackBoxCode\PandoAccountTicketBundle\TicketData
   {
       public function __construct(array $data)
       {
           parent::__construct($data);
           $this->custom_field = $data['custom_field'] ?? null;
       }
   }
   

   Register the custom class in the config:

   'ticket_data_class' => \App\CustomTicketData::class,
   

2. Event Listeners Subscribe to Pando events (e.g., TicketCreated):

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \BlackBoxCode\PandoAccountTicketBundle\Events\TicketCreated::class => [
           \App\Listeners\LogTicketCreation::class,
       ],
   ];
   

3. Testing Helpers Use the PandoAccountTicketTestCase trait for consistent test setups:

   use BlackBoxCode\PandoAccountTicketBundle\Testing\PandoAccountTicketTestCase;
   
   class MyTest extends PandoAccountTicketTestCase
   {
       // Tests use a mocked Pando client by default
   }