Tissue Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Laravel Compatibility: The package is a Symfony Bundle, not a Laravel package, which introduces a fundamental architectural mismatch. Laravel does not natively support Symfony Bundles, requiring either:
  • A Symfony microkernel integration (complex, non-standard).
  • A wrapper layer (e.g., custom facade or service container adaptation).
• Core Functionality Alignment: The package leverages the Tissue library (a PHP virus-scanning wrapper for ClamAV) to scan files. This aligns well with Laravel’s file-handling needs (e.g., uploads, storage) but requires custom integration for Symfony-specific components (e.g., DependencyInjection).
• Use Case Suitability: Ideal for Laravel apps needing file-based virus scanning (e.g., file uploads, media libraries, or document processing). Less relevant for headless APIs or non-file-centric apps.

Integration Feasibility

• High-Level Feasibility: Possible, but non-trivial due to Symfony’s bundle architecture. Options:
  1. Symfony Microkernel: Embed a Symfony kernel in Laravel (overkill for most use cases).
  2. Standalone Tissue Library: Use tissue/tissue directly (the underlying library) via Composer, bypassing the Bundle.
  3. Laravel Service Provider: Reimplement Bundle logic in a Laravel ServiceProvider (recommended for minimalism).
• Dependencies:
  • Requires ClamAV (external service) and PHP extensions (clamav or exec() for CLI calls).
  • May conflict with Laravel’s PSR-4 autoloading if not isolated.
• Testing Complexity: Integration testing will need mocks for ClamAV interactions, adding complexity.

Technical Risk

Key Questions

1. Why a Symfony Bundle?
   • Is the Bundle’s specific configuration (e.g., YAML-based scanning rules) critical, or can tissue/tissue suffice?
2. ClamAV Infrastructure:
   • Is ClamAV available as a service (e.g., Docker, cloud), or must it be locally installed?
3. Scaling Needs:
   • Will scans be synchronous (blocking) or asynchronous (queued)?
4. Fallback Strategy:
   • How should the system handle ClamAV failures (e.g., network issues, service down)?
5. Maintenance:
   • Who will update the Symfony Bundle if Laravel-specific changes are needed?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Not natively supported, but the underlying tissue/tissue library is PHP-agnostic and can be used directly.
  • Recommended Stack:
    • Laravel 8+ (for service containers and queues).
    • PHP 8.0+ (for named arguments and attributes).
    • ClamAV (local or remote service).
• Alternatives:
  • Symfony Microkernel: Only if the Bundle’s full feature set (e.g., Twig integration) is required.
  • Custom Wrapper: Build a Laravel ServiceProvider to expose Tissue functionality.

Migration Path

1. Assess Dependency Scope:
   • Replace cleentfaar/tissue-bundle with tissue/tissue in composer.json.
   • Remove Symfony-specific autoloading (e.g., autoload-dev for Bundles).
2. Refactor Configuration:
   • Move Bundle’s YAML/XML configs to Laravel’s config/tissue.php (or environment variables).
   • Example:

     // config/tissue.php
     return [
         'clamav_binary' => env('CLAMAV_BINARY', '/usr/bin/clamscan'),
         'scan_on_upload' => true,
         'allowed_mime_types' => ['image/jpeg', 'application/pdf'],
     ];
     

3. Service Container Integration:
   • Register Tissue as a Laravel service provider:

     // app/Providers/TissueServiceProvider.php
     public function register()
     {
         $this->app->singleton(TissueScanner::class, function ($app) {
             return new TissueScanner(config('tissue.clamav_binary'));
         });
     }
     

4. Facade/Helper Methods:
   • Create a facade for easy scanning:

     // app/Facades/Tissue.php
     public static function scanFile(string $path): bool {
         return app(TissueScanner::class)->scan($path);
     }
     

Compatibility

Sequencing

1. Phase 1: Proof of Concept (1-2 days)
   • Install tissue/tissue and test basic scanning.
   • Validate ClamAV integration (local/remote).
2. Phase 2: Laravel Integration (2-3 days)
   • Build ServiceProvider and facade.
   • Configure scanning triggers (e.g., file upload events).
3. Phase 3: Performance Optimization (1-2 days)
   • Implement async scanning (Laravel queues).
   • Cache results for frequent files.
4. Phase 4: Error Handling & Monitoring (1 day)
   • Add logging for scan failures.
   • Set up alerts for ClamAV downtime.

Operational Impact

Maintenance

• Dependency Updates:
  • tissue/tissue is actively maintained (check GitHub).
  • ClamAV updates may require PHP binary path adjustments.
• Laravel-Specific Overhead:
  • Minimal if using tissue/tissue directly; higher if wrapping Symfony Bundle logic.
• Configuration Drift:
  • Risk of hardcoded paths (e.g., ClamAV binary). Mitigate with ENV vars.

Support

• Debugging Complexity:
  • ClamAV failures may require system-level checks (e.g., clamscan --version).
  • Laravel logs may need custom formatting for Tissue errors.
• Vendor Support:
  • Primary support via:
    • Tissue GitHub Issues.
    • ClamAV community (e.g., FreshPorts).
• Documentation Gaps:
  • Bundle-specific docs (e.g., Symfony config) will need Laravel equivalents.

Scaling

• Horizontal Scaling:
  • Stateless Scanning: If ClamAV is remote, scales with Laravel instances.
  • Stateful Scanning: Local ClamAV requires shared storage or distributed scans (e.g., queue workers).
• Performance Bottlenecks:
  • Synchronous Scans: Block I/O; use queues (e.g., Laravel Horizon) for async processing.
  • Large Files: Stream scanning to avoid memory issues.
• ClamAV Load:
  • High scan volumes may overload ClamAV. Consider:
    • Dedicated ClamAV service (e.g., Docker container).
    • Rate limiting (e.g., scan batches).

Failure Modes