Free Upload Laravel Package

Product Decisions This Supports

• Shipping upload UX in Filament admin panels without owning storage infrastructure. This release makes "add image/file upload to our admin panel" a one-afternoon decision instead of a two-sprint infrastructure project (bucket provisioning, IAM, signed URLs, image transforms, CDN).
• Build vs. buy calls for asset handling. The package bundles the upload widget, the client-side encoding, the upload endpoint, and the retrieval proxy into one composer dependency. The buy/borrow decision shifts from "which object store + which upload library" to "is this package's transport good enough for our next 6–12 months?"
• Deferring (not eliminating) the storage/CDN roadmap item. Because URLs stored in your database now point at your own app (proxy_base_url), an eventual migration to S3/R2 is a proxy-controller swap rather than a data migration across every model and view. That materially lowers the cost of postponing the decision — a legitimate "we'll revisit at scale" bet.
• MVP and internal-tool scoping. For prototypes, back-office tools, community sites, and low-traffic products where uploads are user-facing but not business-critical, this is a credible "don't build it" answer that keeps the team on revenue features.
• Feature-level go/no-go on sensitive content. The data path routes files through a third-party image host, so any feature involving PII, customer documents, legal evidence, health data, or regulated content should be flagged as out of scope for this component before it's designed in, not after.
• Vendor-risk and exit-cost tracking. v1.0.0 replaces the external media-server.kawnek.workers.dev worker with an in-app proxy — that's a genuine reduction in blast radius and worth reflecting as a lowered risk line in the roadmap, while the remaining dependency on FreeImage.host stays on the vendor register.

When to Consider This Package

Good fit when:

• You are already running Filament v4/v5 on Laravel 11–13 / PHP 8.2+ and the upload need is inside an admin or panel experience — the native $wire.set(...) state handling means no glue code.
• Upload volume and file sizes are modest and predictable; you can live without a CDN, signed URLs, on-the-fly transforms, or direct-to-bucket uploads for now.
• Content is non-sensitive — marketing imagery, avatars, community attachments, internal reference images — and you can accept files transiting a third-party host.
• You want short time-to-value and are willing to accept a small, single-maintainer dependency in exchange for avoiding storage plumbing.
• You value configurability over convention: upload_endpoint, proxy_base_url, image_path, files_path, proxy_timeout, and route prefix/middleware all being env- or config-driven means you can point this at your own paths without forking.

Look elsewhere when:

• Compliance, residency, or confidentiality applies: GDPR/DPA obligations, customer contracts prohibiting third-party subprocessors, or any hint of PII or regulated data. The FreeImage.host round-trip is architecturally disqualifying here regardless of the proxy.
• Scale or performance is the constraint: the proxy is a synchronous fetch-and-decode hop through your PHP workers, so bandwidth, worker concurrency, and proxy_timeout become your problem. High-traffic or large-file workloads belong on S3/R2 with direct uploads and a CDN.
• You need durable guarantees — SLAs, retention policy, lifecycle rules, virus scanning, EXIF stripping, or audit trails on stored assets.
• Long-term maintenance certainty matters more than speed: single-maintainer packages with a dependency on a free external image host carry abandonment and ToS-change risk that should be priced in.
• You require real file-type handling. Non-image files being encoded client-side into PNGs to travel as images is a workaround, not a storage strategy — treat it as unsuitable for any workflow where the file is the deliverable (contracts, exports, archives, datasets).
• Your stack is outside the pinned matrix (older Laravel/PHP, Filament v3) or you cannot guarantee ext-gd across environments.

How to Pitch It (Stakeholders)

To executives (30 seconds): This is a free, open-source building block that lets us add image and file uploads to our admin interfaces in days rather than weeks, with no cloud storage bill and no new infrastructure to operate. It just reached its first stable release and no longer depends on a third-party file server we don't control — files are now served through our own application. The trade-off is that the underlying image hosting is a free external service, so I'd position it as the right choice for internal tools, prototypes, and non-sensitive content, and budget a swap to managed storage once uploads become customer-critical or regulated.

To engineering: v1.0.0 is a legitimate adoption candidate. The FreeUploadFileController + Proxy removes the media-server.kawnek.workers.dev dependency, which was the biggest architectural wart. Endpoints are config-driven, state stays native to Filament via $wire.set, the component is publishable (freeupload:publish-component and the vendor stub with a namespace placeholder) so we can fork and own the markup if needed, and there's a real Pest suite (43 tests / 99 assertions) covering the proxy, the decoder, the controllers, and the component. Requirements are PHP ^8.2 with ext-gd, Laravel 11–13, Filament 4–5. Two things to design around up front: the proxy makes our app the file server, so plan for bandwidth and worker-time costs, and non-image files are encoded to PNG in the browser rather than stored natively — don't put it behind document workflows. The clean exit is a custom proxy controller, since stored URLs already point at us.

To security/legal: before this appears in any customer-facing or regulated surface, we need a written position on files transiting FreeImage.host, the absence of scanning and lifecycle guarantees, and what we do if that host changes its terms or disappears. The v1.0.0 proxy reduces our exposure but does not remove the dependency.