How do I resolve the "Class 'League\Flysystem\Sftp\SftpAdapter' not found" error in Laravel

To resolve this error, follow these detailed steps:

1. Install the Required Package:
Laravel's integration with the SFTP driver relies on the package `league/flysystem-sftp-v3`. You need to explicitly require this package using Composer, as it is not included by default in Laravel's main package.
Run the following command in your terminal at the root of your Laravel project:

composer require league/flysystem-sftp-v3 "^3.0"

This installs the version 3 compatible SFTP adapter which provides the `SftpAdapter` class under the namespace `League\Flysystem\PhpseclibV3\SftpAdapter`.

2. Configure SFTP Disk in Laravel:
You need to configure a disk for SFTP in Laravel's `config/filesystems.php`. Add an SFTP disk configuration inside the 'disks' array like this:

php
'sftp' => [
    'driver' => 'sftp',
    'host' => env('SFTP_HOST'),
    'username' => env('SFTP_USERNAME'),
    'password' => env('SFTP_PASSWORD'), // or use 'privateKey' and 'passphrase' if using SSH keys
    'privateKey' => env('SFTP_PRIVATE_KEY'), // path to private key file (optional)
    'passphrase' => env('SFTP_PASSPHRASE'), // private key passphrase (optional)
    'port' => env('SFTP_PORT', 22),
    'root' => env('SFTP_ROOT', ''), // optional root directory path on server
    'timeout' => 30,
],

Note: You can authenticate either via username/password or SSH private key, depending on your SFTP server setup.

3. Set Environment Variables:
Add the corresponding environment variables to your `.env` file with the actual connection details:

SFTP_HOST=your-sftp-host.com
SFTP_USERNAME=your-username
SFTP_PASSWORD=your-password
SFTP_PRIVATE_KEY=/path/to/private/key
SFTP_PASSPHRASE=your-passphrase
SFTP_PORT=22
SFTP_ROOT=/remote/path

Include only the relevant ones depending on the authentication method.

4. Clear Configuration Cache:
Laravel caches the configuration files for performance. After updating config or `.env` files, clear the cache to ensure changes take effect:

php artisan config:clear

5. Usage in Laravel Application:
You can use the SFTP disk as follows:

php
use Illuminate\Support\Facades\Storage;

// List all files in the root directory on SFTP
$files = Storage::disk('sftp')->allFiles('/');

// Read the contents of a file
$contents = Storage::disk('sftp')->get('path/to/file.txt');

// Write a file to the SFTP disk
Storage::disk('sftp')->put('path/to/newfile.txt', 'File content here');

// Delete a file from the SFTP disk
Storage::disk('sftp')->delete('path/to/file.txt');

6. Ensure PHP Extensions Are Installed:
The `league/flysystem-sftp-v3` package depends on `phpseclib/phpseclib` for SSH connections. It uses pure PHP library but ensure you have the OpenSSL PHP extension enabled since SSH key encryption might require it.

7. Check Laravel Version Compatibility:
The SFTP driver integration in Laravel has improved since version 5.6. Ensure you are using a Laravel version that supports the newer Flysystem v3 packages or adjust usage for older versions by following legacy documentation.

8. Troubleshooting Missing Classes:
If after installing `league/flysystem-sftp-v3` the error persists, verify the following:

- Run `composer dump-autoload` to regenerate the Composer autoload files.
- Check that your `vendor/league/flysystem-sftp-v3` directory exists and contains the source files.
- Verify `composer.json` has the `league/flysystem-sftp-v3` listed under the "require" section.
- Double-check the namespace and class name in your code match the installed package; the correct class is `League\Flysystem\PhpseclibV3\SftpAdapter` (note the PhpseclibV3 namespace in v3 of the adapter).
- Investigate if any conflicting older Flysystem SFTP packages are installed and remove them.

9. Update and Lock Dependencies Properly:
Sometimes dependency conflicts prevent the correct package version installation. Run:

