Pando Ticket Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require blackboxcode/pando-ticket-bundle
   

   Ensure the bundle is enabled in config/bundles.php:

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

2. Publish Configuration

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

   Locate the config file at config/pando_ticket.php and review default settings (e.g., API endpoints, authentication).

3. First Use Case: Ticket Creation Inject the PandoTicketService into a controller or service:

   use BlackBoxCode\PandoTicketBundle\Service\PandoTicketService;
   
   public function createTicket(PandoTicketService $ticketService)
   {
       $ticket = $ticketService->create([
           'subject' => 'Test Ticket',
           'description' => 'Debugging issue',
           'priority' => 'high',
       ]);
       return response()->json($ticket);
   }
   

   Verify the PandoTicketService is autowired via Laravel’s DI container.

Implementation Patterns

Core Workflows

1. Ticket Management

   • Create: Use create(array $data) for new tickets.
   • Update: Use update(int $id, array $data) for existing tickets.
   • Fetch: Use find(int $id) or list(array $filters) for retrieval.
   • Delete: Use delete(int $id) with caution (soft deletes if configured).

2. Event-Driven Extensions Subscribe to bundle events (e.g., TicketCreatedEvent) via Laravel’s event system:

   // In a service provider
   $this->app->booting(function () {
       event(new TicketCreatedEvent($ticket));
   });
   

3. API Integration

   • Configure API keys in config/pando_ticket.php:

     'api' => [
         'key' => env('PANDO_API_KEY'),
         'secret' => env('PANDO_API_SECRET'),
     ],
     

   • Use the PandoTicketClient directly for low-level API calls:

     $client = app(PandoTicketClient::class);
     $response = $client->get('/tickets/1');
     

4. Form Integration Use the PandoTicketType form type in Symfony forms:

   use BlackBoxCode\PandoTicketBundle\Form\Type\PandoTicketType;
   
   $form = $this->createForm(PandoTicketType::class, $ticket);
   

Common Integrations

• Laravel Notifications: Extend PandoTicketNotification to send ticket updates via email/SMS.
• Laravel Scout: Index tickets for search functionality by implementing a custom PandoTicketScoutEngine.
• Laravel Horizon: Queue ticket operations (e.g., dispatch(new CreateTicketJob($data))).

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Ensure PANDO_API_KEY and PANDO_API_SECRET are set in .env.
   • Debug with PandoTicketClient::setDebug(true) to log raw API requests/responses.

2. Rate Limiting

   • The bundle may throttle requests. Implement exponential backoff in custom clients:

     try {
         $response = $client->post('/tickets', $data);
     } catch (RateLimitException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

3. Data Mismatches

   • Validate input against Pando’s API schema (e.g., priority must be low|medium|high).
   • Use Laravel’s ValidatesWhen or custom rules:

     use BlackBoxCode\PandoTicketBundle\Rules\ValidPriority;
     
     $request->validate([
         'priority' => ['required', new ValidPriority],
     ]);
     

4. Soft Deletes

   • By default, delete() may soft-delete tickets. Override in config:

     'soft_deletes' => false,
     

Debugging Tips

• Log API Responses Enable debug mode in config:

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

  Check logs at storage/logs/laravel.log for raw API interactions.

• Mock the Client For testing, bind a mock PandoTicketClient in phpunit.xml:

  <env name="PANDO_TICKET_MOCK" value="true"/>
  

Extension Points

1. Custom Fields Extend the PandoTicket entity:

   class CustomPandoTicket extends PandoTicket
   {
       protected $customField = 'value';
   }
   

   Register the custom class in the bundle’s service provider.

2. Webhooks Implement a PandoWebhookHandler to process incoming webhook events:

   public function handleWebhook(array $payload)
   {
       // Parse and act on $payload
   }
   

   Bind the handler in config/pando_ticket.php:

   'webhook_handler' => \App\Services\CustomWebhookHandler::class,
   

3. API Versioning Override the default API endpoint in config:

   'api' => [
       'base_uri' => 'https://api.pando.example.com/v2',
   ],