README

An easy solution to attach files to your Eloquent models, with image manipulation built in!

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

Images are resized on the fly by the configured driver. The default driver is imgproxy. Set IMGPROXY_URL, and a hex-encoded IMGPROXY_KEY and IMGPROXY_SALT when URL signatures are enabled. IMGPROXY_SOURCE_URL is prepended to relative disk URLs so imgproxy can fetch the original. An s3 disk is passed to imgproxy as s3://bucket/key, so imgproxy reads the object with its own S3 credentials.

Define named sizes in config/media.php:

'conversions' => [
    'thumb' => ['width' => 64, 'height' => 64, 'resizing_type' => 'fill'],
],

resizing_type is one of fit, fill, fill-down, force, or auto.

// Named conversion
$post->getFirstMediaUrl('gallery', 'thumb');

// Arbitrary size
$media->resizeUrl(300, 200, ['resizing_type' => 'fit', 'quality' => 80]);

turahe / media

Package info

Security

Statistics