Pumukit Opencast Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — it plugs into PuMuKIT (itself a Symfony app), so treat it as a reference implementation rather than a drop-in dependency. Expect Symfony 3.x/4.x-era conventions (AppKernel registration, YAML service definitions).

Minimal path:

1. composer require teltek/pumukit-opencast-bundle inside an existing PuMuKIT 2.x/3.x install. Do not try this on a fresh Laravel or bare Symfony 5+ app — the constraint set will not resolve.
2. Register the bundle in app/AppKernel.php (new Pumukit\OpencastBundle\PumukitOpencastBundle()).
3. Copy the bundle's configuration block into app/config/parameters.yml / config.yml: Opencast host, admin credentials, and default workflow/flavor values. Check DependencyInjection/Configuration.php first — that file is the authoritative list of every knob.
4. Look next at Services/ (the REST client and import service) and Command/ (the CLI entry points). PuMuKIT's own MultimediaObject/Series documents are the target of every import, so have the PuMuKIT data model open alongside.
5. First use case: run the import command against one finished Opencast event, confirm a MultimediaObject is created with its tracks attached, then publish it to the Web TV portal and verify playback.

Implementation Patterns

• CLI-first imports. Any import path downloads or copies large media tracks. Always drive it from a console command under cron, never from a web request.
• Series mapping is the backbone. Decide up front how Opencast series map to PuMuKIT series (by series_id/external_id), and make the mapping explicit in config rather than relying on title matching.
• Sync job shape: query the Opencast Admin API for events in workflow state SUCCEEDED, skip anything already imported (see gotchas), then hand each event to the import service. A nightly job plus a "recent events" job every 15 minutes covers most portals.
• Wrap the client. The bundle's HTTP client is thin and old. Put your own service in front of it (OpencastGateway) so your controllers and commands never call the bundle directly — you'll be able to swap in a maintained client later without touching call sites.
• Publish via PuMuKIT's own publishing decisions (Publication/broadcast objects) rather than calling Opencast's Engage player URLs directly. The portal's channel and playlist logic lives there.
• Player embedding: the portal renders through PuMuKIT's Paella player. If you need the Opencast player, override the track URL resolution — don't fork the bundle template.
• Customization over editing: decorate the import service in your app's services.yml and override only the mapping method. Copying bundle code into your app is the fastest way to make future Opencast upgrades miserable.
• Extend the client, not the command, when you need extra Opencast endpoints (ACL updates, workflow starts, snapshots). Commands should stay thin orchestrators.

Gotchas and Tips

• Abandoned since Feb 2020, 1 star, zero dependents. Assume no upstream fixes. Read the source before trusting it; expect to fork and vendor-patch. Budget time for a pinned composer.json (symfony/* locked to what the bundle supports).
• Opencast API drift is the big one. Endpoints moved between /api, /admin-ng, /engage and changed shapes across Opencast 4→9. Hit /api/version (or /admin-ng/info/me) first and test against your server version, not the docs.
• Auth differences: older Opencast servers accept plain Basic; newer ones often need X-Requested-Auth: Digest headers or form-login. Failures frequently show as a 200 with a login HTML page — validate the body is JSON, not just the status code.
• Idempotency is not handled for you. Importing the same event twice silently creates duplicates. Store the Opencast event ID on the MultimediaObject and check it before import; add a unique index or a pre-query.
• Workflow state filtering: events in RUNNING/FAILED produce broken or missing tracks. Only import SUCCEEDED.
• Timeouts and memory: raise max_execution_time, memory_limit, and Guzzle timeouts for download commands. A single hung Opencast track can wedge your cron silently — log start/end per event.
• Track flavors and attachments (presenter/presentation, captions) come back as separate objects; make sure your mapping preserves them or captions vanish without error.
• Debugging: run commands with -vvv, and log the raw API response body on failure. Old Symfony HTTP clients often swallow the useful part.
• Config quirks: defaults are rarely what you want — explicitly set the flavor, workflow definition ID, and whether media is downloaded locally or streamed. Half of the "it works but no video" reports trace back to these three.