Bigbluebutton Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ibondoc/bigbluebutton
   

   Publish the config file:

   php artisan vendor:publish --provider="Ibondoc\Bigbluebutton\BigbluebuttonServiceProvider"
   

   Configure .env with your BigBlueButton server URL and secret:

   BIGBLUEBUTTON_URL=https://your-bbb-server.com/bigbluebutton/api/
   BIGBLUEBUTTON_SECRET=your-secret-key
   

2. First Use Case: Verify connectivity by checking if the API endpoint is reachable:

   use Ibondoc\Bigbluebutton\Facades\Bigbluebutton;
   
   $response = Bigbluebutton::checkConnection();
   dd($response); // Should return `true` if successful
   

3. Key Files:

   • config/bigbluebutton.php: Central configuration.
   • app/Providers/BigbluebuttonServiceProvider.php: Service binding.
   • app/Facades/Bigbluebutton.php: Facade for easy access.

Implementation Patterns

Core Workflows

1. Meeting Creation

Create a meeting with default settings:

$meeting = Bigbluebutton::createMeeting([
    'name' => 'Team Sync',
    'attendeeName' => 'John Doe',
    'moderatorPW' => 'moderator123',
    'viewPassword' => 'viewer123',
    'record' => true,
]);
dd($meeting); // Returns meeting ID and join URL

Dynamic Configuration: Use a model or service to encapsulate meeting logic:

class MeetingService {
    public function createMeetingForUser(User $user, string $topic) {
        return Bigbluebutton::createMeeting([
            'name' => $topic,
            'attendeeName' => $user->name,
            'moderatorPW' => Str::random(8),
            'viewPassword' => Str::random(8),
        ]);
    }
}

2. Slides Management

Upload slides for a meeting:

$slideResponse = Bigbluebutton::uploadSlides($meetingId, [
    'slide' => fopen('path/to/slide.pdf', 'r'),
    'name' => 'Slide Deck',
]);

Workflow Integration: Trigger slide uploads post-meeting creation:

$meeting = Bigbluebutton::createMeeting([...]);
Bigbluebutton::uploadSlides($meeting['meetingID'], [...]);

3. Webhook Callbacks

Handle meeting end callbacks in Laravel routes:

Route::post('/bbb-webhook', function (Request $request) {
    $payload = $request->all();
    // Validate payload (e.g., check secret)
    if (Bigbluebutton::validateWebhook($payload)) {
        // Process meeting end (e.g., update DB, send notifications)
        event(new MeetingEnded($payload['meetingID']));
    }
    return response()->json(['status' => 'success']);
});

Validation: Always validate webhook payloads:

$isValid = Bigbluebutton::validateWebhook($request->all(), config('bigbluebutton.secret'));

4. Recording Management

Fetch recordings for a meeting:

$recordings = Bigbluebutton::getRecordings($meetingId);
foreach ($recordings as $recording) {
    // Process recording (e.g., store in DB, generate links)
}

Automated Processing: Use Laravel queues to handle recording post-processing:

dispatch(new ProcessRecordingJob($meetingId, $recordingData));

Integration Tips

1. Eloquent Models

Attach BigBlueButton data to Eloquent models:

class Meeting extends Model {
    public function createBbMeeting() {
        $response = Bigbluebutton::createMeeting([
            'name' => $this->topic,
            'attendeeName' => $this->organizer->name,
        ]);
        $this->meeting_id = $response['meetingID'];
        $this->save();
        return $response;
    }
}

2. API Rate Limiting

Implement Laravel middleware to throttle BigBlueButton API calls:

class ThrottleBigbluebuttonRequests {
    public function handle($request, Closure $next) {
        return $next($request)->throttle('bbb-api', 60); // 60 calls/minute
    }
}

3. Testing

Mock the BigBlueButton API in tests:

$this->partialMock(Bigbluebutton::class, 'createMeeting')
     ->shouldReceive('createMeeting')
     ->andReturn(['meetingID' => 'test123']);

Gotchas and Tips

Pitfalls

1. Secret Mismanagement

• Issue: Hardcoding secrets in .env or config files.
• Fix: Use Laravel's env() function or environment variables exclusively. Avoid committing .env to version control.

2. Webhook Validation Bypass

• Issue: Skipping payload validation in webhook endpoints.
• Fix: Always validate the signature header or payload secret:

  $isValid = Bigbluebutton::validateWebhook($payload, config('bigbluebutton.secret'));
  

3. Rate Limiting

• Issue: Exceeding BigBlueButton API rate limits (e.g., too many meeting creations).
• Fix: Implement retries with exponential backoff:

  use Ibondoc\Bigbluebutton\Exceptions\RateLimitExceeded;
  
  try {
      $meeting = Bigbluebutton::createMeeting([...]);
  } catch (RateLimitExceeded $e) {
      sleep($e->getRetryAfter());
      retry();
  }
  

4. Timeouts

• Issue: Long-running API calls timing out.
• Fix: Increase Laravel's HTTP client timeout:

  Bigbluebutton::setTimeout(60); // 60 seconds
  

5. Recording Cleanup

• Issue: Orphaned recordings if meetings are deleted but recordings persist.
• Fix: Implement a cleanup job:

  class CleanupOldRecordingsJob implements ShouldQueue {
      public function handle() {
          $oldMeetings = Meeting::where('ended_at', '<', now()->subDays(30))->get();
          foreach ($oldMeetings as $meeting) {
              Bigbluebutton::deleteRecording($meeting->meeting_id);
              $meeting->delete();
          }
      }
  }
  

Debugging Tips

1. Enable Logging

Configure the package to log API requests/responses:

'debug' => env('BBB_DEBUG', false),

Check logs in storage/logs/laravel.log for raw API interactions.

2. API Response Inspection

Use dd() or dump() to inspect raw responses:

$response = Bigbluebutton::createMeeting([...]);
dd($response->getOriginalContent()); // Raw API response

3. Common Errors

• 403 Forbidden: Incorrect secret or URL. Verify .env values.
• 500 Internal Server Error: Invalid payload. Check BigBlueButton server logs.
• 429 Too Many Requests: Hit rate limits. Implement retries.

Extension Points

1. Custom API Endpoints

Extend the package to support non-standard BigBlueButton endpoints:

class ExtendedBigbluebutton extends Bigbluebutton {
    public function customEndpoint(array $data) {
        return $this->client->post('custom/endpoint', $data);
    }
}

2. Event Dispatching

Trigger Laravel events for BigBlueButton actions:

event(new MeetingCreated($meetingId, $meetingData));

3. Middleware for Authentication

Add middleware to authenticate API calls:

Bigbluebutton::setAuthMiddleware(function ($request) {
    $request->headers->set('Authorization', 'Bearer ' . config('bigbluebutton.token'));
});

4. Queueable Jobs

Offload long-running operations to queues:

class UploadSlidesJob implements ShouldQueue {
    use Dispatchable, InteractsWithQueue, Queueable;

    public function handle() {
        Bigbluebutton::uploadSlides($this->meetingId, $this->slides);
    }
}