Common Laravel Package

Technical Evaluation

Architecture fit

phpoffice/common is not an application-layer package; it is a low-level shared utility library that sits beneath the PHPOffice document stack (phpspreadsheet, phpword, phppresentation). In a Laravel codebase it is almost always a transitive dependency, not something a team wires up directly. Its responsibilities are narrow and infrastructural: OLE compound-document container reading, XML/stream helpers, and drawing primitives. Architecturally this means it should be treated as a platform dependency governed by our document-processing surface area, not as a component we design around.

Release 1.1.0 is additive rather than structural. The one substantive change is OLEWrite (PR #65), the write-side counterpart to the long-standing OLERead. That closes a genuine capability gap — historically OLE container writing lived inside downstream packages (notably PhpSpreadsheet's Xls writer), so consolidating it here is a directionally correct layering fix. However, it introduces new public API surface and, more importantly, new binary output paths into our dependency tree.

The remaining three changes are toolchain hygiene: PHP 8.5 in the CI matrix, PHPStan 2.x allowance, and PHPStan raised to level 7. These have zero runtime footprint for consumers but are meaningful signals about maintainer discipline and forward-compatibility posture.

Integration feasibility

Very low effort. This is a 1.0.5 → 1.1.0 bump with no breaking changes, no deprecations, and no removed symbols. Integration is a composer update phpoffice/common or, more realistically, an incidental consequence of updating phpspreadsheet/phpword within their existing version constraints. No Laravel service provider, config, migration, or facade involvement. No database, queue, or HTTP surface.

The only decision point is whether we consciously adopt OLEWrite. Default integration — i.e., simply absorbing the bump — is effectively a no-op we should still validate, because binary-adjacent code paths are where silent regressions hide.

Technical risk

• New write path, unproven in the field. OLEWrite is brand-new, contributed by a first-time contributor (@businessarshgoyal), and has essentially no production mileage. Any code path that begins emitting OLE containers via this class should be considered beta until we have a golden-file corpus.
• Regressions in read paths are unlikely but non-zero. Raising PHPStan to level 7 and permitting PHPStan 2.x are static-analysis changes only; they do not alter runtime behavior. Treat as informational.
• PHP 8.5 coverage is CI-only. Adding 8.5 to the matrix asserts the package builds there; it does not guarantee the surrounding stack (PhpSpreadsheet, PHP extensions such as zip, xml, gd) is equally ready. Do not let this lull us into an early PHP 8.5 upgrade.
• Binary corruption is a high-severity, low-detectability failure class. If a downstream writer picks up OLEWrite and produces malformed .xls/.doc containers, the failure surfaces at the consumer (Excel repair prompts, truncated documents), not in our logs.
• Transitive version-drift risk. Because we likely do not pin phpoffice/common explicitly, the bump arrives silently. Our lockfile diff is the only audit trail.

Key questions

1. Does any part of our product roadmap require OLE writing (legacy .xls/.doc/.ppt export) rather than just reading? If not, OLEWrite is inert for us and risk is near zero.
2. Which downstream packages in our lockfile constrain phpoffice/common, and does their current constraint already admit 1.1.0? (Confirm before assuming the bump is deliberate.)
3. Does our export regression suite include golden-file comparison, or only "does it open without exception" checks? Binary output requires byte- or structure-level assertions.
4. Are we on a PHP version supported by both 1.0.x and 1.1.0, and do we intend to adopt PHP 8.5 within the next two quarters?
5. Do we run PHPStan ourselves? If so, does allowing PHPStan 2.x in this dependency's dev constraints create any conflict in a monorepo or shared tooling repo?

Integration Approach

Stack fit

Standard Composer dependency, PSR-4 autoloaded, no framework coupling. It fits the Laravel stack without friction precisely because it does nothing framework-specific. The relevant fit question is not Laravel-version compatibility but PHP-version and extension compatibility: this package's surface depends on ext-xml, ext-zip, and binary stream handling, which is where operational surprises actually originate.

Migration path

Effectively a no-migration change. Recommended path:

1. Land the bump as an isolated dependency-only commit (lockfile + composer.json if we pin explicitly) so it is trivially revertible and clearly attributable in history.
2. Do not bundle it with a feature branch or a PhpSpreadsheet major upgrade — keep the blast radius legible.
3. Explicitly decide and record whether we are adopting OLEWrite. If we are not, add a note to the dependency register that the symbol exists but is unused, so a future engineer does not assume it is battle-tested.
4. If we are adopting it, gate it behind a feature flag and a dedicated export test matrix from day one.

Compatibility

• Semver-minor; backward compatible per the project's convention.
• Downstream constraints: PhpSpreadsheet and PhpWord generally allow ^1.0, so 1.1.0 resolves without a coordinated multi-package upgrade. Verify against our lockfile rather than assuming.
• No config, env, or storage-format changes for existing functionality.
• PHPStan 2.x allowance is dev-only and does not affect consumers unless we share tooling config with the dependency source (rare).

Sequencing

1. Confirm current resolved version and which packages constrain it (audit).
2. Update in isolation; run full test suite plus any document-generation tests.
3. Run a targeted export smoke test — generate one .xlsx, one .docx, one .csv — and confirm files open cleanly in a real client, even though those paths should not touch OLEWrite.
4. Defer OLEWrite adoption to its own ticket, with an explicit evaluation gate: golden-file round-trip tests, a validation pass against Excel/LibreOffice, and a documented fallback (e.g., retain the PhpSpreadsheet-internal writer) if output proves unstable.
5. Revisit PHP 8.5 readiness on our own timeline, independent of this release's CI matrix.

Operational Impact

Maintenance

Near-zero steady-state burden. No runtime configuration, no scheduled tasks, no persistence layer. The maintenance consideration is entirely dependency hygiene: because it arrives transitively and silently, it should be captured in our dependency-inventory process (SBOM / lockfile review) so version changes are attributable. Maintainer signals here are positive — active CI matrix expansion, tightened static analysis, and first-time contributors being merged — which suggests a healthy project rather than an abandoned one.

Support

No vendor support; community-maintained under the PHPOffice umbrella. Escalation path is upstream issues on GitHub, which historically have variable latency. Mitigation is architectural: never let this package be the sole component responsible for a customer-visible artifact without a verified fallback.

Scaling

Not a scaling-relevant component in the horizontal sense — it is CPU- and memory-bound within a single request or job. The scaling concern is per-artifact cost: OLE container handling reads/writes whole binary structures in memory. If we adopt OLEWrite for bulk export, large documents will inflate peak memory per worker. This should be modeled against our queue worker memory limits before any volume rollout, and exports of meaningful size should run in queued jobs rather than synchronous requests.

Failure modes

Ramp-up

Minimal for absorbing the bump — a competent PHP engineer needs no ramp-up to consume a transitive minor version. Ramp-up is only material if we adopt OLEWrite, in which case budget for: understanding the compound-document container format, building a golden-file corpus, and establishing a binary-output testing convention the team does not currently need. Estimate that as a small, self-contained spike rather than a line item on this release.

Recommendation

Adopt 1.1.0 as a routine, isolated dependency bump — no breaking changes, no migration, no deprecations, and the toolchain changes are strictly beneficial to the ecosystem. Treat OLEWrite as additive capability we are not yet consuming: flag it as unproven, do not build production write paths on it without a dedicated evaluation ticket, and record the deliberate deferral so the decision is revisit-able rather than accidental.