README

The media package utilizes Cloudinary for images and YouTube for videos. Create a free Cloudinary account for each Laravel application utilizing this package here:

Cloudinary

Models

The following models are included in this package:

List of Models

Image
Tag
Video

Installation

You can install the package via composer:

composer require drewroberts/media

Environment variables (Cloudinary Laravel v3)

Add your Cloudinary credentials to your .env file. Choose one of the following options:

Required env variables:

CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_KEY=
CLOUDINARY_SECRET=
FILESYSTEM_DISK=cloudinary

Note

You can get your credentials from your Cloudinary console.

Configure the Cloudinary disk (required)

Add a cloudinary disk to your config/filesystems.php:

return [
    ...
    'disks' => [
        ...
        'cloudinary' => [
            'driver' => 'cloudinary',
            'key' => env('CLOUDINARY_KEY'),
            'secret' => env('CLOUDINARY_SECRET'),
            'cloud' => env('CLOUDINARY_CLOUD_NAME'),
            'url' => env('CLOUDINARY_URL'),
            'secure' => (bool) env('CLOUDINARY_SECURE', true),
            'prefix' => env('CLOUDINARY_PREFIX'),
        ]
    ]
];

The package expects filesystems.disks.cloudinary.cloud to be set. If missing, URL helpers will throw an informative exception.

Media package config (optional)

This package ships with config/media.php for its own options. You can publish and customize it:

php artisan vendor:publish --tag=media-config

Available options and defaults:

return [
    'transforms' => [
        'cover' => 't_cover',
        'cover_placeholder' => 't_coverplaceholder',
    ],

    // Relative path; wrapped with url() in code when no image exists
    'fallback_image' => 'img/ogimage.jpg',

    // YouTube Data API V3 integration (Non-OAuth)
    'youtube' => [
        // Set in your application's .env
        'api_key' => env('YOUTUBE_API_KEY'),

        // HTTP request options
        'timeout' => 8.0, // seconds
        'base_url' => 'https://www.googleapis.com/youtube/v3',

        // Preferred order for selecting thumbnails
        'thumbnail_preference' => [
            'maxres', 'standard', 'high', 'medium', 'default',
        ],
    ],
];

Note

In your Cloudinary console, create a Named Transformation called t_cover sized to 1200x630 pixels. This package references that name to render cover images.

Create another Named Transformation t_coverplaceholder sized to 120x63 pixels. This is intended as a lightweight loading placeholder, while the full t_cover image can be lazy-loaded by the frontend.

YouTube Data API v3 (Non-OAuth)

This package integrates with the official YouTube Data API v3 using an API key (no OAuth). It is used to parse YouTube links, fetch video details (title, description, duration, publish date, statistics, etc.), and pick the best thumbnail.

Required env variable:

YOUTUBE_API_KEY=

Notes

Obtain an API key from your Google Cloud Console and enable the YouTube Data API v3 for your project.
You can customize request timeout, base URL, and thumbnail selection order via config/media.php under the youtube key (publish the config if needed).
API quota or configuration issues will surface as clear exceptions; ensure the key is set in environments where the service is used.

Filament Admin Resources

This package ships first‑party Filament resources for managing media:

Images: Resource, pages, form schema, and table
Tags: Resource, pages, form schema, and table
Videos: Resource, pages, form schema, and table, including:
- Create via YouTube URL/ID (fetches metadata on submit)
- Edit with read‑only metadata and editable “Internal Name”, “Credit”, and “Thumbnail”
- A “Refresh API Data” button on the edit page to pull the latest details from YouTube

How they’re registered

The package provides a Filament plugin that auto‑discovers resources from DrewRoberts\Media\Filament\Resources.
In your Filament Panel config, install the package plugin (if not auto‑discovered in your setup).

User Resource in your application

This package does not provide a Filament User resource. Your Laravel application should create its own Filament User resource with php artisan make:filament-resource Customer
The media models reference your app’s user model via config('auth.providers.users.model') for creator_id and updater_id relations. No additional wiring is required.

Migrations

This package auto-runs its migrations and does not publish them.

The following tables are created:

images
videos
tags
taggables

Note: Because migrations are auto-loaded, you don’t need to vendor:publish them. If you need to customize the schema, override with your own migrations in your application.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

License

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

drewroberts / media

Maintainers

Details