Unoconv Bundle Laravel Package

Technical Evaluation

Architecture fit — poor, and a category mismatch. jmd/unoconv-bundle is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no config/*.php publishable config, no facade, and no Laravel-version constraint in its metadata. It integrates via Symfony's Bundle registration in AppKernel/bundles.php and a DependencyInjection extension class. Adopting it in a Laravel application means either (a) pulling Symfony's DI/bundle machinery into a Laravel app, which is architecturally incoherent, or (b) reading the ~few hundred lines of source and reimplementing them. The package's actual substance is a thin exec()/process wrapper around the unoconv CLI, which in turn drives headless LibreOffice. That is perhaps a day of engineering to reproduce idiomatically.

Integration feasibility — near zero as-is. Last release 2016-05-17, archived, zero stars, zero dependents. Its composer.json will constrain PHP to the 5.x/7.0 era and Symfony to ~2.x, which will fail dependency resolution against any current Laravel (10/11/12 require PHP 8.1+). The upstream dependency is also a concern: unoconv itself has been effectively unmaintained and historically depended on Python 2, meaning even a successful install lands you on a dead toolchain. Installation is not the blocker; the blocker is that there is no supported path to running this on a modern runtime.

Technical risk — high and concentrated in security and process management. Two risks dominate:

• Command-injection and file-handling surface. Any wrapper that shells out to unoconv with user-influenced filenames or paths is an injection vector unless aggressively escaped. The package predates modern hardening norms; it should be assumed unsafe without a line-by-line audit.
• Document-conversion is an adversarial input class. Untrusted Office documents can carry macros, external references (SSRF/XXE-style fetches), malformed archives, and parser exploits. Running LibreOffice on user uploads inside your application's process boundary — with your application's filesystem and network access — is a meaningful escalation of blast radius.

Secondary risks: headless LibreOffice hangs and profile-lock contention are the single most common operational failure of this class of tool, and this wrapper offers no visible supervision, timeout, or isolation story.

Key questions for the requesting team.

1. What is the concrete business requirement — which source and target formats, and which fidelity matters (layout-exact PDF vs. lossy text extraction)?
2. What volume, and is conversion synchronous (inline in a request) or asynchronous (queue)? Synchronous LibreOffice is a latency and availability trap.
3. Are documents trusted (internal/known producers) or untrusted (public uploads)? This single answer determines whether in-process conversion is permissible at all.
4. Is the output legally or commercially sensitive enough to rule out third-party SaaS conversion?
5. Do we already run LibreOffice anywhere, and does anyone own it operationally?
6. Is a format-specific library sufficient — e.g. phpoffice/phpspreadsheet, dompdf/mpdf, phpword — avoiding LibreOffice entirely?

Integration Approach

Stack fit — reject the package; keep the concept. Laravel's idioms for this are a bound service class (app/Services/DocumentConverter.php) resolving a Converter interface, a queued job (ConvertDocumentJob) on a dedicated queue, and Storage disks for input/output. Nothing in the Symfony bundle maps to that, and the bundle's value is too thin to justify a compatibility shim.

Recommended implementation options, in order of preference:

1. Containerized conversion worker (recommended). Run LibreOffice headless in an isolated container — either directly via soffice --headless --convert-to, or via Gotenberg, which packages LibreOffice plus a clean HTTP API and removes the process-management burden. Laravel calls it over HTTP with a timeout and no shell access; workers scale horizontally and are isolated from the app.
2. Direct soffice invocation via Symfony/Process or Laravel's Process facade. One dedicated LibreOffice user-profile directory per worker, --norestore --nologo --nodefault --nolockcheck, hard timeout, temp-dir-per-job, and cleanup in a finally.
3. Managed API (CloudConvert, Adobe PDF Services, Aspose) if document contents are not restricted and volume is low-to-moderate. Fastest to ship, no ops burden, but introduces data-residency and per-page cost questions.
4. unoconv directly — only as a stepping stone, and only knowingly accepting an unmaintained Python dependency.

Migration path. There is nothing to migrate from; the bundle was never installed (0 dependents). Treat the repository as a reference implementation at most — read it for the CLI flags and the "one profile per concurrent conversion" pattern, then discard the code. If a prototype already used it, the migration is: extract the conversion call into an interface, swap the Symfony service definition for a Laravel container binding, move config into config/conversion.php, and shift execution from inline to a queued job writing to a storage disk.

Compatibility. Non-negotiable blockers: PHP 8.x, Laravel 10+, Symfony 6/7 components. The bundle's constraints will not resolve. Any ported code must also be revisited for modern LibreOffice CLI behavior — flags and default output paths have shifted since 2016 — and re-tested against the LibreOffice version actually deployed, not the one assumed in 2016.

Sequencing.

1. Requirement spike (1–2 days): enumerate formats, fidelity bar, trust level, volume. Confirm a dedicated library can't solve it.
2. Feasibility spike (2–3 days): convert a representative sample — worst-case documents, large files, missing fonts, encrypted/password-protected files, malformed inputs — through a containerized LibreOffice. Measure fidelity and runtime. This spike is the real go/no-go.
3. Build the adapter (3–5 days): interface, containerized converter, job, timeouts, retries, output storage, cleanup.
4. Harden: input validation, size/page caps, sandboxed worker with no app credentials or DB access, egress restrictions.
5. Load and failure testing: concurrency, hang injection, OOM, disk exhaustion.
6. Observability and runbook: queue depth, conversion duration, failure-rate alarm, stuck-process reaper.

Operational Impact

Maintenance — the package contributes nothing and costs something. It is archived with no maintainer, no issue triage, no CVE response path, and effectively no user base to surface bugs. Even in a hypothetical world where it installed, you would own it entirely on day one. The honest framing for stakeholders: you are not adopting a dependency, you are forking an abandoned one. The operational burden that matters is not the wrapper — it's LibreOffice, which is a large native application with its own patching cadence (security fixes ship regularly and must be tracked), font packages that affect rendering fidelity, and version-specific output differences.

Support. No vendor, no community, no documentation beyond a README. Internal expertise must be built. Escalation path is "read the LibreOffice source and the unoconv script."

Scaling. Headless LibreOffice is the awkward part of any architecture that uses it. Key constraints:

• A single soffice instance generally serializes conversions; concurrency requires one user-profile directory per worker process. This is the pattern the bundle encodes and the only thing worth borrowing.
• Memory footprint is large and spiky; conversions of complex documents can consume hundreds of MB and multiple CPU-seconds. Capacity planning must be per-concurrent-conversion, not per-request.
• Scale-out is horizontal, worker-per-container, with a dedicated queue so conversion backlog cannot starve transactional jobs.
• Warm-start matters: cold LibreOffice startup is seconds, so long-lived workers beat per-job container spawns at volume, but per-job spawns are far safer for untrusted input. That trade-off should be decided explicitly.

Failure modes to design for up front:

• Hangs on malformed or pathological documents → hard timeouts plus a reaper for orphaned soffice.bin processes; without this, workers leak and the queue silently stalls.
• Profile lock contention → cryptic "another instance is running" failures under concurrency. Mitigated only by per-worker profiles.
• OOM / worker kill mid-conversion → job must be retryable and idempotent, with a bounded retry count and a dead-letter path.
• Fidelity drift → missing fonts and version changes silently produce wrong-looking PDFs. Needs golden-file regression tests in CI.
• Security incidents → macro execution, external-reference fetches, parser exploits. Worker must run as non-root, with no app secrets, restricted egress, and a scratch filesystem that is wiped per job.
• Silent corruption → zero-byte or truncated output treated as success. Validate output size and type before marking a job complete.
• Disk exhaustion from unreaped temp files → mandatory cleanup in finally plus a periodic sweeper.

Ramp-up. Low for the wrapper (trivial), moderate-to-high for the platform. Expect a sprint before the team is confident with LibreOffice process behavior, profile isolation, font provisioning, and fidelity testing. Budget for one engineer to own document conversion as a specialty, because when it breaks — and hang-based failures are a matter of when, not if — the failure is opaque.

Bottom line. Do not add jmd/unoconv-bundle as a dependency. It is an archived, zero-adoption Symfony bundle that will not install on a current Laravel stack, and its entire value is a thin, unaudited shell wrapper you would have to rewrite anyway. Validate the underlying requirement first — a format-specific PHP library may eliminate LibreOffice entirely. If it doesn't, build a small in-house Laravel adapter around a containerized LibreOffice or Gotenberg worker, and treat this repository purely as a design reference for per-worker profile isolation.