Download the PHP package farhanshares/laravel-mediaman without Composer

Laravel MediaMan

MediaMan is an elegant & powerful media management package for Laravel Apps with support for painless uploader, virtual collection & automatic conversion plus an on demand association with specific broadcasting channels of your app models.

MediaMan is UI agnostic & provides a fluent API to manage your app's media, which means you've total control over your media, the look & feel & a hassle free dev experience. It's a perfect suit for your App or API server.

In a hurry? Here's a quick example

Why Choose MediaMan? What Sets It Apart?

While many Laravel applications grapple with media and file management, I've often found solace in Spatie's Laravel MediaLibrary. Yet, despite its capabilities, there were aspects it didn't address, features I yearned for.

Enter MediaMan: Sleek, lightweight, and brimming with functionality. Whether you need a straightforward solution for attaching and detaching media or the robust backbone for an extensive media manager, MediaMan adapts to your needs. And rest assured, its evolution will be guided by the ever-changing requirements of modern applications, whether they are Monolithic, API-driven, enhanced with Livewire/InertiaJS integrations, or built upon Serverless architectures.

Overview & Key concepts

There are a few key concepts that need to be understood before continuing:

• Media: It can be any type of file. You should specify file restrictions in your application's validation logic before you attempt to upload a file.

• MediaUploader: Media items are uploaded as its own entity. It does not belong to any other model in the system when it's being created, so items can be managed independently (which makes it the perfect engine for a media manager). MediaMan provides "MediaUploader" for creating records in the database & storing in the filesystem as well.

• MediaCollection: It can be also referred to as a group of files. Media items can be bundled to any "collection". Media & Collections will form many-to-many relation. You can create collections / virtual directories / groups of media & later on retrieve a group to check what it contains or do.

• Association: Media items need be attached to a model for an association to be made. MediaMan exposes helpers to easily get the job done. Many-to-many polymorphic relationships allow any number of media to be associated to any number of other models without the need of modifying the existing database schema.

• Channel: It can be also referred to as a tag of files. Media items are bound to a "channel" of a model during association. Thus you can easily associate multiple types of media to a model. For example, a "User" model might have an "avatar" and a "documents" media channel. If your head is spinning, simply think of "channels" as :tags" for a specific model. Channels are also needed to perform conversions.

• Conversion: You can manipulate images using conversions, conversions will be performed when a media item is associated to a model. For example, you can register a "thumbnail" conversion to run when images are attached to the "gallery" channel of a model.

Table of Contents

• Requirements
• Installation
• Configuration
• Media
• Media & Models
• Collections
• Media & Collections
• Media, Models & Conversions
• Upgrade Guide to MediaMan v1.x
• Contribution and License

Requirements

Note: From version 2.x of the Laravel Mediaman package, only Laravel 10 and higher versions will be supported; please consider upgrading as official support for previous versions has ended.

Installation

You can install the package via composer:

The package should be auto discovered by Laravel unless you've disabled auto-discovery mode. In that case, add the service provider to your config/app.php:

FarhanShares\MediaMan\MediaManServiceProvider::class

Once installed, you should publish the provided assets to create the necessary migration and config files.

Ensure the storage is linked.

Run the migration and you are all set.

Configuration

MediaMan works out of the box. If you want to tweak it, MediaMan ships with a config/mediaman.php. One common need of tweaking could be to store media in a dedicated Storage.

MediaMan supports all of the storage drivers that are supported by Laravel (for i.e. Local, S3, SFTP, FTP, Dropbox & so on).

Here's an example configuration to use a dedicated local media disk for MediaMan.

Now, run php artisan storage:link to create the symbolic link of our newly created media disk.

Media

Upload media

You should use the FarhanShares\MediaMan\MediaUploader class to handle file uploads. You can upload, create a record in the database & store the file in the filesystem in one go.

The file will be stored in the default disk & bundled in the default collection specified in the mediaman config. The file size will be stored in the database & the file name will be sanitized automatically.

However, you can do a lot more, not just stick to the defaults.

If the collection doesn't exist, it'll be created on the fly. You can read more about collections below.

Q: What happens if I don't provide a unique file name in the above process?

A: Don't worry, MediaMan manages uploading in a smart & safe way. Files are stored in the disk in a way that conflicts are barely going to happen. When storing in the disk, MediaMan will create a directory in the disk with a format of: mediaId-hash & put the file inside of it. Anything related to the file will have it's own little house.

Q: But why? Won't I get a bunch of directories?

A: Yes, you'll. If you want, extend the FarhanShares\MediaMan\Models\Media model & you can customize however you like. Finally point your customized model in the mediaman config. But we recommend sticking to the default, thus you don't need to worry about file conflicts. A hash is added along with the mediaId, hence users won't be able to guess & retrieve a random file. More on customization will be added later.

Reminder: MediaMan treats any file (instance of Illuminate\Http\UploadedFile) as a media source. If you want a certain file types can be uploaded, you can use Laravel's validator.

Retrieve media

You can use any Eloquent operation to retrieve a media plus we've added findByName().

An instance of Media has the following attributes:

You have access to some methods along with the attributes:

Update media

With an instance of Media, you can perform various update operations:

Update Media Name

Update Additional Data

Remove All Additional Data

Update Media File Name

Updating the media file name will also rename the actual file in storage.

Change Media Storage Disk

Moving the media to another storage disk will transfer the actual file to the specified disk.

Heads Up! There's a config regarding disk accessibility checks for read-write operations: check_disk_accessibility.

Disk Accessibility Checks:

• Pros: Identifies potential disk issues early on.

