Pumukit Blackboard Bundle Laravel Package

Getting Started

PuMuKIT is a Symfony-based video platform; this bundle is the ingestion endpoint that lets a Blackboard installation push recordings into a PuMuKIT instance. Treat it as glue code, not a library — there is essentially no documentation, so the first hour is reading source, not following a README.

Minimal steps:

1. Pin your PuMuKIT version first. Check composer.json in the bundle for pumukit/* and symfony/* constraints and compare against your PuMuKIT release. This bundle (0 stars, 0 dependents, last-touched upstream) is almost certainly tied to one PuMuKIT generation. If the constraint doesn't overlap your install, stop and budget for a fork rather than debugging a mismatch.
2. Register the bundle the PuMuKIT way — add it to app/AppKernel.php (Symfony 3-era PuMuKIT) or config/bundles.php (Symfony 4+), next to the other Pumukit*Bundle entries.
3. Read three files before anything else: DependencyInjection/Configuration.php (the config tree tells you every knob that exists — usually an auth secret/token, an optional series/tag to attach uploads to), Controller/ (the actual HTTP surface Blackboard calls), and Resources/config/routing.* (whether routes are auto-loaded or you must import them).
4. Configure credentials under the bundle's root key in app/config/config.yml (typically pumukit_blackboard:), pulling the shared secret from parameters/env rather than committing it.
5. First use case: smoke-test the endpoint by hand. Don't wire Blackboard up yet. curl the import route with a dummy payload and a valid token and watch what MultimediaObject appears in the PuMuKIT admin. That single round-trip tells you the payload schema, the auth scheme, and whether it enqueues transcoding or expects you to do it.

Implementation Patterns

Treat the bundle as an adapter behind your own service. The controller is thin; the real work is a service that resolves a MultimediaObject, stores the file, and creates tracks. Call that service from your own thin controller (or a console command) so you can add validation, logging, and retries without patching vendor code. Fork-and-vendor under src/ is the expected posture here.

Idempotency by external ID. Blackboard will retry. Store the Blackboard recording/course identifier as a tag or property on the MultimediaObject (pumukit:blackboard:<id>) and check for it before creating. If the bundle doesn't do this for you — likely — wrap the import in that lookup. Without it you get duplicate objects and duplicate transcodes on every network hiccup.

Map to PuMuKIT's object model explicitly. Decide up front which Series uploads land in (usually a course→series mapping, creating series on demand), and set MultimediaObject properties (title, description, date, language) from LMS metadata rather than defaulting. Use the PuMuKIT factory/service layer rather than instantiating documents directly, so the same event listeners that fire for manual uploads (indexing, tags, MultimediaObjectFactory behavior) fire for imports.

Push the heavy work to the queue. Store the original file, create a master track, then let PuMuKIT's normal worker/cron pipeline generate the rest. Returning a fast 202 to Blackboard and doing transcoding asynchronously avoids LMS-side HTTP timeouts, which are typically much shorter than a video ingest.

Integration tips:

• If Blackboard is driving this via an LTI launch or a Building Block, keep auth validation in the bundle/controller layer and business logic downstream, so you can swap the transport later.
• Add a bin/console command wrapping the import service for backfills and for replaying payloads captured from production logs.
• Log the raw request body (redacting the secret) to a dedicated channel; you will need it to reproduce malformed LMS payloads.

Gotchas and Tips

• Maintenance risk is the headline issue. Zero stars, zero dependents, no release cadence. Budget for a fork, pin the commit, and keep your diff small so you can rebase. Don't spread its classes through your app — confine them to one service.
• Symfony/PuMuKIT version coupling. Service definitions, routing format (routing.yml vs PHP/attributes), and AppKernel vs bundles.php all changed between PuMuKIT generations. Errors like "service not found" or routes 404ing despite being defined are almost always this.
• Auth is probably a shared secret in config. If so, it's a static bearer-style token with no rotation or per-course scoping. Verify whether it's compared with === vs hash_equals, and whether the route is behind your firewall — an import endpoint that creates objects must not be publicly reachable.
• Upload handling is the usual failure point. Check PHP upload_max_filesize, post_max_size, and the tmp dir; a truncated POST often surfaces as a confusing 500 rather than a 413. Confirm whether the bundle expects multipart/form-data or a URL/base64 payload.
• File storage and permissions. The web user must be able to write into the PuMuKIT track/storage paths. Silent failures writing tracks are common after deploys with wrong ownership.
• No migrations means schema drift. If the bundle adds fields to PuMuKIT documents, verify how they're persisted (annotations/XML mapping vs migrations); otherwise doctrine:schema:validate will complain and Mongo/ORM indexes may be missing.
• Debugging: bin/console debug:router | grep -i blackboard to confirm routes exist, debug:container for the service, and debug:config for the bundle key. That trio resolves most "is it even wired up" questions quickly.
• Extension points are mostly Symfony's, not the bundle's. Prefer a compiler pass or service override (services.yml alias) over editing vendor files where possible; if you must patch, keep a PATCHES.md and a composer patch entry so upgrades don't silently drop it.
• Add observability yourself. The bundle likely emits little telemetry; wrap the import service in a timing/logging decorator and emit a metric per outcome — you'll want it the first time Blackboard reports "import succeeded" and nothing appears in PuMuKIT.