Laravel Mediable Laravel Package

Technical Evaluation

Architecture Fit

• Enhanced Security Model: The new release introduces robust security features (SSRF protection, SVG sanitization, forbidden extensions/MIME types) that align with modern Laravel applications requiring strict input validation and XSS protection. Ideal for:
  • High-security environments (e.g., financial platforms, healthcare apps).
  • Public-facing apps where user-uploaded media is rendered directly (e.g., social platforms, CMS).
  • Regulated industries (e.g., GDPR, HIPAA) where media sanitization is critical.
• Remote Media Handling: The allowed_remote_hosts and allowed_remote_schemes configurations enable controlled integration with third-party media sources (e.g., CDNs, APIs) while mitigating SSRF risks.
• Polymorphic + Security: Retains the original polymorphic flexibility but now with built-in safeguards against directory traversal, executable uploads, and stored XSS (via SVG sanitization).
• Config-Driven Customization: Security policies (e.g., forbidden extensions, sanitizers) are now centrally configurable, reducing hardcoded logic in business layers.

Integration Feasibility

• Backward Compatibility:
  • Breaking Changes:
    • MediaUploader constructor now requires a MediaUploaderConfiguration object (not an array), necessitating updates to existing upload logic.
    • ON_DUPLICATE_* constants are replaced with an enum (OnDuplicateBehaviour), requiring type adjustments.
    • beforeSave() now accepts a Closure (type-safe), but this is a minor change.
  • Non-Breaking Additions:
    • New security features are opt-in (e.g., SVG sanitization, forbidden extensions) and can be adopted incrementally.
• Migration Effort:
  • Low for new projects; moderate for existing ones due to the MediaUploader refactor.
  • Example migration for MediaUploader:

    // Before (6.x)
    $uploader = new MediaUploader($model, 'avatar', $request->file('avatar'), [
        'disk' => 's3',
        'tags' => ['profile'],
    ]);
    
    // After (7.0+)
    $config = new MediaUploaderConfiguration([
        'disk' => 's3',
        'tags' => ['profile'],
    ]);
    $uploader = new MediaUploader($model, 'avatar', $request->file('avatar'), $config);
    

• Security Overhead:
  • Minimal runtime impact for most use cases (sanitizers like SvgSanitizer only run on SVG uploads).
  • Forbidden extensions/MIME types add negligible validation overhead (~1–5ms per upload).

Technical Risk

• Security Misconfigurations:
  • Risk: Overly restrictive allowed_remote_hosts or forbidden_file_extensions may break legitimate workflows (e.g., blocking .zip uploads for document previews).
  • Mitigation: Start with default configurations, then whitelist/blacklist incrementally. Test edge cases (e.g., nested extensions like script.php.jpg).
• SVG Sanitization Performance:
  • Risk: SvgSanitizer may introduce latency for SVG uploads if not optimized (e.g., large SVGs with complex paths).
  • Mitigation: Benchmark sanitizer performance; consider async processing for high-volume SVG uploads.
• Enum Migration:
  • Risk: Forgetting to update ON_DUPLICATE_* usages to OnDuplicateBehaviour::SKIP/OnDuplicateBehaviour::REPLACE could cause runtime errors.
  • Mitigation: Use IDE refactoring tools (e.g., PHPStorm’s "Rename") to automate the switch.
• Storage Backend Quirks:
  • Risk: Directory traversal stripping (e.g., . in paths) may break apps relying on literal dot characters in filenames (e.g., file.123.txt).
  • Mitigation: Validate business requirements for dot characters in filenames pre-migration.

Key Questions

1. Security Requirements:
   • Are there existing policies for forbidden file extensions/MIME types? How do they align with the package’s defaults?
   • Are SVG uploads rendered directly to webpages? If yes, is the SvgSanitizer sufficient, or are additional XSS protections needed (e.g., CSP headers)?
