Skip to content

Flysystem

Islandora uses Flysystem and the associated Drupal module to persist binary files to Fedora instead of keeping a copy in both Drupal and Fedora.

Background

"Flysystem is a filesystem abstraction library for PHP" which allows applications to read from and write to a variety of data source beyond the local file system, such as an SFTP server, Amazon S3, and Zip files provided an Adapter is available to support it. Flysystem Adapters extend a single class implementing League\Flysystem\FilesystemInterface although some separate adapter traits for common actions and properties, such as the StreamedCopyTrait, are available.

The Drupal Flysystem module extends Flysystem to work within the Drupal filesystem structure. Drupal flysystem plugins include a Flysystem adapter (if not provided by default or in another library) and a class implementing Drupal\flysystem\Plugin\FlysystemPluginInterface which instantiates the Flysystem adapter based on the Drupal site's configuration.

The Drupal Flysystem module uses flysystem stream wrappers to define filesystem descriptors which are configured in the site's settings.php file. The configurations including the filesystem prefix, adapter (driver), and any adapter-specific configurations such as API endpoints and authorization information.

Islandora's Implementation

The Plugin and Adapter

Islandora 8 implements a Flysystem adapter and a Drupal Flysystem plugin. The Flysystem adapter acts as an intermediary between the Flysystem filesystem API and Fedora, translating requests and responses between them. The adapter interacts with Fedora using an instance of the Chullo Fedora API it receives from the Drupal Flysystem plugin. The Drupal Flysystem plugin's main responsibility is to instantiate the Chullo Fedora API object with the proper authentication and pass it to the Flysystem adapter. To authenticate with Fedora the plugin adds a handler to the Chullo's Guzzle client which adds a JWT authentication header to each request.

The Fedora Flysystem adapter does not use Gemini to map the relationship between Drupal URIs and Fedora URIs, so they are indexed separately using the "files_in_fedora" Context which triggers the "Index Fedora File in Gemini" and "Delete Fedora File in Gemini" actions as appropriate.

Configuration

The fedora file system is configured in the site's settings.php file. An example configuration can be seen in the claw-playbook webserver role's drupal tasks:

$settings['flysystem'] = [
  'fedora' => [
    'driver' => 'fedora',
    'config' => [
      'root' => 'http://localhost:8080/fcrepo/rest/',
    ],
  ],
];

The configuration array's top-level key is the name of the Drupal stream wrapper, which also serves as the filesystem prefix. Any Drupal file path using "fedora://" will use this Flysystem adapter. Drupal will translate this prefix to the site's domain plus "_flystem/fedora/". For example, using the default configuration provided by the claw-playbook, a file stored at "fedora://test.tif" will persist to Fedora with the URI "http://localhost:8080/fcrepo/rest/test.tif" and will be accessible from the Drupal URL "http://localhost:8000/_flysystem/fedora/test.tif". The 'driver' value 'fedora' corresponds to the plugin's machine name. The 'config' section contains all the adapter-specific configurations. In this case, the only thing configured for the site is the Fedora REST end-point. (Change this value to match your own Fedora's location, if needed.) The JWT is configured separately.

Other examples of Drupal Flysystem configurations can be seen in the module's README.

Islandora is configured to have all Media use the Fedora file system by default in the islandora_core_feature. For example, the field storage uri_scheme setting for field_media_image (and the other media types) is "fedora". This can also be viewed in the UI on the field's "Field settings" page; e.g. http://localhost:8000/admin/structure/media/manage/image/fields/media.image.field_media_image/storage, look for "Upload destination" and see that "Flysystem: fedora" is selected.

However, there are methods for saving files that can explicitly set a different filesystem than the default. Migrations can explicitly set which file system a file is saved to and Islandora can emit events that also specify which file system a derivative should be saved to.

Derivatives

As hinted in the previous section, Islandora, by default saves derivatives to the Drupal public file system.

For example, if I upload a Tiff to a repository item as a File Media with the term "Original File", the "Image Original File" (image_original_file) Context is triggered. This fires the 'image_generate_a_service_file_from_an_original_file' action which emits an event using the 'public' scheme (file system).

To make Islandora save future derivatives to Fedora instead of to Drupal, change the corresponding action's "File system" setting ('scheme' in the corresponding config file) to 'fedora' instead of 'public'.

Screenshot showing the setting to change for the derivative generation action.