Bigbluebutton Api Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bigbluebutton/bigbluebutton-api-php:^2.3.1
   

   Update your composer.json and run composer update.

2. Basic Configuration Create a BigBlueButton client instance in your Laravel service provider or config file:

   use BigBlueButton\BigBlueButton;
   
   $bbb = new BigBlueButton([
       'url' => env('BBB_URL', 'https://demo.bigbluebutton.org/bigbluebutton/'),
       'secret' => env('BBB_SECRET', 'your-secret-key'),
   ]);
   

3. First Use Case: Create a Meeting

   $meeting = $bbb->createMeeting([
       'name' => 'Team Sync',
       'meetingID' => 'team-sync-123',
       'attendeePW' => 'password123',
       'moderatorPW' => 'moderator123',
       'record' => true,
   ]);
   

   Verify the response with dd($meeting) to confirm meeting details.

4. New Feature: Insert Document

   $documentId = $bbb->insertDocument([
       'meetingID' => 'team-sync-123',
       'document' => base64_encode(file_get_contents('path/to/document.pdf')),
       'name' => 'Meeting Notes',
   ]);
   

Key Files to Reference

• Documentation: Check the official API docs for endpoint specifics.
• Source: Review src/BigBlueButton.php for core methods, including the new insertDocument method.
• Exceptions: Check src/Exceptions/ for error handling, especially for the new API endpoints.

Implementation Patterns

Common Workflows

1. Meeting Management

• Create Meetings Dynamically

  $meeting = $bbb->createMeeting([
      'name' => 'Laravel Workshop',
      'meetingID' => Str::uuid()->toString(),
      'attendeePW' => Str::random(10),
      'moderatorPW' => Str::random(10),
      'record' => true,
      'recordFormat' => 'mp4',
  ]);
  

• Join a Meeting

  $joinUrl = $bbb->getJoinUrl($meeting['meetingID']);
  return redirect()->away($joinUrl);
  

• End a Meeting

  $bbb->endMeeting($meeting['meetingID']);
  

2. Document Management (New in 2.3.1)

• Insert a Document into a Meeting

  $document = base64_encode(file_get_contents('path/to/document.pdf'));
  $documentId = $bbb->insertDocument([
      'meetingID' => $meeting['meetingID'],
      'document' => $document,
      'name' => 'Project Requirements',
      'description' => 'Discussion notes for the project',
  ]);
  

• List Documents in a Meeting

  $documents = $bbb->getMeetingDocuments($meeting['meetingID']);
  foreach ($documents as $doc) {
      // Process or display document metadata
  }
  

3. User Management

• List Users in a Meeting

  $users = $bbb->getMeetingUsers($meeting['meetingID']);
  foreach ($users as $user) {
      // Log or process user data
  }
  

• Mute/Unmute Users

  $bbb->muteUser($meeting['meetingID'], $userId, true); // Mute
  $bbb->muteUser($meeting['meetingID'], $userId, false); // Unmute
  

4. Webhooks for Real-Time Events

Configure webhooks in your Laravel app to handle BBB events:

// In your BBB config
$bbb->setWebhookUrl(route('bbb.webhook'));

// In your routes file
Route::post('/bbb/webhook', [BbbWebhookController::class, 'handle']);

5. Recording Management

• List Recordings

  $recordings = $bbb->getRecordings();
  foreach ($recordings as $recording) {
      if ($recording['recorded']) {
          $playbackUrl = $bbb->getPlaybackUrl($recording['recordId']);
      }
  }
  

• Delete a Recording

  $bbb->deleteRecording($recording['recordId']);
  

Integration Tips

• Laravel Service Provider Bind the BBB client to the container for dependency injection:

  $this->app->singleton(BigBlueButton::class, function ($app) {
      return new BigBlueButton([
          'url' => config('bbb.url'),
          'secret' => config('bbb.secret'),
      ]);
  });
  

• Queue Delayed Actions For long-running tasks (e.g., document processing), use Laravel queues:

  dispatch(new ProcessDocumentJob($documentId, $meetingId));
  

• Rate Limiting Implement middleware to throttle BBB API calls:

  Route::middleware(['throttle:10,1'])->group(function () {
      Route::post('/bbb/webhook', [BbbWebhookController::class, 'handle']);
  });
  

Gotchas and Tips

Pitfalls

1. Secret Key Validation

   • BBB validates requests using the secret key. Ensure it matches the server’s key.
   • Error: 403 Forbidden or malformed responses may indicate a mismatched secret.
   • Fix: Double-check config('bbb.secret') and regenerate it if needed.

2. Meeting ID Collisions

   • Reusing meetingID without ending the previous meeting will fail.
   • Fix: Use UUIDs or timestamps (e.g., meeting- . now()->format('YmdHis')) for IDs.

3. Webhook Signature Verification

   • BBB sends a Signature header for webhooks. Always verify it:

   public function validateWebhook(array $payload) {
       $expectedSignature = hash_hmac(
           'sha1',
           $payload['payload'],
           config('bbb.secret')
       );
       if (!hash_equals($request->header('Signature'), $expectedSignature)) {
           abort(403, 'Invalid webhook signature');
       }
   }
   

4. Rate Limits

   • BBB may throttle requests. Handle 429 Too Many Requests gracefully:

   try {
       $bbb->createMeeting($data);
   } catch (BigBlueButtonException $e) {
       if ($e->getCode() === 429) {
           sleep(2); // Retry after delay
           retry();
       }
       throw $e;
   }
   

5. Document Size Limits

   • Large documents may fail to upload. Ensure documents are within BBB's size limits (typically < 10MB).
   • Fix: Compress or split large documents before uploading.

6. URL Builder Fix (2.3.1)

   • The urlBuilder property was fixed in this release. Ensure your custom configurations align with the updated structure if you previously extended the class.

Debugging Tips

• Enable Debugging Set the debug option in the BBB client:

  $bbb = new BigBlueButton([
      'url' => config('bbb.url'),
      'secret' => config('bbb.secret'),
      'debug' => true, // Logs requests/responses
  ]);
  

  Check Laravel logs for raw API interactions.

• Test with Demo Instance Use the BBB demo server for testing:

  $bbb = new BigBlueButton([
      'url' => 'https://demo.bigbluebutton.org/bigbluebutton/',
      'secret' => 'your-demo-secret', // Check BBB docs for demo secrets
  ]);
  

Extension Points

1. Custom Exceptions Extend the BigBlueButtonException class to handle domain-specific errors:

   class BbbDocumentException extends BigBlueButtonException {}
   

2. API Response Wrappers Create a decorator for responses to standardize data, including document metadata:

   class BbbDocumentDecorator {
       public static function decorate(array $document) {
           return [
               'id' => $document['documentId'],
               'name' => $document['name'],
               'meeting_id' => $document['meetingID'],
               'uploaded_at' => $document['uploadTime'],
               'download_url' => route('bbb.download', $document['documentId']),
           ];
       }
   }
   

3. Event Dispatching for Documents Trigger Laravel events for document-related actions:

   $documentId = $bb