• Cons: Can introduce performance delays.

Tip: Enabling this check can preemptively spot storage issues, but may add minor operational delays. Consider your system's needs and decide accordingly.

Delete media

You can delete a media by calling delete() method on an instance of Media.

Or you delete media like this:

Note: When a Media instance gets deleted, file will be removed from the filesystem, all the association with your App Models & MediaCollection will be removed as well.

Heads Up!: You should not delete media using queries, e.g. Media::where('name', 'the-file')->delete(), this will not trigger deleted event & the file won't be deleted from the filesystem. Read more about it in the official documentation.

Media & Models

Associate media

MediaMan exposes easy to use API via FarhanShares\MediaMan\HasMedia trait for associating media items to models. Use the trait in your App Model & you are good to go.

This will establish the relationship between your App Model and the Media Model.

Once done, you can associate media to the model as demonstrated below.

The first parameter of the attachMedia() method can either be a media model / id or an iterable collection of models / ids.

attachMedia() returns number of media attached (int) on success & null on failure.

Retrieve media of a model

Apart from that, HasMedia trait enables your App Models retrieving media conveniently.

Though the original media URL is appended with the Media model, it's nice to know that you have a getUrl() method available.

It might be a common scenario for most of the Laravel apps to use the first media item more often, hence MediaMan has dedicated methods to retrieve the first item among all associated media.

Tip: getFirstMediaUrl() accepts two optional arguments: channel name & conversion name

Disassociate media

You can use detachMedia() method which is also shipped with HasMedia trait to disassociate media from model.

detachMedia() returns number of media detached (int) on success & null on failure.

Synchronize association / disassociation

You can sync media of a specified channel using the syncMedia() method. This provides a flexible way to maintain the association between your model and the related media records. The default method signature look like this: syncMedia($media, string $channel = 'default', array $conversions = [], $detaching = true)

This will remove the media that aren't in the provided list and add those which aren't already attached if $detaching is truthy.

Heads Up!: None of the attachMedia, detachMedia or syncMedia methods deletes the file, it just does as it means. Refer to delete media section to know how to delete a media.

Collections

MediaMan provides collections to bundle your media for better media management. Use FarhanShares\MediaMan\Models\MediaCollection to deal with media collections.

Create collection

Collections are created on thy fly if it doesn't exist while uploading file.

If you wish to create collection without uploading a file, you can do it, after all, it's an Eloquent model.

Retrieve collection

You can retrieve a collection by it's id or name.

Update collection

You can update a collection name. It doesn't really have any other things to update.

Delete collection

You can delete a collection using an instance of MediaCollection.

This won't delete the media from disk but the bindings will be removed from database.

Heads Up! deleteWithMedia() is a conceptual method that hasn't implemented yet, create a feature request if you need this. PRs are very much appreciated.

Media & Collections

The relationship between Media & MediaCollection are already configured. You can bind, unbind & sync binding & unbinding easily. The method signatures are similar for Media::**Collections() and MediaCollection::**Media().

Bind media

attachMedia() returns number of media attached (int) on success & null on failure. Alternatively, you can use Media::attachCollections() to bind to collections from a media model instance.

Heads Up! Unlike HasMedia trait, you can not have channels on media collections.

Unbind media

detachMedia() returns number of media detached (int) on success & null on failure. Alternatively, you can use Media::detachCollections() to unbind from collections from a media model instance.

Synchronize binding & unbinding

syncMedia() always returns an array containing synchronization status. Alternatively, you can use Media::syncCollections() to sync with collections from a media model instance.

Conversions

You can specify a model to perform "conversions" when a media is attached to a channel.

MediaMan provides a fluent api to manipulate images. It uses the popular intervention/image library under the hood. Resizing, adding watermark, converting to a different format or anything that is supported can be done. In short, You can utilize all functionalities from the library.

Conversions are registered globally. This means that they can be reused across your application, for i.e a Post and a User both can have the same sized thumbnail without having to register the same conversion twice.

To get started, you should first register a conversion in one of your application's service providers:

Once you've registered a conversion, you should configure a media channel to perform the conversion when media is attached to your model.

From now on, whenever a media item is attached to the "gallery" channel, a converted image will be generated. You can get the url of the converted image as demonstrated below:

Tip: The default channel name is default.

Tip: The media_uri and media_url are always appended with an instance of Media, these reflect the original file (and not the conversions).

Upgrade Guide to MediaMan v1.x

If you're upgrading from a previous version of MediaMan, rest assured that the transition is fairly straightforward. Here's what you need to know:

Changes

• Introduction of media_uri: In this release, we've introduced a new attribute called media_uri. This provides the URI for the original file. When you want to generate a full URL for use in Blade, you'd use it like so:

• Modification to media_url: In previous versions, media_url used to act like what media_uri does now. Starting from v1.0.0, media_url will directly give you the absolute URL for the original file.

Steps to Upgrade

1. Update the Package: Run the composer update command to get the latest version.

2. Review Your Blade Files: If you previously used media_url with the asset() helper, like:

   Update it to:

   If you used media_url without asset(), there's no change required.

3. Run Any New Migrations (if applicable): Always check for new migrations and run them to ensure your database schema is up-to-date.

4. Test Your Application: As always, after an upgrade, ensure you test your application thoroughly, especially the parts where media files are used, to make sure everything works as expected.

Thank you for using MediaMan and we hope you enjoy the improvements in v1.0.0! If you face any issues, feel free to open a ticket on GitHub.

Contribution and License

If you encounter a bug, please consider opening an issue. Feature Requests & PRs are welcome.

The MIT License (MIT). Please read License File for more information.