Highrise Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require 20steps/highrise-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       HighriseBundle\HighriseBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config and update config/packages/highrise.yaml:

   highrise:
       api_key: '%env(HIGHRISE_API_KEY)%'
       subdomain: 'your_subdomain' # e.g., 'yourcompany' for yourcompany.highrisehq.com
       version: 'v1' # or 'v2' if using Highrise v2 API
   

3. First Use Case Fetch a list of contacts:

   use HighriseBundle\Highrise\HighriseClient;
   
   class SomeService
   {
       public function __construct(private HighriseClient $highrise)
       {
       }
   
       public function getContacts()
       {
           return $this->highrise->get('contacts');
       }
   }
   

Implementation Patterns

Common Workflows

1. CRUD Operations Use the client methods for standard API calls:

   // Create
   $contact = $this->highrise->post('contacts', ['first_name' => 'John']);
   
   // Read
   $contact = $this->highrise->get('contacts/123');
   
   // Update
   $this->highrise->put('contacts/123', ['last_name' => 'Doe']);
   
   // Delete
   $this->highrise->delete('contacts/123');
   

2. Querying with Filters Pass query parameters for filtering:

   $contacts = $this->highrise->get('contacts', [
       'query' => 'John Doe',
       'page' => 2,
       'per_page' => 50,
   ]);
   

3. Handling Responses The client returns Symfony\Component\HttpFoundation\Response objects. Use:

   $response = $this->highrise->get('contacts');
   $data = json_decode($response->getContent(), true);
   

4. Dependency Injection Inject HighriseClient into services or controllers:

   public function __construct(
       private HighriseClient $highrise,
       private EntityManagerInterface $em
   ) {}
   

5. Batch Operations Use the post method with collections:

   $this->highrise->post('contacts/batch', [
       'contacts' => [
           ['first_name' => 'Alice', 'email' => 'alice@example.com'],
           ['first_name' => 'Bob', 'email' => 'bob@example.com'],
       ],
   ]);
   

Integration Tips

1. Symfony Forms Bind Highrise data to forms using DataTransformer or PropertyAccess:

   use Symfony\Component\Form\DataTransformerInterface;
   
   class HighriseContactTransformer implements DataTransformerInterface
   {
       public function __construct(private HighriseClient $highrise) {}
   
       public function transform($contact): ?array
       {
           return $contact ? ['id' => $contact['id']] : null;
       }
   
       public function reverseTransform($data): ?array
       {
           return $this->highrise->get("contacts/{$data['id']}");
       }
   }
   

2. Event Listeners Sync Highrise data with your app on events (e.g., UserCreatedEvent):

   public function onUserCreated(UserCreatedEvent $event)
   {
       $this->highrise->post('contacts', [
           'first_name' => $event->getUser()->getFirstName(),
           'email' => $event->getUser()->getEmail(),
       ]);
   }
   

3. Doctrine Entities Map Highrise resources to Doctrine entities:

   #[ORM\Entity]
   class Contact
   {
       #[ORM\Id]
       private ?int $highriseId;
   
       #[ORM\Column]
       private string $firstName;
   
       // Getters/setters...
   }
   

4. Command Bus Use Symfony’s CommandBus for async operations:

   $this->commandBus->dispatch(new SyncHighriseContactsCommand());
   

Gotchas and Tips

Pitfalls

1. API Versioning

   • The bundle defaults to v1. If using Highrise v2, explicitly set version: 'v2' in config.
   • v2 has breaking changes (e.g., pagination uses page[number] instead of page).

2. Rate Limiting

   • Highrise enforces 60 requests/minute. Cache responses aggressively:

     $cache = $this->cache->get('highrise_contacts', function () {
         return $this->highrise->get('contacts');
     }, 300); // Cache for 5 minutes
     

3. Authentication Failures

   • If 401 Unauthorized occurs, verify:
     • api_key is correct in highrise.yaml.
     • The key has read/write permissions in Highrise.
     • The subdomain matches your Highrise account URL.

4. Data Mismatches

   • Highrise fields may not align 1:1 with your app. Use mapping services:

     $mappedContact = $this->highriseMapper->mapToEntity($highriseContact);
     

5. Deprecated Endpoints

   • Some endpoints (e.g., /people) may be deprecated in v2. Check Highrise API docs for updates.

Debugging

1. Enable Debug Mode Set debug: true in highrise.yaml to log requests/responses:

   highrise:
       debug: true
   

   Logs appear in var/log/dev.log.

2. Manual API Testing Use curl to test endpoints directly:

   curl -X GET \
     -H "Authorization: Basic YOUR_API_KEY" \
     "https://your_subdomain.highrisehq.com/api/v1/contacts.json"
   

3. Error Handling Wrap API calls in try-catch:

   try {
       $this->highrise->get('contacts/999');
   } catch (\HighriseBundle\Exception\HighriseException $e) {
       $this->logger->error('Highrise error: ' . $e->getMessage());
       // Fallback logic
   }
   

Extension Points

1. Custom HTTP Client Override the default Guzzle client by binding your own:

   # config/services.yaml
   services:
       HighriseBundle\Highrise\HighriseClient:
           arguments:
               $client: '@your_custom_http_client'
   

2. Response Transformers Extend HighriseClient to auto-transform responses:

   class CustomHighriseClient extends HighriseClient
   {
       protected function transformResponse(Response $response): array
       {
           $data = parent::transformResponse($response);
           return $this->customMapper->map($data);
       }
   }
   

3. Webhook Handling Use Symfony’s EventDispatcher to process Highrise webhooks:

   // src/EventListener/HighriseWebhookListener.php
   public function onKernelRequest(GetResponseEvent $event)
   {
       if ($event->isMasterRequest() && $this->isHighriseWebhook()) {
           $this->dispatcher->dispatch(new HighriseWebhookEvent($this->request));
       }
   }
   

4. Testing Mock HighriseClient in PHPUnit:

   $mockClient = $this->createMock(HighriseClient::class);
   $mockClient->method('get')->willReturn(new Response(json_encode(['id' => 1])));
   
   $service = new YourService($mockClient);