Laradrop Laravel Package

Getting Started

1. Install the package:

   composer require jasekz/laradrop
   

2. On Laravel 5.5+ the service provider is auto-discovered. On 5.3/5.4 add Jasekz\Laradrop\LaradropServiceProvider::class to config/app.php.
3. Publish config and assets:

   php artisan vendor:publish --provider="Jasekz\Laradrop\LaradropServiceProvider"
   

4. Create the public storage symlink if you want served URLs:

   php artisan storage:link
   

5. Open config/laradrop.php and set the upload path, allowed extensions, max file size, and route prefix. Confirm the registered routes with:

   php artisan route:list | grep laradrop
   

6. Browse to the package route (typically /laradrop) in a logged-in session. You should see the Dropzone-based file manager.

First use case: blog post attachments. Embed the manager inside an admin form, upload an image, copy the returned storage path, save it to your Post model, and render it with Storage::url($path) on the front end.

Implementation Patterns

• Iframe embedding for pickers. Drop the package route into an <iframe> inside your admin form and use postMessage or a small inline JS listener to push the selected file path back to the parent form. This keeps the package’s UI untouched while giving you a "browse files" button.
• Standalone admin file browser. Put the route behind your admin middleware and treat it as a global media library. Store returned paths in a simple media table so multiple models can reference the same asset.
• Programmatic uploads. Point your own Dropzone instance at the package’s upload endpoint with the exact form field name the controller expects, and include the CSRF token. This lets you keep your own UI while reusing the server-side validation and storage logic.
• Eloquent attachment pattern. After upload, persist path, original_name, mime, size, and a polymorphic attachable_id/type. Query with Storage::disk(...)->url() at render time rather than storing absolute URLs.
• Middleware scoping. Wrap the package route in a group with auth (and your role check) instead of relying on defaults:

  Route::middleware(['auth', 'can:manage-media'])->group(function () {
      // laradrop routes or your wrapper view
  });
  

• WYSIWYG integration. Configure CKEditor/TinyMCE’s file browser URL to the package route and map the returned path into the editor’s image dialog. This is the most common day-to-day use and the reason the package exists.
• Multiple upload trees. The package is effectively single-namespace. If you need separate directories (e.g. avatars/ vs documents/), either add a query parameter your wrapper controller interprets, or register a second controller with a distinct config array passed at runtime.

Gotchas and Tips

• Unmaintained since 2021. The package tops out at Laravel 8.x. Before upgrading Laravel, verify Composer constraints resolve; otherwise fork it or budget for a replacement (Spatie Media Library, Laravel File Manager, or a small custom Dropzone controller).
• CSRF on custom Dropzones. If you build your own uploader, send X-CSRF-TOKEN from a <meta> tag. A 419 in the network tab almost always means a missing token, not an auth bug.
• Storage permissions. The web user needs write access to storage/app (or whatever path is configured). A 500 on upload with no Laravel exception is usually a permission or missing directory issue.
• Asset caching. Published CSS/JS can go stale after composer update. Re-publish with --force and clear your browser cache; the bundled Dropzone version is old and will conflict if your app already loads Dropzone globally.
• storage:link for URLs. Files stored under storage/app/public are not web-accessible until the symlink exists. Persist relative paths, not absolute URLs, so you can move disks later.
• Config caching. After editing config/laradrop.php run php artisan config:clear. A surprising number of "my config change did nothing" reports trace back to a cached config.
• Route collisions. The package registers routes globally. Check php artisan route:list after install and confirm no prefix clash with your own /laradrop or /files endpoints.
• Filename handling. Verify collision behavior on duplicate names — the package may overwrite or auto-suffix depending on version. If uniqueness matters, hash filenames in a wrapper controller before delegating.
• Validation is config-driven, not model-driven. Server-side MIME/extension checks come from config, so if you need per-user quotas or virus scanning, wrap the endpoint rather than editing the vendor controller directly.
• Extension points. Publish and override the Blade views to restyle, override the controller via your own route to add logic, and use the config file for path/size/extension rules. Avoid editing files under vendor/ — changes vanish on composer update.
• Debugging checklist for failed uploads: network tab for 413 (PHP upload_max_filesize/post_max_size), 419 (CSRF), 422 (validation config), or 500 (permissions/logs). Check storage/logs/laravel.log for the exception trace before assuming the package is broken.