H5P Extractor Laravel Package

Technical Evaluation

What the package is. snordian/h5p-extractor is a thin PHP orchestration layer over the H5P core libraries that produces server-side artifacts from H5P content instead of relying on the browser-side H5P Player: rendered HTML via a headless browser, and — as of 0.4.1 — plain-text extractions for supported content types. The value it adds is process orchestration, content-type dispatch, and output serialization, not the rendering engine itself.

What 0.4.1 changes. The release adds plain-text generators across all supported content types. This is additive and non-breaking, but it materially widens the package's addressable use cases. Static HTML was an export concern (snapshots, offline bundles, PDF/certificates). Text extraction is an indexing and retrieval concern: search over course content, accessibility and screen-reader fallbacks, moderation/QA sweeps, translation pipelines, analytics on content coverage, and RAG/LLM ingestion of an existing content corpus. It also, in principle, gives us a much cheaper artifact than a Chromium render — provided the text generators execute in pure PHP rather than inside the headless browser. That single question determines whether 0.4.1 is a nice-to-have or a meaningful cost/architecture lever.

Architecture fit. Unchanged in shape and now broader. Good fit for a Laravel app that stores .h5p packages or H5P content rows and needs derived artifacts behind an application-owned interface. Still a poor fit as a replacement for the interactive runtime: text extraction and static HTML both flatten stateful interaction (branching scenarios, adaptive paths, drag-and-drop scoring) into a snapshot. The new text output introduces a second, distinct fidelity axis — semantic/text fidelity, separate from visual fidelity — and the two must be evaluated and gated independently. A content type can be visually acceptable and textually lossy (e.g., text dumps that drop answer keys, ordering, or scoring semantics), or vice versa. Treat the package as an artifact generation adapter (HTML + text) behind an internal interface, never as the primary playback path.

Integration feasibility. Mechanically still low-friction: Composer-installable, PHP-native, no Laravel coupling. The environmental constraint that dominates HTML rendering — a Chromium binary, shared libraries, fonts, memory, sandbox strategy, a container worker pool — may not apply to the text path at all, which would make bulk backfill of an existing corpus feasible on ordinary app workers. Confirm before planning; do not assume.

Technical risk. Remains high overall, with 0.4.1 shifting the profile slightly rather than reducing it:

• Adoption signal. Still minimal stars, near-zero dependents, single maintainer. No ecosystem validation, no bus factor. Plan for an internal fork from day one.
• Pre-1.0 API churn. 0.4.1 is a 0.x minor. This release is additive, but 0.x semver gives no compatibility guarantee across minors. Pin exact versions and vendor/fork; never float the constraint.
• Coverage claim vs. reality. "All supported content types" is a claim about the package's supported set, not about our corpus. Coverage and quality must be measured per content type against real content, and unsupported types must fail loudly rather than emit empty or truncated text.
• Runtime fragility (HTML path only). Headless Chromium remains stateful, memory-hungry, and prone to hangs; long-lived browser processes leak and time out on heavy content.
• Version coupling. Output depends on the H5P core and content-type library versions present, plus now the generator version. Authors publishing against newer libraries than the server carries will fail or degrade silently.
• Trust boundary. Text generation may reduce exposure by avoiding browser execution, but HTML rendering of third-party packages remains untrusted-code execution and still needs isolation, egress restriction, and a render timeout ceiling.

Key questions to resolve before commitment.

1. Do the plain-text generators run in pure PHP, or do they require the headless browser/Node runtime? This decides whether text extraction is cheap enough for corpus-wide backfill.
2. What is the text output contract — flat plain text, or structured (per-interaction, heading/answer/feedback delineation)? Flat text is weak for search relevance and RAG chunking.
3. Which of our top content types are covered, and what is the text fidelity per type — specifically, are answers, feedback, ordering, and scoring semantics preserved, dropped, or leaked (answer-key exposure is a real risk if text is user-visible)?
4. Which rendering backend does the HTML path require (Chromium build/version, Node, pure PHP), and is it pinned?
5. What is the visual fidelity ceiling per content type for the top 10 types in our corpus?
6. How are relative asset URLs, fonts, and library dependencies rewritten for CDN or offline delivery?
7. Is text output deterministic and stable enough to diff and to use as a cache/index key across generator upgrades?
8. Licensing posture of bundled H5P libraries and of derived artifacts.
9. Is the maintainer responsive, and what is our fork-and-own cost if the project stalls?
10. Can we guarantee library-version parity between authoring and rendering, or do we need a per-content render manifest?

Integration Approach

Stack fit. PHP/Laravel remains native territory; the package slots into a service class plus queued jobs. 0.4.1 improves the fit for a second workload class: a text-extraction job is a natural fit for existing app workers if it is browser-free, whereas HTML rendering remains gated on containerized workers (ECS/Fargate/Kubernetes or a Forge VM). Vapor, shared hosting, and constrained PaaS remain poor targets for the HTML path and may be fine for the text path. Confirm the hosting and runtime split before scoping — it still moves the estimate more than any code concern.

