Bigbluebutton Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require joisarjignesh/bigbluebutton
   

   Publish the config file:

   php artisan vendor:publish --provider="Joisarjignesh\BigBlueButton\BigBlueButtonServiceProvider"
   

   Configure .env with your BigBlueButton server URL and secret:

   BBB_URL=https://your-bigbluebutton-server.com/bigbluebutton/api/
   BBB_SECRET=your-secret-key
   

2. First Use Case: Create a Meeting Inject the BigBlueButton facade or service into a controller:

   use Joisarjignesh\BigBlueButton\Facades\BigBlueButton;
   
   public function createMeeting()
   {
       $meeting = BigBlueButton::createMeeting([
           'name' => 'Team Sync',
           'meetingID' => 'team-sync-123',
           'attendeePW' => 'password123',
           'moderatorPW' => 'moderator123',
           'record' => true,
       ]);
       return response()->json($meeting);
   }
   

3. Verify Connection Use the checkConnection method to validate your credentials:

   $response = BigBlueButton::checkConnection();
   // Returns true if credentials are valid
   

Implementation Patterns

Core Workflows

1. Meeting Management

   • Create Meetings: Use createMeeting() with required parameters (name, meetingID, passwords, etc.).

     $meeting = BigBlueButton::createMeeting([
         'name' => 'Weekly Standup',
         'meetingID' => Str::uuid(),
         'attendeePW' => 'guest-pass',
         'moderatorPW' => 'host-pass',
         'record' => true,
         'voiceBridge' => '1234567890',
     ]);
     

   • Join Meetings: Redirect users to the generated join URL:

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

   • End Meetings: Trigger via API or callback:

     BigBlueButton::endMeeting($meeting['meetingID']);
     

2. Recording Handling

   • List Recordings:

     $recordings = BigBlueButton::getRecordings(['recordID' => '123']);
     

   • Publish Recordings:

     BigBlueButton::publishRecording($recordID, 'published');
     

   • Delete Recordings:

     BigBlueButton::deleteRecording($recordID);
     

3. Slides and Polls

   • Upload Slides:

     $slideUrl = BigBlueButton::uploadSlide($meeting['meetingID'], 'path/to/slide.pdf');
     

   • Create Polls:

     $poll = BigBlueButton::createPoll($meeting['meetingID'], [
         'title' => 'Feedback',
         'question' => 'How was the session?',
         'answers' => ['Good', 'Average', 'Poor'],
     ]);
     

4. Webhooks and Callbacks

   • Configure callback URLs in .env:

     BBB_END_MEETING_CALLBACK_URL=https://your-app.com/bbb/callback
     

   • Handle callbacks in a Laravel route:

     Route::post('/bbb/callback', function (Request $request) {
         $payload = $request->all();
         // Validate and process payload (e.g., update DB)
     });
     

Integration Tips

1. Service Container Binding Bind the package to a custom interface for better testability:

   $this->app->bind(
       BigBlueButtonInterface::class,
       function ($app) {
           return new BigBlueButton($app->make('config'));
       }
   );
   

2. Queue Delayed Actions Offload recording processing to a queue job:

   use Joisarjignesh\BigBlueButton\Jobs\ProcessRecording;
   
   ProcessRecording::dispatch($recordID)->delay(now()->addMinutes(5));
   

3. Laravel Events Trigger events for meeting lifecycle hooks:

   event(new MeetingCreated($meeting));
   

   Listen for events in EventServiceProvider:

   protected $listen = [
       MeetingCreated::class => [
           SendMeetingNotification::class,
       ],
   ];
   

4. API Rate Limiting Use Laravel’s rate limiting middleware for API calls:

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

Gotchas and Tips

Common Pitfalls

1. Secret Key Validation

   • Issue: checkConnection() returns false even with correct credentials.
   • Fix: Ensure the secret key in .env matches exactly (including trailing spaces/newlines) with the BigBlueButton server’s secret. Use:

     $secret = trim(file_get_contents('/path/to/bbb-secret'));
     

     Or fetch it dynamically from a secure source.

2. MeetingID Collisions

   • Issue: Duplicate meetingID errors when creating meetings.
   • Fix: Use UUIDs or timestamp-based IDs:

     $meetingID = 'meeting-' . Str::uuid();
     // OR
     $meetingID = 'meeting-' . now()->format('YmdHis');
     

3. Recording Permissions

   • Issue: getRecordings() returns empty or 403 Forbidden.
   • Fix: Verify the API user has admin or recording permissions in BigBlueButton. Check logs for detailed errors:

     $response = BigBlueButton::getRecordings();
     Log::debug($response->getContent());
     

4. Webhook Payload Validation

   • Issue: Callback payloads fail validation due to malformed data.
   • Fix: Use Laravel’s ValidateRequest to sanitize payloads:

     public function handle(Request $request) {
         $validated = $request->validate([
             'event' => 'required|string',
             'meetingID' => 'required|string',
             'internalMeetingID' => 'nullable|string',
             'secret' => 'required|string',
         ]);
     }
     

5. Timeouts and Retries

   • Issue: API calls hang or timeout during peak loads.
   • Fix: Configure Guzzle retry logic in config/bbb.php:

     'guzzle_options' => [
         'timeout' => 30,
         'connect_timeout' => 10,
         'retries' => 3,
     ],
     

Debugging Tips

1. Enable Debug Logging Add to .env:

   BBB_DEBUG=true
   

   Logs will appear in storage/logs/laravel.log.

2. Raw API Responses Inspect raw responses for debugging:

   $response = BigBlueButton::createMeeting([...]);
   Log::debug([
       'status' => $response->status(),
       'body' => $response->getBody()->getContents(),
   ]);
   

3. BigBlueButton Server Logs Check BigBlueButton’s logs/bbb-web-api.log for server-side errors.

Extension Points

1. Custom API Clients Extend the BigBlueButton class to add methods:

   namespace App\Services;
   
   use Joisarjignesh\BigBlueButton\BigBlueButton as BaseBigBlueButton;
   
   class CustomBigBlueButton extends BaseBigBlueButton {
       public function customMethod($param) {
           return $this->callApi('custom_endpoint', $param);
       }
   }
   

2. Middleware for API Calls Add middleware to log or modify requests/responses:

   $this->app->extend('bbb.client', function ($client) {
       $client->getEmitter()->addSubscriber(new BbBApiLogger());
       return $client;
   });
   

3. Database Models Create Eloquent models for meetings/recordings:

   class Meeting extends Model {
       protected $fillable = ['meeting_id', 'name', 'join_url', 'status'];
   
       public static function createFromBbB($data) {
           return self::create([
               'meeting_id' => $data['meetingID'],
               'name' => $data['name'],
               'join_url' => $data['joinUrl'],
           ]);
       }
   }
   

4. Testing Use Laravel’s HTTP testing to mock API calls:

   public function test_create_meeting() {
       $this->mockBigBlueButtonApi()
            ->shouldReceive('createMeeting')
            ->once()
            ->andReturn(['meetingID' => 'test-123']);