Presigned Uploader Bundle Laravel Package

Technical Evaluation

Baseline note: no prior assessment exists, so this is an initial evaluation rather than a delta review. v0.2.1 is a patch release with no API or breaking changes, but it is the first version that can actually be consumed through its documented loader path — treat >=0.2.1 as the minimum viable floor and block anything below it.

Architecture fit — primary finding: the release notes describe @vadage/presigned-uploader-bundle as a Symfony package, not Laravel. The evidence is unambiguous: an ...Bundle suffix, assets/controllers.json (Symfony UX / Stimulus controller registration), Webpack Encore, and vite-plugin-symfony. There is no Laravel service provider, no config/*.php publishable config, no Storage/Filesystem integration, and no Laravel package discovery metadata implied anywhere. The premise of a "Laravel/PHP package" should be corrected before any planning proceeds: this is a Symfony bundle whose only Laravel-reusable artifact is the framework-agnostic Stimulus controller.

• Direct in-app fit: poor. Laravel's asset pipeline is laravel-vite-plugin + resources/js/app.js, with Alpine/Livewire as the interaction layer. Symfony UX controller conventions do not map onto it without adapter work.
• Realistic reuse surface: two separable pieces. (1) dist/upload_controller.js — a Stimulus controller that may be usable under Laravel if Stimulus is already in the stack; (2) the PHP-side presigned-URL generation, which is Symfony-DI-configured and would have to be re-implemented, not installed.
• Integration feasibility: medium-to-low for full-stack adoption, medium for JS-only reuse. The v0.2.1 fix removes a hard build blocker (Webpack Encore failed the build whenever the package was listed; vite-plugin-symfony failed once the upload controller was enabled), so a spike is now possible where it previously was not.
• Technical risk: elevated. This defect class — shipping a package that omits its own package.json and entry file — means the package had effectively zero working installs through its documented path prior to this patch. That points to thin packaging/CI validation (no post-build consumer smoke test). Combined with a 0.x version line, assume the API and asset layout can shift in any minor release.
• Key questions for the maintainer:
  1. Will a Laravel adapter or service provider be supported, or is the PHP side permanently Symfony-coupled?
  2. Is upload_controller.js free of Symfony UX runtime assumptions (controller registry, data-controller bootstrapping, symfony/ux-* helpers)?
  3. What is the presigned-URL flow — direct-to-S3/Spaces, or a proxy endpoint? Which signature algorithm and default TTL?
  4. Where is server-side validation enforced (content-type allowlist, max size, key scoping)? Client-side-only limits are not a control.
  5. Is the exports map in package.json stable, and will subpath exports be considered a compatibility surface?
  6. Is there a CI job that installs the published tarball in a clean fixture project? This bug class recurs without one.

Integration Approach

Stack fit: Laravel (Vite, laravel-vite-plugin, Alpine/Livewire) against a Symfony UX Stimulus package. Nothing composes out of the box. The viable shape is a thin internal adapter, not an installation.

Recommended target architecture:

• Consume only the JS controller, vendored or pinned via npm, imported explicitly in resources/js/app.js.
• Re-implement the presigning endpoint as a Laravel controller (e.g. POST /uploads/presign) using Storage::disk('s3')->temporaryUploadUrl() or the AWS SDK directly. This is the piece you own; do not attempt to port the Symfony DI configuration.
• Enforce authorization, key namespacing, content-type and size limits server-side in that controller. Assume the client controller provides UX, not security.

Migration path from the previous state: there is nothing to migrate — no prior adoption. The de-risking sequence is:

1. Inspect the published artifact first. Confirm package.json, dist/upload_controller.js, and a valid exports map are present in the 0.2.1 tarball (npm pack --dry-run or unpack the tarball). Do not trust the changelog alone; the changelog is a claim that the artifact changed.
2. Vite resolution spike (1–2 days). Import the controller in a throwaway Laravel app, run npm run build and npm run dev. The v0.2.1 fix targets Encore and vite-plugin-symfony; plain Vite + laravel-vite-plugin is a different resolver path and is not what was fixed. Verify it independently.
3. Confirm the controller boots without Symfony UX registration — instantiate Stimulus yourself and register it.
4. Build the Laravel signing endpoint in parallel, with tests for expiry, MIME allowlist, size cap, and unauthorized key access.
5. Decide build-vs-adopt based on steps 1–3. If the controller is tightly coupled to Symfony UX, stop and write ~100 lines of Alpine/dropzone code instead; the buy-vs-build math does not favor an adapter here.

Compatibility: verify PHP constraint (assume 8.1+; unconfirmed), Stimulus 3.x against whatever the rest of the front end uses, and Node/Vite resolver behavior around exports. Note that adding an exports map is itself a resolution change — it can restrict previously-deep-importable subpaths, so pin the version rather than floating ^0.2.

Sequencing: artifact verification → Vite resolution spike → go/no-go on controller reuse → Laravel signing endpoint → integration test → pin. Do not start with the endpoint before the resolution spike; if step 2 fails, the endpoint is wasted work.

Operational Impact

Maintenance: the dominant cost is the adapter, not the dependency. Every upstream 0.x minor can break the controller's expected events, attributes, or asset paths, and you own the reconciliation because the PHP half is not portable. Budget a standing per-release review; a patch that touches packaging (as 0.2.1 does) still requires re-running the resolution spike, since the failure mode is a build-time resolve error, not a runtime exception.

Support: community/maintainer-led, pre-1.0, single-vendor (@vadage). No commercial backing implied, no LTS, no documented Laravel support channel. Escalation for a Symfony-specific regression that blocks a Laravel use case is unlikely to be prioritized. Mitigation: fork dist/upload_controller.js into resources/js/vendor/ and treat upstream as a reference implementation rather than a dependency. This converts an availability risk into a known, small, owned surface.

Scaling: the presigning model scales well if the flow is direct-to-object-storage — the app server only signs, so bandwidth and memory stay flat as file volume grows. Watch three things: signing endpoint rate limits (one call per file, so it inherits upload concurrency), presigned URL TTL versus large-file upload duration (short TTLs fail mid-upload on slow links), and storage-side CORS plus multipart cleanup for abandoned uploads. If the bundle instead proxies bytes through PHP, that is a hard scaling constraint and a reason to reject full-stack adoption outright — confirm this in question 3 above.

Failure modes:

• Build-time resolve failure — the exact regression fixed in 0.2.1, and the most likely recurrence. Symptom: Could not find module during npm run build/dev. Blast radius is total: a broken asset build blocks all deploys, not just uploads.
• Exports-map regression — deep imports or asset copies breaking on an upgrade.
• Controller bootstrapping failure — controller silently never registers, uploads fail at runtime with no build error; needs an integration test, not just a green build.
• Expired presigned URL — user-visible failure on slow networks or large files.
• Orphaned multipart uploads — silent storage cost growth; needs a lifecycle rule.
• Validation bypass — if limits live only in the client controller, an attacker with the presigned URL can exceed them; the server-side controls in the Laravel endpoint are load-bearing.

Ramp-up: low for the JS controller if the team already knows Stimulus; effectively a from-scratch implementation for anyone on Alpine/Livewire. Realistic estimate: 1–2 days to evaluate and spike, 2–4 days to build and test the Laravel signing endpoint plus validation, and a recurring half-day per upstream release to re-verify packaging and resolution.

Recommendation: do not adopt this as a Laravel dependency. Run the resolution spike to confirm whether dist/upload_controller.js is framework-agnostic; if it is, vendor it and pair it with a Laravel-owned presigning endpoint. If it is not, build the upload flow directly. Either way, pin 0.2.1 exactly and require a clean-install smoke test in CI for anything pulled from this package.