The current documentation is clearly inadequate. It has not been updated for four years.
I wish I could update it on https://git.drupalcode.org, but I'm not allowed to neither edit nor fork over there.
So here's an error ridden, but hopefully useful, stab at some better documentation:
1. The Flysystem module page links to
http://cgit.drupalcode.org/flysystem/plain/README.md?h=8.x-1.x
This page look pretty ugly in a browser. Link to
https://git.drupalcode.org/project/flysystem/-/blob/2.0.x/README.md?ref_...
or some such instead.
Better yet. Include most of the documentation (100+ lines?) on the module page. It's a great place for documentation! People will probably be more likely to install it, if they get the full picture up front.
2. "Reducing technical debt and risk of vendor lock-in." is slightly better than the current "Reducing technical debt and chance of vendor lock-in."
3. Requirements and Installation boilerplate should be removed. This is definitely not the first module a novice Drupal user will choose to install. Spend your time on the important details.
4. "Stream wrappers are configured in settings.php (usually found in /sites/default/settings.php or /web/sites/default/settings.php".
There are two settings.php in a typical D10 installation (the other one is at /core/lib/Drupal/Core/Site). And nearly 20 *settings.php files. We'd hate to confuse people.
5. Troubleshooting. Fine. But place it after the Configuration bit, where people need it.
6. Configuration. The example does not work.
This example will work
$schemes = [
'local-example' => [ // The name of the stream wrapper.
'driver' => 'local', // The plugin key.
'config' => [
'root' => '/../../', // Path to directory outside Drupal. Maybe /var/www/html/storage or ../ works better, who knows? 'sites/default/files/flysystem' would be a part of the public file system.
'public' => TRUE, // In order for the public setting to work,
// the path must be relative to the root
// of the Drupal install.
// Optional settings that apply to all adapters.
'name' => 'local-example', // Optional. Defaults to something secret.
'description' => 'An example of a local flyssystem file system', // // Optional. Defaults to something secret.
'cache' => TRUE, // Cache filesystem metadata. Not necessary for
// the local driver.
'replicate' => 'ftp-example', // 'replicate' writes to both filesystems, but
// reads from this one. Functions as a backup.
'serve_js' => TRUE, // Serve Javascript or CSS via this stream wrapper.
'serve_css' => TRUE, // This is useful for adapters that function as
// CDNs like the S3 adapter.
],
],
'ftp-example' => [
'driver' => 'ftp',
'config' => [
'host' => 'ftp.storaro.it', // or whatever the name of your ftp host is
'username' => 'storaro', // use a better username
'password' => 'cin3matograph3r', // use a better password
// Optional config settings.
'port' => 21,
'root' => '/var/www/html/storage',
'passive' => true,
'ssl' => false,
'timeout' => 90,
'permPrivate' => 0700,
'permPublic' => 0700,
'transferMode' => FTP_BINARY,
],
],
];
// Don't forget this!
$settings['flysystem'] = $schemes;
6) Troubleshooting. Have a look at the status report (admin/reports/status) to see if it works.
And on the status page, you should never write "ftp returned an error". That's close to useless. What error did it return? Should the user have a closer look at the hostname, port, username or password?
7) How to use the module.
"Now whenever you add a NEW file field to a node type/entiity type, you can decide which file system to use for the field. You cannot change the file system for existing fields, though. Only new fields get the benefit of the Flysystem module."