README

Generate, manage, and secure temporary share links for files, routes, and models

A powerful Laravel package for creating secure, time-limited sharing capabilities with comprehensive audit trails

🚀 Overview

Laravel ShareLink is a comprehensive package for generating secure, time-limited sharing capabilities in your Laravel applications. Perfect for sharing files, creating temporary access to routes, or providing time-limited previews of model data with complete audit trails and advanced security features.

✨ Key Features

🔗 Multiple Resource Types - Share files, routes, and model previews seamlessly
⏰ Time-Limited Access - Set expiration dates and usage limits
🔒 Password Protection - Optional password gates for enhanced security
🚫 Rate Limiting - Per-token rate limiting to prevent abuse
🌐 IP Filtering - Allow/deny specific IP addresses or CIDR ranges
🔏 Signed URLs - Optional Laravel signed route integration
🔥 Burn After Reading - One-time access links that self-destruct
📊 Comprehensive Auditing - Track access patterns, IPs, and timestamps
🛡️ Advanced Security - Password throttling, brute force protection
🎯 Flexible Delivery - Support for X-Sendfile, X-Accel-Redirect, and streaming
📋 Management API - Revoke and extend links programmatically
🎨 CLI Commands - Full Artisan command support
📈 Observability - Built-in logging and metrics integration
🧪 Test-Friendly - Comprehensive test coverage with easy mocking

📦 Installation

Install the package via Composer:

composer require grazulex/laravel-sharelink

Publish and run the migrations:

php artisan vendor:publish --tag="sharelink-migrations"
php artisan migrate

Optionally, publish the configuration file:

php artisan vendor:publish --tag="sharelink-config"

💡 Auto-Discovery: The service provider will be automatically registered thanks to Laravel's package auto-discovery.

⚡ Quick Start

🚀 Basic Usage

use Grazulex\ShareLink\Facades\ShareLink;

// Share a file with expiration
$link = ShareLink::create('/path/to/document.pdf')
    ->expiresIn(60) // 60 minutes
    ->maxClicks(5)
    ->withPassword('secret123')
    ->generate();

echo $link->url; // https://yourapp.com/share/abc123xyz

📁 File Sharing

// Share a local file
$link = ShareLink::create('/storage/documents/report.pdf')
    ->expiresIn(1440) // 24 hours
    ->maxClicks(10)
    ->generate();

// Share via Laravel Storage
$link = ShareLink::create('s3://bucket/private/document.pdf')
    ->expiresIn(60)
    ->withPassword('secure')
    ->generate();

🌐 Route Sharing

// Share a named route with parameters
$link = ShareLink::create([
    'type' => 'route',
    'route' => 'user.profile',
    'parameters' => ['user' => 123]
])
->expiresIn(120)
->generate();

📊 Model Preview

// Share a model preview (JSON representation)
$user = User::find(1);
$link = ShareLink::create([
    'type' => 'model',
    'class' => User::class,
    'id' => $user->id
])
->expiresIn(30)
->generate();

🔥 Advanced Security Features

// Burn-after-reading link with IP restrictions
$link = ShareLink::create('/secure/document.pdf')
    ->expiresIn(60)
    ->burnAfterReading() // Self-destructs after first access
    ->metadata([
        'allowed_ips' => ['192.168.1.0/24', '10.0.0.1'],
        'denied_ips' => ['192.168.1.100']
    ])
    ->generate();

// Signed URL for extra security
$signedUrl = ShareLink::signedUrl($link, now()->addHour());

🔧 Requirements

PHP 8.3+
Laravel 11.0+ | 12.0+

📚 Complete Documentation

For comprehensive documentation, examples, and advanced usage guides, visit our Wiki:

📖 👉 Laravel ShareLink Wiki

The wiki includes:

🚀 Installation & Setup
⚙️ Configuration
🎯 Quickstart Guide
🌐 API Endpoints
📋 API Reference
🛡️ Security Features
📡 Events & Observability
🎨 CLI Commands
📈 Version Matrix
📝 Changelog

🎨 Artisan Commands

Laravel ShareLink includes powerful CLI commands for managing your share links:

# Create a new share link
php artisan sharelink:create /path/to/file --expires=60 --max-clicks=5

# List all share links
php artisan sharelink:list --active --expired

# Revoke a specific link
php artisan sharelink:revoke abc123xyz

# Clean up expired links
php artisan sharelink:prune --days=7

🔧 Configuration

The package comes with sensible defaults, but you can customize everything:

// config/sharelink.php
return [
    'route' => [
        'prefix' => 'share',
        'middleware' => ['web'],
    ],
    
    'security' => [
        'signed_routes' => [
            'enabled' => true,
            'required' => false,
        ],
        'rate_limiting' => [
            'enabled' => true,
            'max_attempts' => 10,
        ],
        'password_throttling' => [
            'enabled' => true,
            'max_attempts' => 5,
        ],
    ],
    
    'delivery' => [
        'x_sendfile' => false,
        'x_accel_redirect' => false,
    ],
];

🧪 Testing

composer test

🤝 Contributing

Please see CONTRIBUTING.md for details.

🔒 Security

If you discover any security-related issues, please email jms@grazulex.be instead of using the issue tracker.

📝 Changelog

Please see the Wiki Changelog for more information on what has changed recently.

📄 License

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

👥 Credits

Jean-Marc Strauven
All Contributors

💬 Support

🐛 Report Issues
💬 Discussions
📖 Documentation

Laravel ShareLink - Secure, time-limited sharing for Laravel applications
with comprehensive audit trails and advanced security features.

grazulex / laravel-sharelink

Maintainers

Details