Php Autopilothq Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require picr/php-autopilothq
   

   Add API key to your .env:

   AUTPILOTHQ_API_KEY=your_api_key_here
   

2. First Use Case: Initialize the manager and fetch a contact:

   use Picr\AutopilotHQ\AutopilotManager;
   
   $manager = new AutopilotManager(config('services.autopilothq.key'));
   $contact = $manager->getContact('user@example.com');
   

3. Where to Look First:

   • Core Class: AutopilotManager (all API interactions).
   • Contact Handling: AutopilotContact (data manipulation).
   • README.md: Quick reference for methods and examples.

Implementation Patterns

Usage Patterns

1. Contact Management Workflow:

   // Create/update a contact
   $contact = new AutopilotContact();
   $contact->fill([
       'firstName' => 'John',
       'email'     => 'john@example.com',
       'customField' => 'value'
   ]);
   $manager->saveContact($contact);
   
   // Bulk operations
   $contacts = collect([...])->map(function ($data) {
       $contact = new AutopilotContact();
       $contact->fill($data);
       return $contact;
   });
   $manager->saveContacts($contacts->all());
   

2. List and Journey Integration:

   // Add contact to a list/journey
   $manager->addContactToList('Marketing Newsletter', 'john@example.com');
   $manager->addContactToJourney('Welcome Series', 'john@example.com');
   
   // Check list membership
   if ($manager->checkContactInList('Newsletter', 'john@example.com')) {
       // Handle logic
   }
   

3. Webhook Setup:

   // Register a webhook for contact updates
   $manager->addRestHook('contact_updated', 'https://your-app.com/webhooks/autopilothq');
   

4. Laravel Integration:

   // Service Provider Binding
   $this->app->singleton(AutopilotManager::class, function ($app) {
       return new AutopilotManager(config('services.autopilothq.key'));
   });
   
   // Facade (optional)
   facade(AutopilotManager::class, 'Autopilot');
   

5. Event-Driven Workflows:

   // Laravel Event Listener for webhooks
   public function handle(IncomingWebhook $event) {
       if ($event->data['event'] === 'contact_updated') {
           $contact = $manager->getContact($event->data['email']);
           // Trigger business logic
       }
   }
   

Integration Tips

• Caching: Cache API responses (e.g., lists, contacts) to reduce calls:

  $contacts = Cache::remember("autopilothq_contacts_{$list}", now()->addHours(1), function () use ($manager, $list) {
      return $manager->getAllContactsInList($list);
  });
  

• Error Handling: Wrap API calls in try-catch blocks:

  try {
      $manager->saveContact($contact);
  } catch (\Exception $e) {
      Log::error("AutopilotHQ Error: " . $e->getMessage());
      // Retry or notify admin
  }
  

• Batch Processing: Use Laravel queues for large operations:

  foreach ($contacts as $contact) {
      SyncContactJob::dispatch($contact)->onQueue('autopilothq');
  }
  

Gotchas and Tips

Pitfalls

1. API Key Management:

   • Issue: Hardcoded keys in the wrapper.
   • Fix: Always inject the key via constructor or Laravel config:

     $manager = new AutopilotManager(config('services.autopilothq.key'));
     

2. Deprecated API:

   • Issue: AutopilotHQ’s API may have changed since 2017.
   • Fix: Verify endpoints/methods against current API docs. Use dd($manager->getContact(...)); to inspect responses.

3. Custom Fields:

   • Issue: Dynamic field names may cause errors.
   • Fix: Use setFieldValue() instead of magic methods for custom fields:

     $contact->setFieldValue('custom_field_name', 'value');
     

4. Rate Limiting:

   • Issue: No built-in rate limit handling.
   • Fix: Implement exponential backoff or use Laravel’s retry helper:

     $response = retry(3, function () use ($manager) {
         return $manager->getAllContactsInList('list_name');
     }, 100);
     

5. Webhook Delays:

   • Issue: REST hooks may not fire immediately.
   • Fix: Implement idempotency checks in your webhook handler.

Debugging

• Enable Debugging:

  $manager = new AutopilotManager($apiKey, [
      'debug' => true,
  ]);
  

• Log API Responses:

  $manager->setLogger(function ($message) {
      Log::debug($message);
  });
  

• Common Errors:
  • 404 Not Found: Verify contact/list IDs or names.
  • 422 Unprocessable Entity: Validate AutopilotContact data with toArray().
  • 500 Server Error: Check AutopilotHQ status or API key.

Config Quirks

• HTTP Client:
  • The wrapper uses PHP’s native curl or file_get_contents. Replace with Laravel’s Http client for consistency:

    // Override the HTTP client in AutopilotManager (if extensible)
    $manager->setHttpClient(app('http'));
    

• Timeouts:
  • Default timeout may be too short for large batches. Adjust in Laravel’s Http client config:

    'timeout' => 60,
    

Extension Points

1. Custom HTTP Client:

   • Extend AutopilotManager to use Guzzle or Laravel’s Http client:

     class LaravelAutopilotManager extends AutopilotManager {
         public function __construct($apiKey) {
             parent::__construct($apiKey);
             $this->setHttpClient(app('http'));
         }
     }
     

2. Eloquent Integration:

   • Create a local Contact model that syncs with AutopilotHQ:

     class Contact extends Model {
         public function syncToAutopilot() {
             $manager = app(AutopilotManager::class);
             $autopilotContact = new AutopilotContact($this->toArray());
             $manager->saveContact($autopilotContact);
         }
     }
     

3. Event Dispatching:

   • Trigger Laravel events for AutopilotHQ actions:

     $manager->afterSaveContact(function ($contact) {
         event(new ContactSynced($contact));
     });
     

4. Testing:

   • Mock the AutopilotManager in tests:

     $mockManager = Mockery::mock(AutopilotManager::class);
     $mockManager->shouldReceive('getContact')->andReturn($fakeContact);
     $this->app->instance(AutopilotManager::class, $mockManager);