IBX-1439: Upgraded codebase to rely on Flysystem v2

[alongosz]

Question	Answer
JIRA issue	IBX-1439
Type	feature
Target Ibexa version	v4.4
BC breaks	yes

This PR upgrades codebase to rely on Flysystem v2. We can't upgrade to the newest Flysystem v3 because of the hard requirement on PHP 8.

One of the most significant changes is the fact that Adapters were completely rewritten, requiring us to make significant changes to the code.

Our Flysystem Adapter implementation must support dynamic paths described by complex settings resolvable for the SiteAccess context. By default Local io.root_dir is defined as %webroot_dir%/$var_dir$/$storage_dir$ where var_dir and storage_dir are SiteAccess configuration parameters. Next to it there's the DFS (NFS) implementation which has one minor difference - web root is custom and static, defined via DFS_NFS_PATH environment variable. It could either be local path or a NFS mount which is transparently seen also as a local filesystem on all *nixes.

Per suggestion of Flysystem's Maintainer, Introducing DynamicPathFilesystemAdapterDecorator, proxying all calls to inner native Flysystem Local Adapter, after applying our dynamic path prefix using custom SiteAccess-aware PathPrefixer.
Additionaly to PathPrefixer, implementations of VisibilityConverter are provided, following Flysystem v2 \League\Flysystem\UnixVisibility\VisibilityConverter contracts. These resolve created file and directory permissions.

PathPrefixer has 2 implementations: LocalSiteAccessAwarePathPrefixer and DFSSiteAccessAwarePathPrefixer.
VisibilityConverter has 2 implementations: DFSVisibilityConverter and SiteAccessAwareVisibilityConverter. Please note that DFS doesn't include SiteAccessAware part in its name on purpose - DFS file/directory permissions are taken from ibexa.io.nfs.adapter.config Container parameters and are not dynamic.

The structure of the implementation could be presented on the following diagram:

classDiagram
direction BT
class FilesystemAdapter
class DynamicPathFilesystemAdapterDecorator
class PathPrefixerInterface
class BaseSiteAccessAwarePathPrefixer
class DFSSiteAccessAwarePathPrefixer
class BaseVisibilityConverter
class DFSVisibilityConverter
class VisibilityConverter


BaseSiteAccessAwarePathPrefixer  ..>  PathPrefixerInterface
DFSSiteAccessAwarePathPrefixer  -->  BaseSiteAccessAwarePathPrefixer  
LocalSiteAccessAwarePathPrefixer  -->  BaseSiteAccessAwarePathPrefixer

BaseVisibilityConverter  ..>  VisibilityConverter
DFSVisibilityConverter  -->  BaseVisibilityConverter
SiteAccessAwareVisibilityConverter  -->  BaseVisibilityConverter

DynamicPathFilesystemAdapterDecorator  ..>  FilesystemAdapter
DynamicPathFilesystemAdapterDecorator *-- FilesystemAdapter
DynamicPathFilesystemAdapterDecorator *-- PathPrefixerInterface
FilesystemAdapter *-- BaseVisibilityConverter

Loading

Features no longer supported

1. Support for overwriting existing files has been dropped (catch block of \Ibexa\Core\IO\IOBinarydataHandler\Flysystem::create + test) as now native Flysystem Local Adapter does this OOTB.
2. Support (in the form of test case) for no last modified timestamp (allegedly unset by AWS/S3 handler in the past) has been dropped as right now Flysystem throws UnableToRetrieveMetadata exception in such case.

Documentation

Upgrade instruction

Local adapters' (by default defined in config/packages/oneup_flysystem.yaml) directory key becomes location

E.g.:

Before

oneup_flysystem:
     adapters:
         default_adapter:
             local:
                directory: '%kernel.cache_dir%/flysystem'

After

oneup_flysystem:
    adapters:
        default_adapter:
            local:
                location: '%kernel.cache_dir%/flysystem'

If you haven't touched these files, you can simply reset 3rd party oneup/flysystem-bundle recipe by executing:

composer recipe:install --force --reset -- oneup/flysystem-bundle

Backward compatibility breaks

Requiring higher major version in a minor release is a necessary BC break. We are forced to do that because it seems 1.x is no longer maintained and moreover 3rd party adapters rely higher Flysystem version.
If a custom project relies directly on Flysystem features instead of using our IO abstraction, it will require an upgrade as well, using the following instructions: https://flysystem.thephpleague.com/docs/upgrade-from-1.x/

Other docs

Page https://doc.ibexa.co/en/latest/infrastructure_and_maintenance/clustering/clustering_with_aws_s3/#set-up-aws-s3-account
needs to be updated:

composer require league/flysystem-aws-s3-v3:^2.0

QA

Affected scopes / features:

• NFS / DFS adapters
• IBX-3740 regarding DFS_NFS_PATH configuration
• Multirepository storage var_dir for files, images, etc - when directory is different per Repository's SiteAccesses
• Content preview which emits \Ibexa\Core\MVC\Symfony\Event\ScopeChangeEvent affecting path prefixes as well
• CLI: Symfony command using --siteaccess option.
• CLI: Symfony command ibexa:images:normalize-paths
• Local adapters now by default should overwrite existing files - our support for that has been dropped, delegating it to Flysystem
• Platform.Sh NFS & local (or do we use NFS-only there?) binary files operations.

Tasks

• Bump Flysystem dependencies to rely on Flysystem 2.x
• Upgrade codebase to use Flysystem 2.x
• Investigate OneUp/FlysystemBundle requirements
• Confirm that Flysystem v2 by default overwrites existing file
• Fix failing tests
• Upgrade other packages with root dependencies on Flysystem or OneUp Flysystem Bundle
• Upgrade other packages with dev dependency on Flysystem Memory adapter

Checklist:

• Provided PR description.
• Tested the solution manually.
• Provided automated test coverage.
• Checked that target branch is set correctly.
• Ran PHP CS Fixer for new PHP code (use $ composer fix-cs).
• Asked for a review.

[konradoboza]

Yet I think, that at least a question (as contribution probably would require too much work) to Flysystem should be sent anyway (if not the case already) to avoid maintaining overridden code.

[alongosz]

Update: b280ad8 fixed outstanding legacy test parameter values for storage root dir.

[alongosz]

Moving this to draft state as part of the solution needs to be changed according to the feedback in thephpleague/flysystem#1614

[webhdx]

I rebased it against main so we can run regression tests again.

[tomaszszopinski]

QA approved on IbexaDXP commerce 4.4.x.