Gallery Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require comensee/gallery
   

   Publish the package config (if needed):

   php artisan vendor:publish --provider="Comensee\Gallery\GalleryServiceProvider"
   

2. Configuration Check config/gallery.php for default settings (e.g., storage paths, allowed extensions). Customize as needed:

   'storage' => [
       'disk' => 'public',
       'path' => 'uploads/gallery',
   ],
   

3. First Use Case: Uploading an Image Inject the Gallery facade or service into a controller:

   use Comensee\Gallery\Facades\Gallery;
   
   public function upload(Request $request) {
       $file = $request->file('image');
       $upload = Gallery::upload($file, [
           'resize' => [800, 600], // Optional: Resize dimensions
           'thumbnail' => true,    // Optional: Generate thumbnail
       ]);
       return response()->json($upload);
   }
   

4. Routes & Middleware Register routes in routes/web.php or routes/api.php:

   use Comensee\Gallery\Facades\Gallery;
   
   Route::post('/upload', [GalleryController::class, 'upload']);
   

Implementation Patterns

Common Workflows

1. Uploading Files

   • Use Gallery::upload() with optional parameters:

     $result = Gallery::upload($file, [
         'resize' => [1200, 800],
         'thumbnail' => true,
         'watermark' => 'path/to/watermark.png',
     ]);
     

   • Returns an array with:
     • path: Full storage path.
     • url: Publicly accessible URL.
     • thumbnail_url: If generated.

2. Generating Thumbnails

   • Automatically generated via config (thumbnail => true) or manually:

     $thumbnail = Gallery::generateThumbnail('original-path.jpg', 200, 200);
     

3. Deleting Files

   • Delete by path or ID (if using a database):

     Gallery::delete('uploads/gallery/123.jpg');
     

4. Integration with Eloquent

   • Store file paths in a model:

     class Product extends Model {
         public function uploadGallery(Request $request) {
             $this->image_path = Gallery::upload($request->file('image'))['path'];
             $this->save();
         }
     }
     

5. Batch Processing

   • Process multiple files in a loop:

     foreach ($request->file('images') as $file) {
         Gallery::upload($file, ['resize' => [500, 500]]);
     }
     

Advanced Patterns

1. Custom Storage Disks Override the default disk in config or dynamically:

   $upload = Gallery::upload($file, [], 's3');
   

2. Event Listeners Listen for upload events (if the package supports them):

   // In EventServiceProvider
   public function boot() {
       Gallery::onUpload(function ($path) {
           Log::info("Uploaded: {$path}");
       });
   }
   

3. API Responses Normalize responses for consistency:

   return response()->json([
       'success' => true,
       'data' => Gallery::upload($file),
   ]);
   

Gotchas and Tips

Pitfalls

1. File Validation

   • Ensure files are validated before upload (e.g., mimes:jpeg,png).
   • The package may not validate extensions by default; add checks:

     $validated = $request->validate([
         'image' => 'required|image|mimes:jpeg,png,jpg|max:2048',
     ]);
     

2. Storage Permissions

   • Verify the storage/app/public/uploads/gallery directory is writable:

     chmod -R 755 storage/app/public/uploads
     

3. Missing Thumbnails

   • If thumbnails aren’t generating, check:
     • GD/ImageMagick is installed (php -m | grep gd).
     • Config thumbnail is set to true.
     • Permissions on the thumbnail directory.

4. Resizing Issues

   • Large images may fail if memory limits are low. Increase memory_limit in php.ini or resize smaller dimensions first.

5. Database vs. Filesystem

   • The package may not include a database table for tracking files. If needed, create a migration manually.

Debugging Tips

1. Enable Logging Add to config/gallery.php:

   'debug' => env('GALLERY_DEBUG', false),
   

   Check storage/logs/laravel.log for errors.

2. Check Uploaded Files Verify files exist in storage/app/public/uploads/gallery after upload.

3. Test with Small Files Use small images (e.g., 100KB) to rule out size/memory issues.

4. Clear Cache If changes to config aren’t applying:

   php artisan config:clear
   php artisan cache:clear
   

Extension Points

1. Custom Processors Extend the package by adding processors (e.g., for PDFs or videos):

   // In a service provider
   Gallery::extend('pdf', function ($file) {
       // Custom logic for PDFs
   });
   

2. Override Storage Logic Bind a custom storage handler:

   Gallery::extendStorage(function ($disk) {
       return Storage::disk($disk)->putFileAs(...);
   });
   

3. Add Metadata Use Laravel’s File class to extract metadata:

   $file = $request->file('image');
   $metadata = exif_read_data($file->getPathname());
   

4. Webhook Integration Trigger external actions post-upload via events or queues:

   event(new FileUploaded($upload['path']));