Flysystem Sftp V3 Laravel Package

Getting Started

1. Install the package:

   composer require league/flysystem-sftp-v3 phpseclib/phpseclib:^3.0
   

   (Note: phpseclib/phpseclib is a required dependency but must be explicitly required due to sub-split isolation.)

2. Basic usage in Laravel:

   • Configure an SFTP disk in config/filesystems.php:

     'sftp' => [
         'driver' => 'sftp',
         'host' => env('SFTP_HOST'),
         'port' => env('SFTP_PORT', 22),
         'username' => env('SFTP_USERNAME'),
         'password' => env('SFTP_PASSWORD'), // or use 'privateKey' + 'passphrase'
         'privateKey' => storage_path('app/id_rsa'),
         'timeout' => 10,
         'root' => '/remote/path',
     ],
     

   • Use the Storage facade:

     Storage::disk('sftp')->put('remote-file.txt', 'content');
     

3. First use case: Upload user-generated reports to a secure server for archival or sharing.

Implementation Patterns

• Integration with Laravel:
  • Define SFTP credentials in .env for flexibility and security.
  • Use Storage::cloud() alias if SFTP is your primary cloud storage.
• Authentication patterns:
  • Prefer key-based auth (privateKey) over passwords for production.
  • Use phpseclib’s Key::load() for encrypted private keys with passphrase.
• Async or bulk operations:
  • Leverage Flysystem’s copy(), move(), and listContents() for batch operations:

    $files = Storage::disk('sftp')->listContents('reports/');
    foreach ($files as $file) {
        Storage::disk('local')->put($file['path'], Storage::disk('sftp')->read($file['path']));
    }
    

• Error handling:
  • Catch League\Flysystem\FilesystemException and inspect reason() for context (e.g., auth failure, path not found).

Gotchas and Tips

• Critical requirement: The phpseclib/phpseclib package must be installed explicitly—the sub-split doesn’t auto-include it. Miss this, and you’ll get Class 'phpseclib3\Net\SFTP not found` errors.
• Path normalization: SFTP servers use forward slashes, but Windows-style paths may fail. Always use DIRECTORY_SEPARATOR-agnostic paths (e.g., 'reports/' . date('Y') . '/report.pdf').
• Performance tuning:
  • Disable readfile() fallback if streaming large files; use readStream() instead:

    $stream = Storage::disk('sftp')->readStream('large-file.dat');
    readfile($stream['stream']);
    

• Debugging connection issues:
  • Enable phpseclib logging by patching the adapter constructor with a LoggerInterface (though the v3 adapter doesn’t expose logger config directly—extend or decorate if needed).
  • Verify server compatibility: Some SFTP servers (e.g., older ProFTPD) require sftp->exec('pwd') workaround for path resolution.
• Extension point: Override the SftpAdapter to inject custom authentication flow (e.g., dynamic credential rotation from AWS Secrets Manager).