composer update league/flysystem-sftp-v3

Ensure no composer errors or warnings show up. If problems arise, consider deleting `vendor/` directory and `composer.lock` file and reinstalling completely with:

composer install

10. Custom SFTP Adapter Usage:
In certain Laravel versions or specific use cases, you may need to manually instantiate the SFTP adapter using Phpseclib classes:

php
use League\Flysystem\Filesystem;
use League\Flysystem\PhpseclibV3\SftpAdapter;
use League\Flysystem\PhpseclibV3\SftpConnectionProvider;

$connectionProvider = new SftpConnectionProvider(
    'host',
    'username',
    'password',
    '/path/to/private/key',
    'passphrase',
    22,
    false,
    30,
    10,
    'host-key-fingerprint'
);

$adapter = new SftpAdapter($connectionProvider, '/remote/root');

$filesystem = new Filesystem($adapter);

// Use $filesystem for file operations

This approach gives full control over the SFTP connection but requires the `league/flysystem-sftp-v3` package.

11. Avoid Using Deprecated or Unsupported Packages:
Do not use the older `league/flysystem-sftp` (v1 or v2) with Laravel versions expecting v3 unless deliberately managing legacy code. The error often stems from missing `SftpAdapter` because Laravel expects the Flysystem v3 package structure.

12. Check Permissions and SSH Access:
Even with correct packages, connection failures may arise due to SSH key permissions, server firewall rules, wrong usernames, or incorrect root paths. Validate credentials independently with an SSH client or command-line SFTP client.

13. Confirm Service Provider Loading:
Laravel's filesystem uses `Illuminate\Filesystem\FilesystemServiceProvider` which registers necessary adapters based on installed packages. Make sure your Laravel installation is complete and not missing core service providers.

14. Use Laravel Filesystem Documentation:
Refer to the official Laravel filesystem docs for usage examples and troubleshooting the SFTP driver:
https://laravel.com/docs/filesystem#sftp-driver

15. Clear Cache and Restart:
After all changes, clear various caches as needed:

php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

Restart your web server or queue workers in case they cache old config or autoloaded classes.

16. Additional Debugging:
If the error persists, enable Laravel debug mode (`APP_DEBUG=true` in `.env`) and check the logs in `storage/logs/laravel.log` for stack traces or missing class details.

Check your autoload files include the League Flysystem namespaces by searching the `vendor/composer/autoload_psr4.php` file for `League\Flysystem`.

17. Community and GitHub Issues:
Check the Flysystem GitHub issues for similar errors and fixes:
- https://github.com/thephpleague/flysystem/issues
- https://github.com/barryvdh/laravel-elfinder/issues/297 (example issue related to SFTP adapter not found)

Various threads discuss the requirement to explicitly add `league/flysystem-sftp-v3` and correctly configure disks.

18. Example Full Configuration and Use:
`config/filesystems.php` excerpt:

php
'disks' => [
    'sftp' => [
        'driver' => 'sftp',
        'host' => env('SFTP_HOST'),
        'username' => env('SFTP_USERNAME'),
        'password' => env('SFTP_PASSWORD'),
        'privateKey' => env('SFTP_PRIVATE_KEY'),
        'passphrase' => env('SFTP_PASSPHRASE'),
        'port' => env('SFTP_PORT', 22),
        'root' => env('SFTP_ROOT', ''),
        'timeout' => 30,
    ],
],

`.env` example:

SFTP_HOST=sftp.example.com
SFTP_USERNAME=user
SFTP_PASSWORD=secret
SFTP_PRIVATE_KEY=/home/user/.ssh/id_rsa
SFTP_PASSPHRASE=
SFTP_PORT=22
SFTP_ROOT=/path/on/server

Then use in Laravel:

php
$files = Storage::disk('sftp')->allFiles('/');

If errors about classes continue, verify package installation and autoload.