Improve user experience when downloading archives

[salmart-dev]

• Resolves: [Enhancement] ZipFolderPlugin fails silently on errors #58825

Took over some of the changes from #57335, thanks @Koc

Summary

This PR adds an alternative working mode to the ZipFolderPlugin.

By setting the new archive_report_missing_files to true (default true) in config.php administrators can allow users to download partial archives when those contain a file that is blocked or missing/corrupted files.

The users will be informed of this via the addition of a missing_files.json inside the archive itself, giving the user some minimal information about why the files are missing.

Why is this needed

The ZipFolderPlugin currently halts the streaming of an archive for download due to various factors, such as storage issues with a file, temporary database problems, or a lost network connection. Because the plugin streams without a content-length header, the user receives an incomplete archive without any warning. In some cases, this issue only becomes apparent when attempting to open a file in the archive and discovering that the entire archive is corrupted.

What changes

Behaviour	Before	After
Downloading a directory containing a blocked file	Whole download denied	Download possible with missing_files.json containing an entry for the blocked file
Downloading a directory with an unstable file backend	Corrupted archive	Valid archive with partial files and entry in missing_files.json reporting the issue
Downloading a directory with files that cannot be opened because of X	Corrupted archive	Valid archive with missing file and entry in missing_files.json reporting the reason

Note: this will need to be backported down to stable29

TODO

• Write tests
• Translations
• Update documentation where needed
• May need a patch to deepdiver/zipstreamer to avoid slow tests due to loss of precision

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)
• Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
• Milestone added for target branch/version (ex: 32.x for stable32)

AI (if applicable)

• The content of this PR was partly or fully generated using AI

[susnux]

so only admin configured, no user option if first failed?

[salmart-dev]

so only admin configured, no user option if first failed?

We could add this option later, right? We need this to work on 29 too 🙈

[icewind1991]

It might make the code clearer if the error reporting code in the inner logic was always active, and only have the outer logic conditionally throw/abort or generate the error report.

[icewind1991]

The overall logic looks good

[joshtrichards]

Embedding missing_files.json is a meaningful improvement over silently producing corrupted/incomplete archives (never good).

• The UX concern that a “successful” download (archive) with missing files is still too easy to misunderstand/overlook remains. missing_files.json is better than nothing, but many users will not inspect it. I don't have a good answer here.
• The opt-in flag seems like a good idea, but less certain upon reflection. If we need a toggle for straightforward (from the end-user perspective) functionality like this it may be a sign the implementation and design still needs further refinement before we commit (or, alternatively,we should drop the flag and accept it as the new default behavior!)
• Admittedly, sometimes the best we can do is improve the UX until the next "go around". ;-)

For cases known ahead of time (e.g. filtered/blocked files), it may still be worth considering an additional visible signal that the archive is incomplete.

[salmart-dev]

It might make the code clearer if the error reporting code in the inner logic was always active, and only have the outer logic conditionally throw/abort or generate the error report.

Makes sense: I removed all ifs inside the inner logic and just returning a reason in case of failure. Then the outer code decides what to do.

[salmart-dev]

@joshtrichards we decided to turn the flag into being default true, so this will be default behaviour 🎉