Upload Laravel Package

Getting Started

1. Install: composer require yangyifan/upload. Laravel's auto-discovery should register the service provider; on older Laravel versions add Yangyifan\Upload\UploadServiceProvider to config/app.php manually.

2. Publish the config (first place to look after install):

   php artisan vendor:publish --provider="Yangyifan\Upload\UploadServiceProvider"
   

   This drops config/upload.php — read it before writing any code. It contains the driver (local, qiniu, oss, cos), upload path, allowed extensions, max size, and route settings.

3. If the config registers a route, the package exposes an upload endpoint (default POST /upload, prefix configurable in config/upload.php). Your frontend posts a multipart/form-data file and receives JSON back with the stored path/URL.

4. For local storage, run php artisan storage:link so the returned URLs actually resolve.

5. First use case: upload a user avatar from a form, persist the returned path in users.avatar, and render it with Storage::disk(...)->url($path).

Smoke-test with curl against the route before wiring the frontend — it confirms routing, CSRF middleware, and disk credentials in one shot.

Implementation Patterns

Route-based (fastest path). Let the package own the endpoint. Your frontend POSTs to /upload, receives JSON, and your controller stores the returned path. Minimal code, but you inherit the package's validation and response shape.

Trait-based (recommended for anything real). The package ships an upload trait intended to be used inside your own controller. use it, then override the disk/path/validation hooks so uploads land in a tenant- or user-scoped folder:

use Yangyifan\Upload\Traits\UploadTrait;

class AvatarController extends Controller
{
    use UploadTrait;

    protected $disk = 'public';
    protected $path = 'avatars';
}

This keeps your auth middleware, policies, and DB writes in your own code while still reusing the SDK's file handling.

Driver swap per environment. Keep local in development and switch config/upload.php to qiniu/oss/cos in production. Application code should never reference the driver — store {disk, path} in the DB and resolve URLs later, so a CDN migration doesn't require a data backfill.

Wrap it behind your own service. Create App\Services\UploadService with an upload(UploadedFile $file): string method that delegates to the package. When the package goes unmaintained (see gotchas), you replace one class instead of hunting call sites.

Validation before upload. Add a FormRequest with mimes: and max: rules in front of your own endpoint. Treat the package's built-in checks as a second line of defense, not the only one.

Response contract. Cloud drivers commonly return the full URL while local returns a relative path. Normalize in your controller before returning to the client, and never persist the URL — persist the path.

Post-upload lifecycle. Store the disk and path, generate signed/temporary URLs at render time, and delete via Storage::disk($disk)->delete($path) when the record is removed. Run a scheduled command to sweep orphans.

Gotchas and Tips

• Public route by default. The package registers an upload endpoint for you. If you don't add auth middleware in config/upload.php (or disable the auto route and mount your own), anyone can push files to your disk. Check php artisan route:list | grep upload first.
• Docs are Chinese and sparse. The package name (yangyifan/upload) and repo (tyua07/laravel-upload) differ, which makes searching confusing. The config file and the package's controller/trait source are the real documentation.
• Low adoption, thin maintenance. 121 stars and 0 dependents means no ecosystem pressure to keep it current with new Laravel releases. Pin an exact version in composer.json and test on the Laravel version you'll actually deploy. Budget for a fork.
• Size units. Check whether max_size in the config is bytes or kilobytes. A wrong assumption shows up as "uploads silently rejected" rather than an error you can trace.
• Client filenames are untrusted. Even if the package sanitizes names, add a date- or UUID-based prefix. Cloud disks will happily overwrite on collision, and the local disk will happily accept ../.
• storage:link on every deploy. Local-disk URLs 404 after a fresh deploy until the symlink is recreated. Put it in your deploy script.
• PHP limits, not package limits. Large-file failures usually come from upload_max_filesize / post_max_size in php.ini or client_max_body_size in nginx, not from the SDK. Check $_FILES['file']['error'] and storage/logs/laravel.log.
• Cloud credentials fail late. A misconfigured qiniu/oss/cos disk loads fine at boot and only fails at upload time. Test the production driver in staging, not just the local one.
• Overriding behavior. Prefer extending the package's controller or overriding trait methods over editing vendor files. If you find yourself patching the response format, write your own controller that calls the trait — the response shape is the most opinionated part of the package.
• Deletes are not cascading. Removing the DB row does nothing to the stored file. Own that cleanup explicitly.
• Extension points worth knowing: the config file (driver, path, route prefix, middleware), the upload trait (disk/path/validation), and the service container binding for the upload implementation. Everything else is small enough to read in one sitting.