Laravel Awesome Uploader Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hozien/laravel-awesome-uploader
   php artisan vendor:publish --provider="Hozien\AwesomeUploader\AwesomeUploaderServiceProvider"
   php artisan migrate
   

   • Publishes config (config/awesome-uploader.php) and migrations (database tables for uploads).

2. Configuration:

   • Update config/awesome-uploader.php to define:
     • Default storage disk (default_disk).
     • Allowed file types (allowed_mimes).
     • Max file size (max_size).
     • Thumbnail settings (thumbnail).
     • Database integration (database).
   • Example:

     'allowed_mimes' => ['image/jpeg', 'image/png', 'application/pdf'],
     'max_size' => 10 * 1024 * 1024, // 10MB
     'thumbnail' => [
         'enabled' => true,
         'width' => 200,
         'height' => 200,
     ],
     

3. First Upload (Blade):

   • Add the Blade component to your view:

     {!! AwesomeUploader::fileInput(['name' => 'document', 'multiple' => true]) !!}
     

   • Handle the upload in a controller:

     use Hozien\AwesomeUploader\Facades\AwesomeUploader;
     
     public function store(Request $request) {
         $upload = AwesomeUploader::upload($request->file('document'));
         return response()->json($upload);
     }
     

4. First Upload (API):

   • Use the upload endpoint (if enabled in config):

     POST /api/upload
     Form-Data: file=@/path/to/file.jpg
     

   • Response:

     {
         "path": "uploads/2023/10/file.jpg",
         "url": "https://example.com/storage/uploads/2023/10/file.jpg",
         "type": "image/jpeg",
         "name": "file.jpg",
         "size": 102400,
         "file_hash": "a1b2c3..."
     }
     

Implementation Patterns

Core Workflows

1. Blade Integration

• File Input:

  {!! AwesomeUploader::fileInput([
      'name' => 'profile_picture',
      'accept' => 'image/*',
      'max_files' => 1,
      'preview' => true,
      'delete' => true, // Enable soft delete
  ]) !!}
  

• Custom Styling: Override default styles via config:

  'blade' => [
      'styles' => [
          'container' => 'custom-upload-container',
          'preview' => 'custom-preview-class',
      ],
  ],
  

2. React/Vue Integration

• React Hook:

  import { useAwesomeUploader } from 'laravel-awesome-uploader';
  
  function MyComponent() {
      const { upload, files, isUploading } = useAwesomeUploader({
          endpoint: '/api/upload',
          maxFiles: 5,
          allowedTypes: ['image/jpeg', 'image/png'],
      });
      return <input type="file" onChange={(e) => upload(e.target.files)} />;
  }
  

• Vue Component:

  <template>
      <awesome-uploader
          endpoint="/api/upload"
          :max-files="3"
          :allowed-types="['application/pdf']"
          @uploaded="handleUploaded"
      />
  </template>
  

3. API-Driven Uploads

• Endpoint Configuration:

  // routes/api.php
  Route::post('/upload', [UploadController::class, 'store']);
  

• Controller Logic:

  public function store(Request $request) {
      $upload = AwesomeUploader::upload($request->file('file'), [
          'user_id' => auth()->id(),
          'custom_metadata' => ['source' => 'api'],
      ]);
      return response()->json($upload);
  }
  

4. Database Integration

• Querying Uploads:

  use Hozien\AwesomeUploader\Models\Upload;
  
  $uploads = Upload::where('user_id', auth()->id())
      ->where('type', 'like', 'image/%')
      ->orderBy('created_at', 'desc')
      ->paginate(10);
  

• Eager Loading:

  $user = User::with(['uploads' => function($query) {
      $query->where('is_primary', true);
  }])->find(1);
  

5. Thumbnail Generation

• Auto-Generated Thumbnails: Configure in config/awesome-uploader.php:

  'thumbnail' => [
      'enabled' => true,
      'width' => 300,
      'height' => 300,
      'format' => 'webp',
      'path' => 'thumbnails/{year}/{month}',
  ],
  

• Manual Thumbnail:

  $upload = AwesomeUploader::upload($file);
  $thumbnail = AwesomeUploader::generateThumbnail($upload->path, 150, 150);
  

6. Deduplication

• Check for Duplicates:

  $existing = AwesomeUploader::findByHash($request->file('file')->hash());
  if ($existing) {
      return response()->json(['message' => 'File already exists', 'upload' => $existing]);
  }
  

• Force Overwrite:

  $upload = AwesomeUploader::upload($file, ['overwrite' => true]);
  

7. Access Control

• Policy Integration:

  // app/Policies/UploadPolicy.php
  public function before($user) {
      if ($user->isAdmin()) return true;
  }
  
  public function delete($user, Upload $upload) {
      return $upload->user_id === $user->id;
  }
  

• Middleware:

  Route::middleware(['auth', 'can:upload'])->group(function () {
      // Upload routes
  });
  

8. Batch Processing

• Bulk Upload:

  $uploads = AwesomeUploader::uploadMultiple($request->file('files'), [
      'user_id' => auth()->id(),
      'batch_id' => 'user_avatar_update_' . time(),
  ]);
  

• Batch Query:

  $batch = Upload::where('batch_id', 'user_avatar_update_12345')->get();
  

Integration Tips

Laravel Filesystem

• Custom Disk:

  $upload = AwesomeUploader::upload($file, [
      'disk' => 's3',
      'folder' => 'custom-folder',
  ]);
  

• Symbolic Links: Ensure public_path('storage') is symlinked to your storage disk:

  php artisan storage:link
  

Queueing Uploads

• Async Processing:

  AwesomeUploader::upload($file, [
      'queue' => 'uploads',
      'dispatch' => true,
  ]);
  

• Queue Worker:

  php artisan queue:work --queue=uploads
  

Custom Validation

• Override Validation:

  AwesomeUploader::extendValidation(function ($request, $file, $rules) {
      $rules->merge(['dimensions' => 'min_width:1000,max_width:5000']);
  });
  

• Dynamic Rules:

  $rules = [
      'mimes' => ['image/jpeg', 'image/png'],
      'max_size' => auth()->user()->plan->max_upload_size,
  ];
  AwesomeUploader::upload($file, ['rules' => $rules]);
  

Frontend Events

• React/Vue Events: Listen to upload-started, upload-progress, upload-success, upload-error events. Example (Vue):

  <awesome-uploader
      @upload-progress="handleProgress"
      @upload-error="handleError"
  />
  

Webhooks

• Post-Upload Hooks:

  AwesomeUploader::afterUpload(function ($upload) {
      // Send notification, update database, etc.
      event(new Uploaded($upload));
  });
  

Gotchas and Tips

Pitfalls

1. Missing Dependencies

• Intervention/Image: If intervention/image is missing, thumbnails will fail silently. Install it explicitly:

  composer require intervention/image
  

• Database Migrations: Always run migrations after publishing:

  php artisan migrate
  

2. File Hash Collisions

• Race Conditions: Deduplication relies on