turahe / media
Associate files with Eloquent models
Requires
- php: ^8.2
- guzzlehttp/guzzle: ^7.9
- kalnoy/nestedset: ^6.0
- spatie/eloquent-sortable: ^4.4
Requires (Dev)
- ext-imagick: *
- laravel/pint: ^1.17
- league/flysystem-aws-s3-v3: ^3.0
- mockery/mockery: ^1.6
- orchestra/testbench: ^8.0|^9.0||^10.0
- phpstan/phpstan: ^2.0
Suggests
- league/flysystem-aws-s3-v3: Required to use AWS S3 file storage
- php-ffmpeg/php-ffmpeg: Required for generating video thumbnails
Conflicts
- php-ffmpeg/php-ffmpeg: <0.6.1
README
An easy solution to attach files to your Eloquent models, with image manipulation built in!
Table of Contents
- Installation
- Key Concepts
- Uploading Media
- Associating Media with Models
- Disassociating & Deleting Media
- Retrieving Media
- Image Manipulation & Conversions
Installation
Install the package via Composer:
composer require turahe/media
Publish the assets to create the necessary migration and config files:
php artisan vendor:publish --provider="Turahe\Media\MediaServiceProvider"
Key Concepts
- Media can be any file type (image, document, etc). Restrict file types in your own validation logic.
- Media is uploaded as its own entity and can be managed independently.
- Associations: Media must be attached to a model to be related.
- Groups: Media items are bound to "groups" (e.g., images, documents) for flexible associations.
- Conversions: You can define image conversions (e.g., thumbnails) to be performed when media is attached.
- Global Conversions: Conversions are registered globally and reusable across models.
Uploading Media
Use the Turahe\Media\MediaUploader
class to handle file uploads. By default, files are saved to the disk specified in your media config, with a sanitized file name, and a media record is created in the database.
From Uploaded File
$file = $request->file('file'); // Default usage $media = MediaUploader::fromFile($file)->upload();
Customizing Uploads
You can customize the file name and media name before uploading:
$media = MediaUploader::fromFile($file) ->useFileName('custom-file-name.jpeg') ->useName('Custom media name') ->upload();
From URL
Upload media directly from a remote URL:
$media = MediaUploader::fromUrl('https://example.com/image.jpg')->upload();
From Base64 String
Upload media from a base64-encoded string (with or without a data URI prefix):
$base64 = '...'; // your base64 string $media = MediaUploader::fromBase64($base64, 'image.png')->upload();
Associating Media with Models
To associate media with a model, include the Turahe\Media\HasMedia
trait:
class Post extends Model { use HasMedia; }
Attach media to a model:
$post = Post::first(); // To the default group $post->attachMedia($media); // To a custom group $post->attachMedia($media, 'custom-group');
Disassociating & Deleting Media
Detach media from a model:
// Detach all media $post->detachMedia(); // Detach specific media $post->detachMedia($media); // Detach all media in a group $post->clearMediaGroup('your-group');
Delete a media item (removes file and associations):
Media::first()->delete();
Retrieving Media
Retrieve media attached to a model:
// All media in the default group $post->getMedia(); // All media in a custom group $post->getMedia('custom-group'); // First media item in the default group $post->getFirstMedia(); // First media item in a custom group $post->getFirstMedia('custom-group');
Get URLs for media:
// URL of the first media item in the default group $post->getFirstMediaUrl(); // URL of the first media item in a custom group $post->getFirstMediaUrl('custom-group');
Image Manipulation & Conversions
You can define image conversions (e.g., thumbnails) using the familiar intervention/image
library. Register conversions in a service provider:
use Intervention\Image\Image; use Turahe\Media\Facades\Conversion; class AppServiceProvider extends ServiceProvider { public function boot() { Conversion::register('thumb', function (Image $image) { return $image->fit(64, 64); }); } }
Configure a media group to perform conversions:
class Post extends Model { use HasMedia; public function registerMediaGroups() { $this->addMediaGroup('gallery') ->performConversions('thumb'); } }
Get the URL of a converted image:
// The thumbnail of the first image in the gallery group $post->getFirstMediaUrl('gallery', 'thumb');