Archive Process Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Corrected Scope — ZIP Tasks, Not a Storage Layer: The bundle ships ZipTask and UnzipTask for CleverAge/ProcessBundle, plus a DI extension. It is a file-packaging step library, not a Doctrine-backed archive-entity system with retention policies or pluggable S3 adapters. Assumptions about ArchiveEntry entities, storage: filesystem|doctrine config, and immutable-archive semantics remain unsupported by the data and stay out of planning.
• Where It Fits: Applications that already orchestrate multi-step Symfony workflows and need a step that bundles artifacts into a ZIP (exports, document sets, delivery packages) or extracts an inbound ZIP for downstream processing. Adoption is a task-level decision, not a platform decision.
• Where It Doesn't Fit: If the requirement is a retention/versioning engine, searchable archive metadata, or cold-storage tiering, this bundle is not that product. Those needs remain application-level work.
• New in v2.4 — UnzipTask as a Trust Boundary: archive_unzip now accepts max_files and max_size (default null = no limit) and validates entry count and total uncompressed size before extracting anything, failing with \RuntimeException on breach (#55). This promotes UnzipTask from "extract a file" to the enforcement point for untrusted inbound archives. It is still not a storage layer — it is a guard clause on an extraction step — but it materially changes where we place responsibility for input validation.
• Where It Still Doesn't Fit: The limits are per-task, per-archive, binary pass/fail. This is not a scanning pipeline, not content-type validation, not virus scanning, and not a quota system. A workflow that needs "reject, quarantine, and notify" semantics still needs application code around the step.
• Framework Coupling — Not Laravel-Native: The bundle is Symfony-specific (bundle class registration, DI extension, ProcessBundle task contracts). A Laravel codebase cannot consume it as a drop-in package; it would require a Symfony runtime or a reimplementation of the ZIP task logic inside a Laravel job. For a Laravel-first stack, this is effectively reference material, not a dependency — and the v2.4 limits are now part of the behavior worth porting.
• Runtime Prerequisites: PHP 8.1+ and, materially, the ext-zip / ZipArchive extension. The v2.2 fixes (#17, #18) were entirely about ZipArchive open/write failure paths; v2.4 adds validation before those paths are reached, but does not remove the dependency.

Integration Feasibility

• Low Coupling, Low Config Surface — Still True: Registration is standard (config/bundles.php); task wiring happens inside existing ProcessBundle process definitions. Two additive, optional options land on archive_unzip, both defaulting to null. No migration step is implied. Confirm against source before promising "zero migrations," but plan for none.
• The v2.4 Changes Are Opt-In and Backward Compatible: With defaults unset, extraction behavior is identical to v2.2. Nothing breaks on upgrade. The integration work is deciding to adopt the limits, not surviving the upgrade.
• Carry-Over Behavioral Changes from v2.2 Still Apply: If 2.2 has not yet been rolled out, the v2.4 upgrade inherits those changes and they remain the dominant integration cost:
  1. Fail-fast instead of silent success (#17) — ZipTask/UnzipTask throw \RuntimeException when an archive cannot be written or extracted. Workflows that "succeeded" while producing a broken archive will now fail.
  2. Explicit type contract (#18) — a non-array input (e.g., a raw string path) throws \UnexpectedValueException. Upstream steps passing strings break loudly.
  3. files_base_path semantics changed (#16) — only the leading occurrence is stripped (previously every occurrence), and an empty files_base_path now resolves relative paths correctly instead of from the filesystem root. Archive entry names may differ from pre-2.2 output.
• Data-Correctness Fix with Historical Blast Radius (#15, v2.2): options are resolved per execution. Previously the first input's options were reused for all subsequent inputs, so any historical workflow feeding multiple inputs with differing options produced archives with wrong per-input options. This still warrants an audit rather than a silent upgrade.
• Documentation Surface Changed (#62): the cookbook now uses task codes instead of the deprecated service: form, and bundle exceptions are documented in the reference pages. Any internal runbook or process definition copied from the old cookbook is now on a deprecated path — that is a documentation-migration item, not a code break, but it is the kind of thing that survives for years unnoticed.

Technical Risk

• Materially Reduced — Zip-Bomb / Resource-Exhaustion Risk: #55 closes a genuine availability risk. Previously an untrusted ZIP could inflate until worker disk or memory was exhausted, with the failure surfacing as an opaque worker crash. Now it is a pre-extraction, deterministic \RuntimeException. For any workflow accepting inbound archives, this is the single most valuable change in the release.
• New Risk — Protection Is Opt-In and Off by Default: Both limits default to null. Teams reading "zip-bomb protection added" may assume coverage that does not exist until someone sets the options. This is a documentation-and-defaults risk, not a code defect, and it is the likeliest source of a false sense of security.
• New Risk — Mis-Tuned Limits Cause Production Failures: Set max_size too low and legitimate large archives now fail the workflow with \RuntimeException. Without per-workflow sizing data, a first-pass limit is a guess. Tighten from observed maxima, not from intuition.
• Carry-Over — Behavior Change Inside a Minor Line: Exception-based failure plus changed path semantics can break callers on a 2.1 → 2.2 (or 2.1 → 2.4) jump. Treat as minor-version-with-behavioral-change: do not auto-merge.
• Carry-Over — Downstream Path Coupling: If consumers parse ZIP entry names (routers, importers, reconciliation jobs), the files_base_path fix can shift paths and break them with no code change on our side.
• Unchanged — Low Adoption: Still effectively no external dependents. No community backstop; documentation, tests, and source reading are the support surface. The steady issue cadence (#13, #15–#18, #55, #62) is improving the quality of that surface without changing its breadth.
• Unchanged — Environment Drift: ext-zip/libzip version differences between local, CI, and production containers remain the most likely source of divergent ZIP behavior (compression, overwrite, large-file handling). Note that uncompressed-size accounting is the basis of max_size — verify that the same archive trips (or does not trip) the limit consistently across environments.
• Version Gap — 2.3 Is Unexamined: The jump from the previously-pinned 2.2 to 2.4 implies an intervening 2.3 release whose changes are not in the supplied notes. Risk is unknown, not zero.

Key Questions

1. Limit Enforcement Point: Which workflows accept externally-originated ZIPs? Those are the mandatory candidates for max_files/max_size. Internal-only packaging flows can leave the limits unset.
2. Units and Semantics: Is max_size in bytes (and does it count uncompressed totals only, or archive size too)? What exactly does max_files count — regular files, directories too? Confirm against source/tests before setting values.
3. Sizing Baseline: What is the observed p95/p99 entry count and uncompressed size for legitimate inbound archives per workflow? Limits should be set several times above that, not at it.
4. Failure Handling Under ProcessBundle: When UnzipTask throws \RuntimeException on a limit breach, does ProcessBundle retry, dead-letter, or halt? A retry loop on a deterministic zip-bomb rejection is pure waste — confirm we are not retrying non-transient failures.
5. Error Signal Quality: Does the exception message distinguish a limit breach from an I/O failure? If both surface as bare \RuntimeException, triage and alerting cannot separate "attacker sent a bomb" from "disk full."
6. Version 2.3 Contents: What shipped between the pinned 2.2 and 2.4? Read that changelog before pinning.
7. Deprecated service: Usage: Do any of our process definitions still use the deprecated service: form flagged in #62? Migrate to task codes before it is removed.
8. Historical Integrity (carry-over): Do any existing processes pass multiple inputs with differing options? Which produced archives need re-verification or regeneration?
9. Path Consumers (carry-over): Does anything downstream depend on ZIP entry names? The files_base_path fix may change them — can we diff old vs. new output before rollout?
10. Input Contracts (carry-over): Do any upstream steps pass a string path to these tasks? That raises \UnexpectedValueException (#18).
11. Stack Reality Check: If the application is Laravel-first, is the goal to port the ZIP task behavior — including the new limits — rather than depend on the Symfony bundle? That changes the effort model entirely.
12. Versioning Posture: Pin 2.4.*? Will future releases continue to carry docs + tests per fix? Do we need a fork-on-failure plan given single-maintainer risk?

Integration Approach

Stack Fit

• Symfony + ProcessBundle: The only first-class fit. Requires ProcessBundle as a prerequisite and PHP 8.1+.
• ext-zip: Mandatory. Verify ZipArchive availability and libzip version in every environment, including CI images and production containers.
• No Doctrine Storage Layer: No entity/migration implication signalled. The "Doctrine vs. filesystem storage" configuration path from the prior assessment should be dropped.
• Laravel Stacks: Not a supported target. Options are (a) keep the workflow engine in Symfony, or (b) treat ZipTask/UnzipTask as a reference implementation and reimplement in a Laravel job — the v2.2 and v2.4 tests are the spec to port, and the v2.4 limits should be ported by default, not optionally, since a reimplementation has no legacy-compatibility excuse.

Migration Path

1. Pin explicitly: cleverage/archive-process-bundle:2.4.* — avoid floating constraints while behavior is settling.
2. Read the 2.3 changelog before pinning; the release notes supplied cover 2.4 only.
3. Verify prerequisites: ext-zip present and consistent across local/CI/prod; ProcessBundle version compatible.
4. Upgrade on a branch and run full workflow regression, capturing archive diffs (entry names, entry count, contents, sizes) versus pre-upgrade output. The files_base_path change makes byte-identical output not a safe assumption.
5. Adopt the new limits deliberately: enumerate workflows that ingest untrusted ZIPs, establish a sizing baseline per workflow, then set max_files/max_size per task. Do not ship the upgrade with limits unset and call the security item closed.
6. Migrate deprecated wiring: replace service:-based task references with task codes per the updated cookbook (#62), so internal docs stop diverging from upstream.
7. Remove compensating code: defensive logic written around the old "returned a path even on failure" behavior, or around warning/TypeError handling for string inputs, should be deleted and replaced with explicit handling of \RuntimeException / \UnexpectedValueException.
8. Document the failure contract in the process runbook: packaging failure = step failure = workflow-level error; limit breach = deterministic rejection, do not retry; ZipArchive error codes appear in extraction failure messages.

Compatibility

• Config Schema: Two new optional keys on archive_unzip (max_files, max_size), both defaulting to null. Existing process definitions remain valid. Bundle registration and task wiring unchanged.
• Behavioral Compatibility: v2.4 itself is backward compatible. The compatibility risk lives in (a) the v2.2 changes if not yet absorbed (#16, #17, #18), and (b) the limits once set — a too-low limit converts a working workflow into a failing one.
• Deprecation Surface: cookbook now documents task codes over service:; exceptions documented in reference pages. Documentation-alignment work, with a removal horizon to track.
• Dependency Updates: Pin and review changelogs manually; the fixes are worth taking, but not unattended.

Sequencing

1. Phase 1 — Non-critical workflow: Upgrade to 2.4 with limits unset, run regression, diff archive output. Confirm entry-name parity or enumerate intentional differences. This isolates v2.2→v2.4 behavioral change from limit-tuning effects.
2. Phase 2 — Historical audit: Identify processes that used multiple inputs with differing options; sample-verify prior archives. Prioritize anything customer-facing or contractually delivered.
3. Phase 3 — Untrusted-input hardening: Baseline archive sizes for every workflow that ingests external ZIPs, set max_files/max_size, and add negative tests (oversized archive, entry-count breach) alongside the happy path.
4. Phase 4 — Core workflows: Roll out with alerting that separates limit-breach rejections from I/O failures on the \RuntimeException path.
5. Phase 5 — Hardening: Standardize files_base_path conventions, migrate service: references to task codes, add a pre-flight ext-zip check, and codify an archive-diff check in CI for packaging workflows.

Operational Impact

Maintenance

• Pinning Discipline: Behavior changes have landed inside a minor line. Keep the constraint tight and require a changelog read before any bump — demonstrated again by the 2.2→2.4 gap.
• New Standing Item — Limit Review: max_files/max_size are now operational thresholds, not static config. Legitimate archive sizes grow; a limit set today becomes a false-positive generator in a year. Review on the same cadence as capacity planning.
• Bus Factor: One-maintainer risk persists despite improved responsiveness. Keep a fork-on-failure plan documented — the growing test suite makes forking and patching materially safer.
• Environment Parity: Treat ext-zip/libzip version pinning as a maintenance item alongside Composer dependencies; max_size depends on consistent uncompressed-size accounting.
• Documentation Drift: Internal runbooks derived from the pre-#62 cookbook now reference a deprecated wiring form. Schedule a one-pass reconciliation.
• Upstream Monitoring: Watch the issue tracker; the maintainer is demonstrably responsive, making upstream fixes a viable path rather than immediate forking.

Support

• Improved Debuggability: Exceptions carry ZipArchive error codes; v2.4 adds a deterministic, pre-extraction rejection for limit breaches — a class of failure that previously appeared as a worker crash or a full disk. Confirm the limit-breach message is self-identifying.
• Documentation Currency: Docs and tests were updated alongside #55, and #62 explicitly fixes a broken link, removes deprecated service: guidance, and documents bundle exceptions. Docs are now a reliable reference for 2.4+ specifically; pre-2.2 and pre-#62 internal notes are stale.
• Tests as Support Surface: The v2.2 tests (options precedence, missing files, overwrite, open failures, DI extension) plus the new limit-enforcement tests are the best answer to "how is this supposed to behave?" Recommend reading them during onboarding rather than reverse-engineering.
• Security Posture Support: UnzipTask limits give the team a named control to point at during security review — but only for workflows where they are configured. Keep an explicit inventory of which extraction steps are guarded and which are not.

Scaling

• Resource Profile: ZIP create/extract is CPU- and disk-I/O-bound, with memory proportional to archive size. Run these tasks in Messenger workers, never inline in web requests.
• Zip-Bomb Ceiling Now Bounded: With limits configured, worst-case extraction is bounded by max_size and max_files — this converts an unbounded capacity risk into a plannable per-worker disk budget. Without limits configured, the prior unbounded risk stands unchanged.
• Temp Disk: Packaging doubles working set (source + archive); extraction adds the inverse. Capacity planning must cover worker-local temp storage, and max_size should be sized against it.
• Concurrency: Overwrite behavior is covered by tests — verify that concurrent workers targeting the same output path are prevented at the workflow level, since the bundle addresses correctness, not coordination.
• Large Archives: If archives legitimately exceed configured limits, the step now correctly fails — capacity or limit misconfiguration surfaces as workflow failure rather than corrupt artifacts. Better, but needs alerting that distinguishes "limit too tight" from "malicious input."

Failure Modes

Ramp-Up

• Low for ProcessBundle Teams: Registration and task wiring are conventional; the work is in options semantics, not framework learning.
• The Learning Curve Is files_base_path, Options Precedence, and Now Limit Tuning: Three areas with active churn. Budget a focused review of the new tests plus the updated docs before letting the team configure limits independently — a poorly chosen max_size is a self-inflicted outage.
• Recommended Onboarding Order: (1) read the v2.2 and v2.4 tests for ZipTask/UnzipTask — especially the limit-enforcement cases, (2) diff a real archive pre/post upgrade, (3) establish an archive-size baseline for one untrusted-input workflow and set limits on it, (4) write one integration test per workflow that uses packaging, including a rejection case, (5) only then expand to core workflows.
• Security Teams Need a Different Orientation: Frame max_files/max_size for them as a per-task guard with off-by-default semantics — not a platform-wide control — so it is not credited with coverage it does not have.
• For Laravel Teams: Ramp-up is effectively porting effort, not adoption — scope it as a small build, not an integration, and port the limit checks unconditionally.