Laravel Uploads Laravel Package

Getting Started

v1.2.0 is the release that makes this package properly adoptable: the headline is URL proxy uploads (the server fetches a remote file and stores it through the normal upload pipeline), and it ships alongside an interactive docs site, which is now the first place to look rather than the README.

Minimal path to a first working upload:

1. composer require the package and publish its config (php artisan vendor:publish --tag=...) — check the docs site for the exact tag, since README-only instructions were the norm before this release.
2. Configure at least one storage disk in config/filesystems.php and point the package config at it. Don't rely on the default; the proxy path writes server-side and will silently land files somewhere unexpected if the disk isn't explicit.
3. Run the migrations if the package persists upload records.

First use case to validate the integration end-to-end: take a known-good public image URL and push it through the proxy upload path, then assert the file exists on the configured disk and the returned model/record points at it.

// Illustrative — confirm the exact entry point and argument names on the v1.2.0 docs site.
$upload = Upload::fromUrl('https://example.com/photo.jpg')
    ->toDisk('s3')
    ->save();

If that round-trip works, the rest of the package is variations on it.

Implementation Patterns

Treat the URL proxy as a server-side import, not a form feature. The valuable pattern is ingesting remote assets your users reference but don't possess — pasted image links, CMS imports, webhook payloads carrying media URLs, avatar sync from an identity provider. Wire it into a queued job rather than a request cycle, because the fetch latency is now yours, not the browser's.

Two distinct upload entry points, one storage layer. Keep form/file uploads and URL proxy uploads flowing through the same validation, naming, and disk logic. The failure mode is teams bolting the proxy on as a special case and ending up with two sets of disk config, two naming schemes, and inconsistent cleanup.

Validate before you fetch, and again after. Pre-validate the URL shape (scheme, host allowlist) at the boundary; post-validate the actual response (content type, byte size) once the fetch returns, because a URL tells you nothing about what it serves. Reject on both sides.

Use it behind your own service class. Wrap the package call in something like App\Services\RemoteImageImporter so the package's API surface is one file in your codebase. This package is on 1.x with an active release cadence (three README rewrites and a docs site in a single minor), so the churn is real and the abstraction is cheap insurance.

Integration tip: pair proxy uploads with a ReplaceBroadcastFiles/temp-disk pattern for anything user-facing — store to a temp location, promote on success, so a slow or 500-ing remote host doesn't leave half-written files on your production disk.

Gotchas and Tips

SSRF is the big one. A URL proxy upload endpoint is, by definition, a server-side request forgery primitive. If users supply the URL, you must enforce a host allowlist or at minimum block private/link-local ranges (169.254.169.254, 10/8, 172.16/12, 192.168/16, ::1) and disable redirect-following, or a redirect will walk you straight past the check. This isn't a package bug — it's inherent to the feature — but v1.2.0 is where you inherit it.

Timeouts and size limits are not defaults you should trust. A remote host that trickles bytes can pin a PHP worker indefinitely. Set an explicit connect timeout, a total timeout, and a hard maximum byte count, and make sure the max is enforced during the stream, not after download completes.

Content-type sniffing, not the Content-Type header. The remote server controls that header. Verify the actual bytes and derive the extension yourself; otherwise you'll happily store an executable with a .jpg name.

Debugging failures here is opaque. When a proxy upload fails, the distinction between "fetch failed", "validation rejected", and "disk write failed" is invisible from a generic exception. Log the URL, HTTP status, resolved content type, and byte count at each stage before you need to debug it at 2am.

Config quirks: republish the config after upgrading. With this many doc changes in one minor, the published config file from an earlier checkout may be missing new keys, and a missing key usually fails silently (defaulting to a disk or size limit you didn't intend) rather than throwing.

Extension points: prefer the package's events/hooks for post-upload work (thumbnailing, virus scanning, model attachment) over subclassing. Subclassing ties you to internals that are clearly still moving.

On the release itself: the CI additions (GitHub Release automation, workflow config) are good hygiene signals but not a feature. Note that release automation now publishes tags on your behalf — pin your composer.json constraint sensibly (^1.2) and read the release notes for each minor rather than trusting semver alone, given how much of this release was documentation churn.