Implement a Result type in Drupal Core

Added a merge request to show the proposed implementation. However this "Needs Work" because we can't quite tell PHPStan what we want to do :)

However, this allows async issues to start using the type and demonstrate its usefulness.

I've asked for some help in the PHPStan discussions on GitHub and Ondrej was very kind in providing more insights: https://github.com/phpstan/phpstan/discussions/10667. It turns out I was running into a known issue https://github.com/phpstan/phpstan/issues/6732.

I've now pushed a workaround using a type annotation :)

The Needs Review Queue Bot → tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide → to find step-by-step guides for working with issues.

This was failing on some coding standards (parts of which is PHPCS not yet understanding more complex PHPStan types). These were fixed in a commit amend.

I missed Catch's feedback on the missing bool return types for isOk/isError which I've now added :D

It looks straightforward so not sure a test needed.

But it needs CR with example of use to announce it to module developers and maybe follow-up to apply monadic result to some core places

I wasn’t quite sure how to test it. I suppose we could test that the isOk and isError types do what they say.

What I’ve previously done is write a few function calls around it with PHPStan at level 9 to make sure all the type annotations had the right behavior. We don’t really have infrastructure for that though and that should be solidified when we adopt it :)

See the linked PHPStan sandbox for that bit of code

I’ll write a CR proposal in the coming days unless someone is faster

I've applied the suggested changes to the documentation and removed the sentence about the list example, instead showing it as code which I hope helps it more easily click with developers.

Nice!

Shouldn't we have test coverage though to make sure this does what is expected?