Ux Zoom Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aziz403/ux-zoom
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Aziz403\UxZoom\UxZoomBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference Aziz403\UxZoomBundle
   

   Update config/packages/ux_zoom.yaml with your Zoom API credentials:

   ux_zoom:
       api_key: '%env(ZOOM_API_KEY)%'
       api_secret: '%env(ZOOM_API_SECRET)%'
   

3. First Use Case: Embedding a Meeting Use the UxZoomMeetingEmbed component in Twig:

   {{ render(controller('Aziz403\\UxZoom\\Controller\\MeetingController::embedMeetingAction', {
       'meetingId': '1234567890',
       'meetingSecret': 'your_meeting_secret'
   })) }}
   

Implementation Patterns

Common Workflows

1. Meeting Creation Use the ZoomService to create meetings programmatically:

   $zoomService = $this->container->get('ux_zoom.zoom_service');
   $meeting = $zoomService->createMeeting([
       'topic' => 'Team Sync',
       'type' => 2, // Scheduled
       'start_time' => '2023-12-25T10:00:00',
       'duration' => 60,
   ]);
   

2. Webhook Handling Register a route for Zoom webhooks (e.g., meeting.started):

   # config/routes.yaml
   ux_zoom_webhook:
       path: /zoom/webhook
       controller: Aziz403\UxZoom\Controller\WebhookController::handle
   

   Validate payloads in your controller:

   public function handle(Request $request, ZoomService $zoomService)
   {
       $payload = json_decode($request->getContent(), true);
       if (!$zoomService->validateWebhook($payload)) {
           throw new \RuntimeException('Invalid webhook signature');
       }
       // Process event...
   }
   

3. Twig Integration Pass meeting data to templates:

   return $this->render('meeting/show.html.twig', [
       'meeting' => $meeting,
       'joinUrl' => $zoomService->getJoinUrl($meeting),
   ]);
   

   Use Twig helpers for embeds:

   {{ ux_zoom_embed(meeting) }}
   

Integration Tips

• Environment Variables Store sensitive keys in .env:

  ZOOM_API_KEY=your_api_key
  ZOOM_API_SECRET=your_api_secret
  ZOOM_WEBHOOK_SECRET=your_webhook_secret
  

• Dependency Injection Bind the ZoomService to your controllers/services:

  use Aziz403\UxZoom\Service\ZoomService;
  
  public function __construct(private ZoomService $zoomService) {}
  

• Event Listeners Subscribe to Zoom events (e.g., MeetingCreatedEvent):

  // src/EventListener/MeetingListener.php
  public function onMeetingCreated(MeetingCreatedEvent $event)
  {
      // Send notification, log, etc.
  }
  

  Register in services.yaml:

  services:
      App\EventListener\MeetingListener:
          tags:
              - { name: kernel.event_listener, event: ux_zoom.meeting.created }
  

Gotchas and Tips

Pitfalls

1. Webhook Validation

   • Issue: Webhook payloads may fail signature validation if the ZOOM_WEBHOOK_SECRET is misconfigured or the request timestamp is out of sync.
   • Fix: Ensure the server clock is accurate and the secret matches the Zoom app setting.

2. Meeting Secrets

   • Issue: Hardcoding meetingSecret in templates exposes security risks.
   • Fix: Fetch secrets dynamically via the ZoomService:

     $meetingSecret = $zoomService->getMeetingSecret($meetingId);
     

3. Rate Limiting

   • Issue: Exceeding Zoom API rate limits (e.g., 15 requests/minute for free tier) may cause 429 errors.
   • Fix: Implement retries with exponential backoff:

     try {
         $zoomService->createMeeting($data);
     } catch (\GuzzleHttp\Exception\RequestException $e) {
         if ($e->getCode() === 429) {
             sleep(2); // Retry after delay
             retry();
         }
     }
     

4. Deprecated Methods

   • Issue: The package lacks type hints and may use older Symfony versions (e.g., ^4.4.17).
   • Fix: Override services in config/services.yaml to enforce stricter types:

     Aziz403\UxZoom\Service\ZoomService:
         arguments:
             $client: '@http_client' # Use Symfony's HTTP client
     

Debugging Tips

1. Enable API Logging Configure Guzzle middleware to log requests:

   // config/packages/ux_zoom.yaml
   ux_zoom:
       debug: true
   

   Check logs in var/log/dev.log for API responses/errors.

2. Test Webhooks Locally Use ngrok to expose a local endpoint for testing:

   ngrok http 8000
   

   Configure the Zoom app to send webhooks to https://your-ngrok-url.ngrok.io/zoom/webhook.

3. Validate API Responses Inspect raw responses for errors:

   $response = $zoomService->createMeeting($data);
   if ($response->getStatusCode() !== 201) {
       $error = json_decode($response->getBody(), true);
       throw new \RuntimeException($error['message'] ?? 'Unknown error');
   }
   

Extension Points

1. Custom Meeting Fields Extend the Meeting entity by overriding the service:

   // src/Service/CustomZoomService.php
   class CustomZoomService extends \Aziz403\UxZoom\Service\ZoomService
   {
       public function createMeeting(array $data): Meeting
       {
           $data['custom_field'] = 'value'; // Add custom data
           return parent::createMeeting($data);
       }
   }
   

   Bind it in services.yaml:

   services:
       ux_zoom.zoom_service:
           class: App\Service\CustomZoomService
   

2. Add Event Subscribers Extend the bundle’s event system:

   // src/EventSubscriber/ZoomSubscriber.php
   class ZoomSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'ux_zoom.meeting.created' => 'onMeetingCreated',
           ];
       }
   
       public function onMeetingCreated(MeetingCreatedEvent $event)
       {
           // Custom logic
       }
   }
   

3. Override Twig Functions Replace the default ux_zoom_embed function:

   {% macro customEmbed(meeting) %}
       <div class="custom-zoom-embed">
           {{- include('Aziz403UxZoom::meeting/embed.html.twig', {
               meeting: meeting,
               joinUrl: app.service('ux_zoom.zoom_service').getJoinUrl(meeting)
           }) -}}
       </div>
   {% endmacro %}