Opentbs Bundle Laravel Package

Technical Evaluation

Architecture fit. wakeasp-inc/opentbs-bundle is a Symfony bundle, not a Laravel package. Its value-add is thin: it registers OpenTBS/TinyButStrong as container services and exposes Symfony bundle configuration. Laravel does not consume Symfony bundles (Bundle classes, DependencyInjection/Configuration, service XML/YAML), so this package provides no framework fit for a Laravel application. The actual document-merging capability lives in the upstream tinybutstrong/opentbs + tinybutstrong/tinybutstrong libraries, which are framework-agnostic and can be adopted directly.

Integration feasibility. Low effort to replicate what the bundle does, high effort to adopt the bundle itself. In Laravel you would: composer require tinybutstrong/opentbs, build a small service class wrapping \clsOpenTBS ($TBS = new \clsOpenTBS; $TBS->LoadTemplate(...); $TBS->MergeBlock(...); $TBS->Show(OPENTBS_DOWNLOAD, ...)), bind it in a service provider, and optionally add a facade. That is roughly the entire surface the Symfony bundle offers, so the bundle adds a dependency without adding capability.

Technical risk.

• Maintenance signal is effectively zero: 0 stars, 0 dependents, last release 2022-06-16, single-maintainer org. Treat as unmaintained.
• Version-constraint collision: a 2022-era Symfony bundle will constrain symfony/* ranges. Laravel already pulls Symfony components (HttpFoundation, Console, Process, Finder, etc.); an incompatible constraint can cause Composer solver conflicts or force downgrades in the Laravel skeleton. This is the most likely blocker.
• PHP compatibility: may not declare support for PHP 8.2/8.3; needs verification before any commitment.
• Abstraction leak: TBS is a procedural, stateful library (static config, plugin autoload, temp-file handling). Wrapping it in DI does not make it testable or stateless; concurrency and global state remain concerns regardless of the bundle.

Key questions.

1. Is the upstream tinybutstrong/opentbs still maintained and PHP 8.3-compatible, independent of this bundle?
2. What symfony/* and php constraints does composer.json declare, and do they conflict with our Laravel version?
3. Does the bundle expose behaviour we cannot trivially replicate (custom plugins, config, caching)?
4. Are our templates .docx/.xlsx with TBS tags, or do we actually need PhpWord/PhpSpreadsheet/dompdf (different trade-offs: programmatic vs template-driven output)?
5. Who owns template authoring, and can they maintain TBS tag syntax?

Integration Approach

Stack fit. The library fits PHP/Laravel fine; the bundle does not fit at all. Recommendation: do not install the Symfony bundle. Adopt tinybutstrong/opentbs directly and implement the small Laravel adapter ourselves.

Migration path.

1. composer require tinybutstrong/opentbs tinybutstrong/tinybutstrong (verify PHP constraint).
2. Create app/Services/Documents/OpenTbsRenderer.php encapsulating clsOpenTBS lifecycle (load, merge, save/output) so controllers never touch the global TBS API.
3. Bind it in AppServiceProvider (singleton is acceptable only if we reset state per render; otherwise bind as a fresh instance per job).
4. Optional OpenTbs facade for ergonomics — but prefer constructor injection for testability.
5. Move template files to resources/templates/ (or object storage) with a versioned naming convention; validate template existence and tag integrity before merge.
6. Add a config file (config/documents.php) for temp path, output path, and plugin allow-list.

If a team member insists on reusing the bundle's logic, treat its source as a reference implementation to copy the ~50 lines of service wiring — not as a runtime dependency.

Compatibility. Validate: PHP version, ext-zip, ext-mbstring, and open_basedir/temp-dir permissions. Confirm the Symfony constraint conflict before spending time; if it conflicts, the decision is made for you. Pin the upstream library version and lock it.

Sequencing.

1. PoC (1–2 days): render a sample .docx and .xlsx with a real dataset using raw OpenTBS in Laravel; measure memory and time.
2. Adapter (2–3 days): service + provider + tests against fixture templates.
3. Template pipeline: authoring conventions, tag validation, fixtures in CI.
4. Async path: job-based rendering for anything large or user-triggered in bulk.
5. Re-evaluate alternatives (PhpWord/PhpSpreadsheet) against real templates before committing.

Operational Impact

Maintenance. Low code surface (our adapter is tiny), but the dependency is unmaintained. Any upstream bug, security advisory, or PHP-version break becomes ours to fix or fork. Budget for the possibility of vendoring/forking tinybutstrong/opentbs. Add a scheduled check on upstream commit activity.

Support. No meaningful community around this bundle (0 dependents). Support falls back to OpenTBS documentation/forums and our own expertise. Document the TBS tag syntax and quirks internally — the bus-factor risk is real, so keep at least two engineers familiar with it.

Scaling. OpenTBS is memory- and I/O-bound: it unzips Office XML, string-manipulates, and re-zips. Large .xlsx files and long merge blocks can exhaust memory and hit max_execution_time. Scale by moving generation to queued jobs with dedicated workers, bounded concurrency, memory limits, and a timeout; store output in object storage rather than streaming large files synchronously. Set explicit memory_limit per worker and monitor.

Failure modes.

• Silent template drift: renamed/missing TBS tags don't always error — output can be wrong-but-valid. Mitigate with fixture-based tests asserting cell/paragraph contents, and a CI step that renders every template.
• Temp-file leaks: failed renders can leave files in the temp dir; ensure finally-block cleanup.
• Corrupt/unsupported Office XML: password-protected or newer-format files fail opaquely; validate uploads.
• Encoding issues with non-UTF-8 data; enforce UTF-8 at the boundary.
• Concurrency/global state: TBS static config can bleed across requests if the instance is reused; instantiate per render.
• Composer conflict at install/upgrade time if the bundle is ever added — a deployment-time failure mode, not runtime, but equally disruptive.

Ramp-up. Low for the Laravel adapter (half a day for a mid-level engineer); moderate for template authoring — TBS tag syntax, block merges, and Office template quirks are a genuine skill. Plan a short internal workshop and a template style guide. Overall: adopt the library, skip the bundle, and treat maintenance as an in-house responsibility rather than a vendor one.