D Media Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require djvue/d-media-bundle
   

   Add to config/app.php under providers:

   Djvue\DMediaBundle\DMediaBundle::class,
   

   Publish config (if needed):

   php artisan vendor:publish --provider="Djvue\DMediaBundle\DMediaBundle" --tag=config
   

2. First Use Case: Uploading Media

   • Define a model trait (e.g., HasMedia.php):

     use Djvue\DMediaBundle\Traits\HasMedia;
     
     class Post extends Model
     {
         use HasMedia;
     }
     

   • Upload logic in a controller:

     use Djvue\DMediaBundle\Services\MediaService;
     
     public function uploadMedia(Request $request)
     {
         $media = MediaService::upload($request->file('media'), 'posts');
         return response()->json($media);
     }
     

3. Key Config Check config/d-media.php for:

   • Storage paths (disks, folders).
   • Allowed MIME types (allowed_mimes).
   • Default drivers (e.g., local, s3).

Implementation Patterns

Core Workflows

1. Model Integration

   • Use HasMedia trait to attach media to models:

     class Post extends Model
     {
         use HasMedia;
     
         protected $mediaableType = 'App\Models\Post';
     }
     

   • Access media via relationships:

     $post->media()->first(); // Returns a Media model
     

2. Service Layer

   • Uploading:

     $media = MediaService::upload($file, 'posts', ['tags' => ['cover']]);
     

   • Deleting:

     MediaService::delete($media->id);
     

   • Generating URLs:

     $media->url(); // Returns full URL (configurable)
     

3. Validation

   • Extend Djvue\DMediaBundle\Rules\Media for custom validation:

     $request->validate([
         'media' => ['required', new Media(['max_size' => 5120])],
     ]);
     

4. Events

   • Listen for media.uploaded or media.deleted:

     event(new MediaUploaded($media));
     

Integration Tips

• Laravel Filesystem: Use config('d-media.disks') to map to Laravel’s filesystem.
• API Responses: Serialize media with toArray() or toJson():

  return $media->toArray(); // Includes 'url', 'path', 'mime', etc.
  

• Frontend: Use the url() method directly in Blade:

  <img src="{{ $post->media->first()->url }}" />
  

Gotchas and Tips

Pitfalls

1. Missing Config

   • If uploads fail silently, check config/d-media.php for misconfigured disks or folders.
   • Default local disk assumes storage/app/media exists. Create it if missing:

     mkdir -p storage/app/media
     

2. Permission Issues

   • Ensure the storage directory is writable:

     chmod -R 775 storage/app/media
     

   • For S3, verify AWS credentials in .env and config/filesystems.php.

3. Trait Conflicts

   • Avoid naming collisions with media() method if your model already has one. Rename the trait method or override:

     public function getMediaAttribute() { ... }
     

4. MIME Type Restrictions

   • Custom MIME types? Extend the allowed_mimes config array or override the validateMimeType method in MediaService.

Debugging

• Log Uploads: Enable debug mode in config/d-media.php:

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

• Check Events: Use php artisan event:listen to debug media.* events.
• Storage Paths: Verify paths with:

  Storage::disk('media')->path('');
  

Extension Points

1. Custom Storage Override the getDisk() method in MediaService:

   protected function getDisk($folder = null)
   {
       return Storage::disk('custom-disk-name');
   }
   

2. Post-Processing Hook into media.uploaded to process files (e.g., generate thumbnails):

   MediaUploaded::subscribe(function ($media) {
       // Run FFmpeg, ImageMagick, etc.
   });
   

3. Model Policies Restrict media access with Laravel’s Policies:

   class MediaPolicy
   {
       public function delete(User $user, Media $media)
       {
           return $user->id === $media->user_id;
       }
   }
   

4. Testing Mock MediaService in tests:

   $this->partialMock(MediaService::class, ['upload']);