2. Remote Media Workflows:
   • Does the app fetch media from untrusted remote URLs (e.g., user-provided links)? If so, how will allowed_remote_hosts be configured (e.g., whitelist specific domains)?
3. Legacy Upload Logic:
   • Are there existing MediaUploader instantiations with array configs? What’s the effort to refactor to MediaUploaderConfiguration?
4. Performance Sensitivity:
   • Will SVG sanitization impact critical paths? If so, should sanitization be queued or cached?
5. Compliance:
   • Are there regulatory requirements for media sanitization (e.g., OWASP Top 10, PCI DSS)? How does this package address them?
6. Testing Strategy:
   • How will security features be validated? For example:
     • Test that script.php.jpg is rejected.
     • Verify SVG sanitization strips <script> tags.
     • Confirm SSRF protection blocks private IP uploads.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Security Integration: Works seamlessly with Laravel’s validation pipeline (e.g., extend FormRequest to enforce forbidden extensions/MIME types).
  • Queue System: Async sanitization (e.g., SVG processing) can leverage Laravel Queues for scalability.
  • Testing: Compatible with Pest/Laravel’s testing tools (e.g., assert forbidden file rejections).
• Dependencies:
  • Required: plank/laravel-mediable:^7.0 (upgrade from ^6.5).
  • Optional:
    • spatie/image (for variants, if still used).
    • league/flysystem-aws-s3-v3 (for S3-specific optimizations).
  • Conflicts: None with Laravel 10/11 core or common packages (e.g., spatie/laravel-medialibrary).
• Anti-Patterns:
  • Avoid disabling security features (e.g., SvgSanitizer) unless absolutely necessary.
  • Don’t bypass forbidden extensions/MIME types via direct filesystem access.

Migration Path

1. Pre-Migration:

   • Audit:
     • Inventory all MediaUploader instantiations and usages of ON_DUPLICATE_* constants.
     • List all custom sanitizers or pre-save logic in beforeSave().
   • Backup: Export media metadata and files (e.g., media table dump + storage backup).
   • Test Environment: Upgrade a staging instance to validate security features (e.g., confirm SVG sanitization works).

2. Phased Upgrade:

   • Phase 1: Configuration Updates
     • Update config/mediable.php to include new security settings (e.g., forbidden_file_extensions, allowed_remote_hosts).
     • Example:

       'forbidden_file_extensions' => [
           'php', 'exe', 'sh', 'zip', 'js', // Defaults + custom
       ],
       'allowed_remote_hosts' => [
           '*.trusted-cdn.com',
           'api.example.com',
       ],
       

   • Phase 2: Code Refactoring
     • Replace array-based MediaUploader configs with MediaUploaderConfiguration:

       # Use a script to automate this (e.g., Regex find/replace)
       find app -type f -name "*.php" -exec sed -i 's/\(new MediaUploader\)(.*), \[/\1, new MediaUploaderConfiguration(\2/' {} +
       

     • Update ON_DUPLICATE_* usages:

       // Before
       $uploader->setOnDuplicateBehaviour(MediaUploader::ON_DUPLICATE_SKIP);
       
       // After
       $config->setOnDuplicateBehaviour(OnDuplicateBehaviour::SKIP);
       

     • Migrate beforeSave() callables to Closure:

       $uploader->beforeSave(fn (UploadingFile $file) => $file->setCustomProperty('source', 'admin'));
       

   • Phase 3: Security Hardening
     • Test remote uploads with malicious payloads (e.g., http://192.168.1.1/evil.php, file.php.jpg).
     • Validate SVG sanitization:

       $svg = <<<SVG
       <svg><script>alert('XSS')</script></svg>
       SVG;
       $file = new UploadingFile($svg, 'test.svg');
       $uploader->upload($file); // Should strip <script>
       

     • Audit logs for blocked uploads (e.g., mediable.log or custom logging).

3. Post-Migration:

   • Deprecation: Phase out old upload logic (e.g.,