Download the PHP package iamgerwin/nova-media-hub without Composer

Nova Media Hub

A comprehensive media management package for Laravel Nova with advanced chunked upload support for handling large files efficiently.

Table of Contents

• Features
• Requirements
• Package Structure
• Installation
• Configuration
• Usage
  • Basic Usage
  • Field Configuration
  • Model Integration
  • Chunked Upload API
• Advanced Use Cases
• Edge Cases
• Testing
• Security
• Maintenance
• Contributing
• Issues & Support
• Credits
• License

Features

Core Features

• Media Hub Interface - Dedicated Nova tool for managing media assets
• Media Hub Field - Custom field for selecting single or multiple media items
• Image Optimization - Automatic optimization and multiple format conversions
• Collections - Organize media into logical collections
• Dark Mode Support - Full support for Nova's dark mode
• Localization - Multi-language support with translation loader
• Custom Fields - Extensible metadata fields (e.g., copyright, alt text)

Chunked Upload System

• Large File Support - Upload files up to 1GB+ without server configuration changes
• Real-time Progress - Visual progress tracking with percentage display
• Automatic Retry - Intelligent retry logic for failed chunk uploads
• Smart Fallback - Automatic fallback to standard upload for small files
• Memory Efficient - Streaming-based chunk combination prevents memory exhaustion
• Session Management - Cache-based upload state persistence
• Configurable - Adjustable chunk sizes, retry attempts, and thresholds

Developer Features

• Multi-version Compatibility - Supports PHP 8.2-8.3, Laravel 10-12, Nova 4-5
• Extensive Testing - Comprehensive test suite with CI/CD pipeline
• Type Safety - Full type hints and strict type checking
• Clean API - Intuitive, well-documented API
• Extensible - Hooks and events for customization

Requirements

Package Structure

Installation

Install the package via Composer:

Run the migrations to create the media library table:

Publish the configuration file (optional):

Publish translations (optional):

Register the tool in your NovaServiceProvider:

Configuration

The package configuration file is located at config/nova-media-hub.php. Key configuration options include:

Storage Configuration

Chunked Upload Configuration

Image Optimization

Usage

Basic Usage

Add the MediaHubField to your Nova resource:

Field Configuration

Single Media Selection

Multiple Media Selection

Collection-specific Selection

Hide from Listing

Model Integration

Using Media Cast

The package provides a custom cast for seamless model integration:

Accessing Media in Blade

Accessing Media in Controllers

Chunked Upload API

For custom implementations or advanced use cases, you can use the ChunkedUploader JavaScript class:

Advanced Use Cases

Custom Media Fields

Add custom metadata fields to the Media Hub:

Programmatic Media Upload

Batch Operations

Custom Image Conversions

Queue Image Processing

For better performance, queue image optimization:

Don't forget to run the queue worker:

Edge Cases

Large File Uploads (>100MB)

For very large files, adjust the chunk size and timeout settings:

Also, ensure your server has adequate disk space for temporary chunks.

Slow Network Connections

The chunked upload system handles slow connections gracefully with automatic retries. Configure retry behavior:

Concurrent Uploads

The package supports concurrent uploads using UUID-based session management. Each upload maintains its own isolated state.

Memory-Constrained Environments

The package uses streaming for chunk combination to minimize memory usage:

Interrupted Uploads

If an upload is interrupted (browser closed, connection lost), you can resume:

Cross-Domain Uploads

When uploading from a different domain, ensure CORS is properly configured:

File Type Restrictions

Restrict allowed file types:

Testing

The package includes a comprehensive test suite to ensure stability and reliability.

Running Tests

Test Structure

Writing Tests

When contributing, please include tests for new features:

Continuous Integration

The package uses GitHub Actions for automated testing across multiple PHP and Laravel versions:

• PHP Versions: 8.2, 8.3
• Laravel Versions: 10.x, 11.x
• Test Matrix: 12+ version combinations

View test results: GitHub Actions

Security

Security Vulnerabilities

If you discover a security vulnerability within Nova Media Hub, please send an email to [email protected]. All security vulnerabilities will be promptly addressed.

Please do not create public GitHub issues for security vulnerabilities.

Security Features

The package implements several security measures:

File Upload Security

• MIME Type Validation - Validates file types before upload
• File Size Limits - Enforces maximum file size restrictions
• Filename Sanitization - Removes dangerous characters from filenames
• Extension Whitelisting - Only allows specified file extensions

Chunked Upload Security

• UUID Session IDs - Prevents session guessing attacks
• CSRF Protection - All endpoints require valid CSRF tokens
• Chunk Index Validation - Prevents malicious chunk injection
• File Hash Verification - Validates file integrity after assembly
• Temporary File Isolation - Chunks stored in isolated directories

Authorization

• Nova Authorization - Respects Nova's authorization policies
• Middleware Protection - All routes protected by authentication middleware
• Permission Checks - User permissions verified before operations

Best Practices

1. Validate User Input - Always validate and sanitize user-provided data
2. Restrict File Types - Only allow necessary MIME types
3. Set Size Limits - Configure appropriate file size limits
4. Use HTTPS - Always serve media over HTTPS in production
5. Regular Updates - Keep the package and dependencies up to date
6. Monitor Uploads - Log and monitor upload activity for suspicious patterns

Reported Vulnerabilities

None reported as of the latest release (0.0.3).

Maintenance

Cleanup Command

The package includes a cleanup command to remove old temporary chunk files:

Scheduled Cleanup

Add the cleanup command to your scheduler in app/Console/Kernel.php:

Monitoring Disk Usage

Monitor storage disk usage to prevent issues:

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository

2. Create a feature branch

3. Install dependencies

4. Make your changes

   • Write tests for new features
   • Follow PSR-12 coding standards
   • Update documentation as needed

5. Run tests

6. Commit your changes

7. Push to your fork

8. Create a Pull Request
   • Provide a clear description of the changes
   • Reference any related issues
   • Ensure CI tests pass

Development Setup

Issues & Support

Found a bug or have a feature request? Please create an issue on GitHub:

Submit an Issue

When submitting an issue, please include:

• Description - Clear description of the issue or feature request
• Steps to Reproduce - Detailed steps to reproduce the issue (for bugs)
• Expected Behavior - What you expected to happen
• Actual Behavior - What actually happened
• Environment:
  • PHP version
  • Laravel version
  • Nova version
  • Package version
  • Operating system
• Code Samples - Relevant code snippets or configuration
• Screenshots - If applicable

Before Submitting an Issue

1. Check if the issue already exists
2. Update to the latest version
3. Check the documentation
4. Review closed issues for similar problems

Security Vulnerabilities

If you discover a security vulnerability, please email [email protected] instead of using the issue tracker.

Credits

• Author: John Gerwin De las Alas
• Contributors: All Contributors

License

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

Links

• Packagist
• GitHub Repository
• Issue Tracker
• Changelog