Bigbluebutton Api Php Laravel Package

Getting Started

Install and pin. The package targets PHP 8.2+, so it drops into Laravel 11/12 without ceremony:

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

Pin to ^3.0 even if your server is older. 3.0 is drop-in for 2.x/3.x servers and fixes several methods (getJoinUrl, putRecordingTextTrack, JSESSIONID capture) that simply never worked against a real server in 2.x.

Where to look first. Skip the README after install — it only points at the mdBook. Read, in this order:

1. docs/src/SUMMARY.md and the Create/Join parameter pages in the built docs (mdbook build docs locally, or read docs/src/ as markdown on GitHub).
2. CHANGELOG.md entry for 3.0.0 — it is effectively the migration guide, and it doubles as the only complete inventory of new Create/Join parameters.
3. tests/ — with 100% coverage claimed, the tests are the fastest way to see the exact method names and response getters for getSessions, learningDashboard, sendChatMessage, insertDocument.

There is no Laravel glue. No service provider, no config stub, no facade. You write ~30 lines once:

// config/bigbluebutton.php
return [
    'base_url' => env('BBB_BASE_URL'), // must end with /bigbluebutton/
    'secret'   => env('BBB_SECRET'),
    'timeout'  => env('BBB_TIMEOUT', 10),
];

// AppServiceProvider::register()
$this->app->singleton(BigBlueButton::class, fn () => new BigBlueButton(
    config('bigbluebutton.base_url'),
    config('bigbluebutton.secret'),
));

First use case: create a meeting, then hand the user a join URL.

$meeting = (new CreateMeetingParameters($meetingId, 'Weekly Sync'))
    ->setAttendeePW($attendeePw)
    ->setModeratorPW($moderatorPw)
    ->setWelcome('Welcome!');

$bbb->createMeeting($meeting);

return redirect()->away(
    $bbb->getJoinMeetingURL(new JoinMeetingParameters($meetingId, $user->name, $attendeePw))
);

That redirect is the canonical flow — the browser hits the BBB server directly, so the session cookie lands in the user's browser, not on your PHP process. Persist meetingId on an Eloquent model immediately; the server is the source of truth, but you need your own row for authorization and idempotency.

Implementation Patterns

Wrap it, don't scatter it. One MeetingService that takes BigBlueButton in its constructor, and returns your own DTOs or Eloquent models. Response objects (CreateMeetingResponse, GetMeetingInfoResponse, …) leak XML-era naming into your domain and will change shape as BBB 4.0 parameters land; a thin adapter keeps that contained and gives you one place to log getMessageKey() on failure.

Prefer getJoinMeetingURL() over joinMeeting(). The latter performs a server-side join and, per the changelog, skips the session cookie — it is a trap for interactive users. Reserve it for bots and health checks. Re-join parameters (existingUserID, replaceSessionToken, sessionName) plus getJoinUrl() cover the "user refreshed the tab and lost the session" case that used to require custom checksum code.

Use queues for sync, not for create. createMeeting should be synchronous — the user is waiting on a redirect. Everything else (recording listing, getRecordingTextTracks, learningDashboard, attendance reconciliation) belongs in queued jobs on a schedule. getSessions returns one Core\Session per joined user, which makes an every-five-minutes attendance job a five-line loop.

Inject a PSR-18 client for production. The default curl transport ships zero dependencies but gives you no timeout knob through the fluent API. For anything user-facing, use BigBlueButton::createWithHttpClient(new GuzzleHttp\Client(['timeout' => 5, 'connect_timeout' => 2]), $factory, $factory, $url, $secret) so the constructor params are explicit and a hung BBB box cannot exhaust your PHP-FPM workers.

Test with a stub PSR-18 client. Because the entry point is createWithHttpClient(), you can bind a fake client in the container for feature tests and never touch a live server. Assert on the generated checksum URL and the query string — that is where parameter-mapping bugs actually live (disabledFeatures serialization, empty eventID, deprecated parameters silently ignored).

Multiple BBB clusters? Don't bind a singleton. Register a factory that returns a configured BigBlueButton per tenant/region keyed off a config array, since the secret is per-server and a global singleton silently cross-authenticates.

Gotchas and Tips

The base URL is fussy. It must end in /bigbluebutton/ with the trailing slash. A missing slash produces a checksum error that looks like a bad secret, and you will spend an hour rotating secrets that were never wrong.

checksumError is almost always the secret or an encoding issue. BBB uses SHA-1 HMAC over the query string; any extra whitespace from a .env value or a parameter you add after URL construction invalidates it. Log the failing method name and the raw response body — the library surfaces message/messageKey, not the HTTP status.

Upgrade from 2.x deliberately. The 3.0 changelog lists real bugs in 2.x: the __construct($baseUrl, $secret) argument mix-up when called explicitly, getJoinUrl XML parsing against a JSON endpoint, putRecordingTextTrack sending a GET with no file, and empty list parameters serialized as empty strings on every request. If you are on 2.x and any of those "work by accident" in your tests, they will change behavior.

Deprecated parameters are now no-ops. breakoutRoomsEnabled, learningDashboardEnabled, virtualBackgroundsDisabled, copyright, webVoice, defaultLayout on Join, and webVoiceConf should all migrate to disabledFeatures / userdata-bbb_*. BBB 4.0 ignores them silently, so you get missing features with zero errors. Grep your codebase for them after upgrading.

Enums over magic strings. MeetingLayout, Feature, and PresenterPolicy accept string unions for BC, but casting in your config layer keeps typos out of a place where the server will not complain. Note Feature::LAYOUTS is no longer valid on 4.0.

eventID is intentionally sent empty on hooks. The changelog calls this out because it looks like the empty-parameter bug; it is a deliberate echo the webhooks app expects. Don't "fix" it.

Verify webhooks yourself. This package sends hook registration and hashing, but signature verification on the receiving Laravel route is your code — raw body, HMAC, timing-safe compare, and idempotency on eventID before you touch the database.

Licensing. LGPL-3.0 means linking from your app is fine, but if you patch the library in vendor/ and ship it, those modifications must be made available. Keep customizations in your own wrapper, or vendor a fork in a private Composer repo rather than editing vendor/.

Community is small — 192 stars, no dependents. There is no Stack Overflow corpus and no Laravel ecosystem blog posts to fall back on. Budget for writing your own integration tests against a real BBB server (.env.local with BBB_SERVER_BASE_URL/BBB_SECRET), because the unit suite mocks the transport and will not catch a server-side parameter rename.