Migration path. Purely additive. Stand up the extractor alongside the existing client-side player, gate each artifact type (HTML, text) independently by a per-content-type feature flag, and backfill asynchronously. Nothing in the current playback path changes. Keep the client-side player as the permanent fallback for content types that fail either extraction. Because text extraction is cheap and low-risk, it is the natural first thing to ship — it validates the package's content-type dispatch and version coupling with almost no infrastructure commitment.

Compatibility. Four axes to pin instead of three: PHP version against the supported matrix; h5p/h5p-core and content-type library versions against our actual corpus; the Chromium build against the host OS image (HTML path only); and the extractor/generator version itself. Lock all in the container image and re-validate on upgrade. Artifacts should be versioned — store extractor version, library versions, and generator version with each artifact, for both HTML and text, so a fidelity regression is traceable and a re-index can be targeted rather than global.

Sequencing.

1. Spike (1–2 weeks). Sandbox, run both HTML and text extraction over 5–10 representative content types from the real corpus. Score visual fidelity, text fidelity, coverage, latency, and — critically — determine whether text extraction needs the browser. This is a go/no-go gate.
2. Wrapper. Application-owned H5PArtifactGenerator interface exposing renderHtml() and extractText() with the package as sole implementation; no package types leak into domain code.
3. Text path first. If browser-free, ship text extraction on ordinary queue workers, backfill the corpus, and wire it into search/indexing. Cheap, reversible, and it produces the per-content-type coverage matrix the HTML decision needs.
4. HTML pipeline. Queued job → isolated worker → asset rewriting → object storage → CDN, with content hash + library versions + extractor version as cache keys.
5. Flagged rollout. Per-content-type, per-artifact-type enablement driven by spike results, with automatic fallback on failure.
6. Fork readiness. Vendor or privately fork from the first production release; do not depend on upstream for fixes.

Operational Impact

Maintenance. Single-maintainer project with negligible community; assume we own the code. 0.4.1 adds surface area to own: a second generator set per content type, and a new output contract whose changes we must track. Budget for periodic fork rebases, Chromium base-image patching (monthly, HTML path only), H5P library version audits, and text-generator regression checks per content type. Small but permanent, and now marginally larger than before this release.

Support. No vendor, no SLA, no contract. Internal on-call must distinguish four failure classes: renderer infrastructure failure, library/version mismatch, content-specific rendering defects, and text-quality defects (empty, truncated, or semantically lossy text). Text defects are the more insidious class because they surface downstream — as bad search results or wrong model output — rather than as a visible broken page, so they need detection at generation time, not consumption time.

Scaling. Two distinct profiles. HTML rendering is CPU/memory-bound at roughly seconds per artifact: scale horizontally on dedicated workers with a bounded queue, never sharing a pool with latency-sensitive jobs, sized on publish volume. Text extraction, if browser-free, is milliseconds-to-low-seconds and can run on existing workers, making whole-corpus backfill and periodic re-index economically trivial. Artifact caching by content hash plus version triple removes most repeat work and remains the largest cost lever.

Failure modes to design for.

• Chromium crash, OOM, or hang on heavy content → hard timeout, worker recycling, retry with backoff, fallback to client-side player.
• Unsupported content type silently yielding empty or stub text → explicit coverage check with a structured reason code; never emit an empty artifact as success.
• Text output leaking answer keys or scoring semantics into a user-visible or externally indexed surface → treat text artifacts as a distinct publication surface with its own visibility policy.
• Generator output drift after an upgrade → golden-file text snapshots alongside HTML snapshots in CI over a fixed content sample.
• Missing or mismatched content-type library → detect at ingest, not at render.
• Asset path breakage after HTML extraction → post-render link validation and CDN smoke check.
• Untrusted package escalation → egress-restricted, non-root, ephemeral containers with no persistent credentials.

Ramp-up. Moderate and uneven, and slightly improved by 0.4.1. The Laravel wiring is a day. Headless-browser operations remain the steepest single skill, but if the text path is browser-free, a new engineer can become productive on a real, useful artifact type without touching Chromium. The enduring learning curve is the H5P domain model (packages, libraries, dependencies, content-type semantics) and the per-content-type fidelity matrix, which now has two columns — visual and textual — and still only comes from testing the actual corpus. Expect two to three weeks before independent diagnosis of a failed extraction.

Bottom line. 0.4.1 is a genuine capability expansion, not housekeeping: it adds a cheap, low-risk, high-leverage artifact type that strengthens the case for a contained export/indexing capability even where static HTML is unattractive. It does not change the underlying risk profile — low ecosystem maturity, single maintainer, pre-1.0 API churn — so this remains a poor platform-level commitment and a defensible contained one, provided it sits behind an internal interface, is validated against the real corpus on both fidelity axes, runs HTML in an isolated container pool, and is forked rather than depended upon.