Laravel Filesystem Laravel Package

Getting Started

Install via Composer:

composer require expresslanding/laravel-filesystem

Publish the config file (if needed) for custom disk configurations:

php artisan vendor:publish --provider="ExpressLanding\Filesystem\FilesystemServiceProvider" --tag="config"

First Use Case: Check if a disk exists or is present:

use ExpressLanding\Filesystem\Facades\Filesystem;

// Check if disk is present (connected, mounted, etc.)
$isPresent = Filesystem::disk('s3')->isPresent();

// Check if disk exists in configuration
$exists = Filesystem::disk('s3')->exists();

Implementation Patterns

Core Workflows

1. Disk Validation:

   • Use isPresent() to verify physical availability (e.g., network drives, cloud connections).
   • Use exists() to validate configuration (e.g., disk is defined in filesystems.php).

   if (Filesystem::disk('custom')->isPresent() && Filesystem::disk('custom')->exists()) {
       // Proceed with operations
   }
   

2. Dynamic Disk Handling:

   • Leverage the package’s methods in middleware, service providers, or controllers to gate access:

   public function handle(Request $request, Closure $next)
   {
       if (!Filesystem::disk('s3')->isPresent()) {
           abort(503, 'Storage unavailable');
       }
       return $next($request);
   }
   

3. Fallback Logic:

   • Combine with Laravel’s native Storage facade for hybrid checks:

   if (Filesystem::disk('local')->exists() && Storage::disk('local')->exists()) {
       // Use Storage facade for operations
   }
   

Integration Tips

• Configuration: Ensure filesystems.php includes the driver key (fixed in v1.0.5). Example:

  'disks' => [
      's3' => [
          'driver' => 's3', // Required for driver-type checks
          'key' => env('AWS_KEY'),
          // ...
      ],
  ],
  

• Testing: Mock disk presence/existence in unit tests:

  $this->partialMock(Filesystem::class, 'isPresent')
       ->shouldReceive('isPresent')
       ->andReturnTrue();
  

Gotchas and Tips

Breaking Changes (v1.0.5)

• Deprecated Methods: The package no longer uses a single check() method. Update calls from:

  Filesystem::disk('s3')->check(); // ❌ Deprecated
  

  to:

  Filesystem::disk('s3')->isPresent(); // ✅ Physical check
  Filesystem::disk('s3')->exists();    // ✅ Config check
  

Debugging

• Missing Driver Key: If isPresent() returns false unexpectedly, verify the driver key exists in filesystems.php. The v1.0.5 bug fix ensures this is required for accurate checks.
• Network Disks: isPresent() may return false for transient network issues. Implement retries or fallback disks:

  $attempts = 0;
  while (!$Filesystem::disk('s3')->isPresent() && $attempts < 3) {
      sleep(2);
      $attempts++;
  }
  

Extension Points

• Custom Drivers: Extend the package by creating a custom disk driver that implements isPresent() logic:

  namespace App\Filesystem;
  
  use ExpressLanding\Filesystem\Contracts\DiskInterface;
  
  class CustomDisk implements DiskInterface {
      public function isPresent(): bool {
          // Custom logic (e.g., ping a service)
          return true;
      }
  }
  

  Register it in FilesystemServiceProvider:

  $this->app->bind('custom', function () {
      return new CustomDisk();
  });
  

• Event Listeners: Listen for disk state changes (e.g., when a disk becomes unavailable):

  Filesystem::disk('s3')->listen(function ($disk) {
      Log::warning("Disk {$disk->getName()} is no longer present");
  });