README

Secure your media file access with authentication and policy-based authorization. Built on top of Spatie Laravel MediaLibrary, this package provides secure view, download, and stream endpoints with fine-grained access control.

Features

• Secure media URLs with UUID-based routing
• Three access types: view, download, and stream
• Signed URLs for time-limited access without authentication
• Authentication requirement (configurable)
• Policy-based authorization with parent model delegation
• Customizable middleware stack
• ETag/Last-Modified caching headers for performance
• Memory-efficient file streaming for large files
• Helper functions for URL generation

Installation

composer require cleaniquecoders/laravel-media-secure

Publish the config file:

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

Quick Start

1. Generate Secure URLs (Authenticated)

use Spatie\MediaLibrary\MediaCollections\Models\Media;

// Get view URL: /media/view/{uuid}
$viewUrl = get_view_media_url($media);

// Get download URL: /media/download/{uuid}
$downloadUrl = get_download_media_url($media);

// Get stream URL: /media/stream/{uuid}
$streamUrl = get_stream_media_url($media);

2. Generate Signed URLs (Shareable)

Signed URLs allow sharing media with external users without requiring authentication. URLs are cryptographically signed and expire after a configurable time.

// Generate signed URL (default expiration from config)
$signedUrl = get_signed_view_url($media);

// Generate signed URL with custom expiration (in minutes)
$signedUrl = get_signed_download_url($media, 30); // Expires in 30 minutes

// Generate signed URL with DateTime expiration
$signedUrl = get_signed_stream_url($media, now()->addHours(24));

// Using the Facade
use CleaniqueCoders\LaravelMediaSecure\Facades\LaravelMediaSecure;

$url = LaravelMediaSecure::signedViewUrl($media);
$url = LaravelMediaSecure::signedDownloadUrl($media, 60);

3. Create a Policy for Your Model (Required when strict = true)

namespace App\Policies;

use App\Models\Document;
use App\Models\User;

class DocumentPolicy
{
    public function view(User $user, Document $document): bool
    {
        return $user->id === $document->user_id;
    }

    public function stream(User $user, Document $document): bool
    {
        return $user->id === $document->user_id;
    }

    public function download(User $user, Document $document): bool
    {
        return $user->id === $document->user_id;
    }
}

4. Register the Policy

// In AuthServiceProvider
protected $policies = [
    \App\Models\Document::class => \App\Policies\DocumentPolicy::class,
];

Signed URLs

Signed URLs are perfect for:

• Sharing files via email or messaging
• Embedding media in external applications
• Providing temporary access to clients
• API integrations where authentication is impractical

Configuration

// config/laravel-media-secure.php

'signed' => [
    'enabled' => env('LARAVEL_MEDIA_SECURE_SIGNED_ENABLED', true),
    'prefix' => 'media-signed',
    'route_name' => 'media.signed',
    'expiration' => env('LARAVEL_MEDIA_SECURE_SIGNED_EXPIRATION', 60), // minutes
],

Environment Variables

LARAVEL_MEDIA_SECURE_SIGNED_ENABLED=true
LARAVEL_MEDIA_SECURE_SIGNED_EXPIRATION=60

Documentation

For detailed documentation, see docs/README.md.

• Getting Started
• Configuration
• Authorization
• Signed URLs

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Nasrul Hazim Bin Mohamad
• All Contributors

License

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