[9.x] Optionally cascade thrown Flysystem exceptions

[driesvints]

This PR gives the ability to optionally cascade thrown Flysystem exceptions with a throws_exceptions config option.

There's a concern with this: operations like the delete method will hard-fail now when passing multiple paths. Any paths that haven't been reached yet won't be deleted yet. Not sure if this is something we should work around?

This PR is opt-in and non-breaking.

Related: #41269

[driesvints]

I couldn't get this test to work on Windows but I'd assume it's related to how I'm creating the directory so I expect exceptions throwing works fine on it 😅

[Jubeki]

May have something todo with the different directory separator:
Linux/MacOS: /
Windows: \

Maybe use: DIRECTORY_SEPARATOR

EDIT:
Reference: https://www.php.net/manual/en/dir.constants.php

[driesvints]

I tried that but it didn't work.

[Jubeki]

Yeah seems like windows ignores the permissions which are set by mkdir: https://www.php.net/manual/en/function.mkdir.php

[derekmd]

You could create a 400 permission read-only file and attempt to overwrite it. I verified this passes on Windows 10:

public function testThrowExceptionsForPut()
{
    $this->filesystem->write('foo.txt', 'Hello World');

    chmod(__DIR__.'/tmp/foo.txt', 0400);

    $adapter = new FilesystemAdapter($this->filesystem, $this->adapter, ['throws_exceptions' => true]);

    try {
        $adapter->put('foo.txt', 'Hello World!');

        $this->fail('UnableToWriteFile exception was not thrown.');
    } catch (UnableToWriteFile $e) {
        $this->assertTrue(true);
    } finally {
        chmod(__DIR__.'/tmp/foo.txt', 0600);
    }
}

It needs chmod(__DIR__.'/tmp/foo.txt', 0600) before the tearDown() deletion of ./tmp which will fail if the subdirectory contains a read-only file.

[driesvints]

@derekmd that didn't seem to work so I'm reverting that. Keeping tests on Linux/macOS for now.

[derekmd]

I think it failed because the wip commit used old config key throws_exceptions after Taylor renamed it to throw.

[driesvints]

ah could be yeah. Gonna leave it now myself but would appreciate a PR if anyone wants to.

[ankurk91]

@driesvints

Thanks for the PR. 😍

Please guide us where to specify the config option throws_exceptions in config/filesystem.php, an example would be helpful.

[driesvints]

@ankurk91 no problem. You'd add this to any disk's config array:

'disks' => [
    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
        'throws_exceptions' => true,
    ],
],

[taylorotwell]

Renamed this config option to just throw. 👍

[browner12]

is there a way to conditionally @throw an exception in the docblock? otherwise the IDE gets confused why we're trying to catch an exception it doesn't think is being thrown.

[driesvints]

@browner12 don't think so no