Add deprecation messages in FlysystemAssetStore

[emteknetnz]

This is currently blocking #522

There are a bunch of @deprecated 1.4.0 phpdoc's on methods in FlysystemAssetStore

As part of silverstripe/silverstripe-framework#10531, we need to add standardized message to all phpdocs. i.e.

* @deprecated 1.4.0 My message

Use either of the following standardized messages:

• Use <methodname>() instead
• Will be removed without equivalent functionality to replace it

Acceptance criteria

• All @deprecated phpdoc's in FlystemAssetStore with missing messages have message added

Pull request

• FIX Handle calling Deprecation::notice() before manifests are available silverstripe-framework#10556
• Deprecate a bunch of legacy file method and tasks #525
• DOC Newly supported and deprecated assets API developer-docs#107

[maxime-rainville]

What's been deprecated, why and what the alternative is (if any)

Legacy filename

Prior to the 4.4 release, there was something called legacy filename that would allow you to output filename without the hash. That was completely busted and become redundant once we enable NaturalFileIDs. We kept some of the methods around because they were part of the API but they effectively do nothing now.

These should be deprecated and throw warning from now on.

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 88 in ce9464b

private static $legacy_filenames = false;

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Lines 1226 to 1229 in ce9464b

	protected function useLegacyFilenames()
	{
	return $this->config()->get('legacy_filenames');
	}

Methods that became part of the FileID helpers

Asset Store used to be very directive because it would assume that all the files would be contained hashes. Those methods were moved to file ID helpers. But some hackish implementation were kept on the asset store ... because SEMVER.

These methods should throw warnings now and be removed altogether.

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 262 in ce9464b

protected function getFilesystemFor($fileID)

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 708 in ce9464b

protected function deleteFromFilesystem($fileID, Filesystem $filesystem)

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 914 in ce9464b

protected function moveBetweenFilesystems($fileID, Filesystem $from, Filesystem $to)

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 1061 in ce9464b

protected function getStreamSHA1($stream)

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 1353 in ce9464b

protected function cleanFilename($filename)

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 1367 in ce9464b

protected function parseFileID($fileID)

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 1381 in ce9464b

protected function getOriginalFilename($fileID)

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 1394 in ce9464b

protected function getVariant($fileID)

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 1407 in ce9464b

protected function removeVariant($fileID)

This method is not currently marked as deprecated, but should be.

silverstripe-assets/src/Flysystem/FlysystemAssetStore.php

Line 772 in ce9464b

protected function findVariants($fileID, Filesystem $filesystem)

Task that need to be removed

These task are no longer needed and should be deprecated/removed

• FixFolderPermissionsHelper.php
• VersionedFilesMigrator.php
• FileMigrationHelper.php
• FolderMigrationHelper.php
• LegacyThumbnailMigrationHelper.php
• NormaliseAccessMigrationHelper.php
• SecureAssetsMigrationHelper.php
• TagsToShortcodeHelper.php
• TagsToShortcodeTask.php
• VersionedFilesMigrationTask.php

Legacy File resolution

To be able to migrate and resolve SS3 file URLs, we had to create a lot of of legacy abstraction (aka replicating the SS3 file resolution logic in SS4).

That legacy logic is no longer needed.

This class should be deprecated: LegacyFileIDHelper.php

This bit of config can be simplified in CMS5:

• FileResolutionStrategy.public should only use NaturalFileIDHelper
• FileResolutionStrategy.protected should only use HashFileIDHelper

This will however mean that everyone who wants to upgrade to CMS5 and had a site created prior to CMS4.4 will have to had run the FileMigrationHelper at some point.

silverstripe-assets/_config/asset.yml

Lines 26 to 43 in ce9464b

	SilverStripe\Assets\FilenameParsing\FileResolutionStrategy.public:
	class: SilverStripe\Assets\FilenameParsing\FileIDHelperResolutionStrategy
	properties:
	ResolutionFileIDHelpers:
	- '%$SilverStripe\Assets\FilenameParsing\HashFileIDHelper'
	- '%$SilverStripe\Assets\FilenameParsing\NaturalFileIDHelper'
	- '%$SilverStripe\Assets\FilenameParsing\LegacyFileIDHelper'
	DefaultFileIDHelper: '%$SilverStripe\Assets\FilenameParsing\NaturalFileIDHelper'
	VersionedStage: Live
	# Define protected resolution strategy
	SilverStripe\Assets\FilenameParsing\FileResolutionStrategy.protected:
	class: SilverStripe\Assets\FilenameParsing\FileIDHelperResolutionStrategy
	properties:
	DefaultFileIDHelper: '%$SilverStripe\Assets\FilenameParsing\HashFileIDHelper'
	ResolutionFileIDHelpers:
	- '%$SilverStripe\Assets\FilenameParsing\HashFileIDHelper'
	- '%$SilverStripe\Assets\FilenameParsing\NaturalFileIDHelper'
	VersionedStage: Stage

Scope creep to annoy @emteknetnz

In CMS4.4, I introduced ParsedFileID. Until then, we would use tuple which were essentially arrays with a filename, hash and variant keys.

ParsedFileID contains all of that, but in a class with types for everything. We should replace any reference to tuple with a ParsedFileID.

Even more scope creep

Flysystem's Filesystem object implements the FilesystemOperator. I think everywhere we expect a Filesystem we could just as easily expect a FilesystemOperator.

This would open some possibilities for some people #368

[maxime-rainville]

This PR will handle the deprecations: #525

I'll spin up my other side concerns into their own card.

[GuySartorelli]

@max please create a PR for the 4.12.0 changelog for the things that are being newly deprecated.

[GuySartorelli]

This is all done