phil / virtual-classroom
Live online classes behind one port: BigBlueButton and Jitsi rooms, signed join links per role, attendance with arrival and departure times, recordings.
Package info
github.com/parler-haut-interagir-librement/virtual-classroom
pkg:composer/phil/virtual-classroom
Requires
- php: >=8.5
- ext-dom: *
- ext-libxml: *
- ext-mbstring: *
- ext-openssl: *
- ext-sodium: *
- phil/url: ^0.1@dev
- psr/clock: ^1.0
- symfony/http-client-contracts: ^3.6
Requires (Dev)
- phpunit/phpunit: ^13.4
- symfony/clock: ^8.2
- symfony/http-client: ^8.2
Suggests
- symfony/http-client: For the HTTP client the BigBlueButton adapter calls its server with
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 03:05:44 UTC
README
Live online classes through one port: open a room on a conferencing server, write the link each participant joins by — signed for a moderator or an attendee —, end it, know who attended and for how long, and find its recordings; BigBlueButton and Jitsi first.
phil/virtual-classroom is a plain PHP library. An application talks to a VirtualClassroom: it opens a room from
a RoomSpec — its identifier, its title, whether it records, the longest it runs, the addresses the server calls back —,
writes the join link of a Participant for a Role, ends the room, asks who is in it now, lists its
recordings, and reads the notifications the server sends — participants joining and leaving, the room ended, a
recording ready — as RoomEvents. AttendanceSheet turns the stays of a participant into the seconds and the share
of the session they attended, overlaps counted once.
Two adapters ship. BigBlueButton calls its server's API over Symfony's HTTP client contracts, every call signed
by the checksum of the secret it shares with the server, each call bounded in time and in size; it reads the end of a
room, the recording ready notification signed with HS256 and the attendance its learning analytics callback posts.
Jitsi writes join links that carry a JSON Web Token: HS256 for a server of the application's own, RS256 for JaaS,
8x8's hosted Jitsi; it reads the notifications JaaS signs with HMAC-SHA-256. Jitsi has no API to end a room or to list
who is in it: those calls throw Unsupported, and capabilities() says so beforehand.
Every failure is an exception of the library — ProviderUnavailable, ProviderRefused, InvalidResponse,
InvalidWebhook, Unsupported, InvalidValue — whose message names no participant and carries no address of a call.
Participants travel by the stable identifier of their account, never by their e-mail address. The adapters keep no
state between calls and serve a long-running worker.
Status
| Part | State |
|---|---|
VirtualClassroom, RoomEvent, RoomId, ParticipantId, Participant, Role, RoomSpec, OpenedRoom, Capabilities, Presences, RoomState, Recording, Webhook |
Implemented and tested |
The events ParticipantJoined, ParticipantLeft, RoomEnded, RecordingReady and the exceptions |
Implemented and tested |
AttendanceSheet, Interval: the seconds and the share of a session attended |
Implemented and tested |
HttpBudget: the time and the size a call may take |
Implemented and tested |
BigBlueButton, ChecksumAlgorithm: rooms, join links, end, presences, recordings, notifications |
Implemented and tested |
Jitsi: join links for a server of the application's own or JaaS, notifications |
Implemented and tested |
| Zoom and Microsoft Teams adapters | Not written |
Documentation
| Document | What it covers |
|---|---|
| Installation | Requirements and installing. |
| Rooms and join links | The port, a room's life, the roles, the participants. |
| BigBlueButton | The adapter: checksums, callbacks, presences, recordings, attendance. |
| Jitsi | The adapter: tokens for a server of the application's own and JaaS, notifications, limits. |
| Attendance | Stays, events and the share of a session attended. |
| Errors and budgets | The exceptions, the time and size bounds, what the logs may keep. |
| Security | Secrets, signatures, personal data, and what is left to the application. |
| Extension points | Writing another adapter, and when the API is stable. |
| Testing | The tests, the fuzz target and the benchmark. |
| Reference | Every public type, with its role. |
Quick start
use Phil\Url\Url; use Phil\VirtualClassroom\BigBlueButton\BigBlueButton; use Phil\VirtualClassroom\Participant; use Phil\VirtualClassroom\ParticipantId; use Phil\VirtualClassroom\Role; use Phil\VirtualClassroom\RoomId; use Phil\VirtualClassroom\RoomSpec; $server = new BigBlueButton($httpClient, Url::fromString('https://bbb.example.com/bigbluebutton/api/'), $secret, $clock); $room = $server->open(new RoomSpec(RoomId::generate(), 'Algebra, week 3', record: true, maxMinutes: 90)); $link = $server->joinUrl($room, new Participant(ParticipantId::fromString('user-7'), 'Ada Lovelace'), Role::Attendee);
Requirements
PHP 8.5 or later with the dom, libxml, mbstring, openssl and sodium extensions; an implementation of the
Symfony HTTP client contracts, symfony/http-client, for BigBlueButton.
Contributing
Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.
License
MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Parler Haut Interagir Librement project. See LICENSE.