Block Directory: Improve Errors and related experience when installing a block.

[StevenDufresne]

Is your feature request related to a problem? Please describe.
The Block Directory package, in combination with the Plugin API, could provide much better error handling when installing a block.

There are two areas that need improvement:

1. We can improve error messaging
2. We can improve the user experience when errors are thrown

Improving Error Messaging

We currently display error messages that are thrown from the Plugin API. This is awkward because some errors have html included. For example this error is thrown when there is an issue with the PHP version & the block:

<strong>Error:</strong> Current PHP version does not meet minimum requirements for Block Name.

The html is rendered as a string and not proper html.

We should intercept these errors and translate them to be more user friendly.

Options:

• The plugin api, translates error messages
• An intermediate PHP file/api translates error messages
• The Block Directory JS package translates error messages

Improving User Experience

There are 3 different actions we can provide to users:

• Retry: Show error message with retry button
• Reload: Show error message with reload button (which reloads the page)
• Fatal: Show error message with no button

Retry	Reload	Fatal

There are also 3 main error scenarios that can arise during a block's installation:

• HTTP issues
• Issues with installing server-side
• Issues with registering in Gutenberg.

HTTP issues

Retry

• 300/400 level
• 503
• 504

Fatal

• 500 level

Issues with installing server-side

Reload
unable_to_connect_to_filesystem
folder_exists

Fatal
plugin_wp_php_incompatible
plugin_wp_incompatible
plugin_php_incompatible
rest_cannot_manage_plugins
rest_plugin_not_found
rest_cannot_install_plugin
rest_cannot_activate_plugin
unable_to_determine_installed_plugin

I'm sure there are plenty more missing.

Next Steps

1. Agree on an approach for translating error messages
2. Update the Block Directory Package to handle 3 error scenarios and tie them in to the error cases.

[TimothyBJacobs]

Have we considered rendering the error messages as HTML? The plugin incompatibilities would be particularly tricky to implement client side, especially because of the update PHP annotations.

[StevenDufresne]

Have we considered rendering the error messages as HTML? The plugin incompatibilities would be particularly tricky to implement client side, especially because of the update PHP annotations.

Can you offer some examples for more context?

[TimothyBJacobs]

Yep here's an example. Ignore the actual numbers :)

<p>
    <strong>Error:</strong> Current PHP version (7.1.4) does not meet minimum requirements for WooCommerce. The plugin requires PHP 7.0.
</p>
<p>
    <a href="https://wordpress.org/support/update-php/">Learn more about updating PHP</a>.
</p>

It can also be like this if the hosting company provides their own custom page.

<p>
    <strong>Error:</strong> Current PHP version (7.1.4) does not meet minimum requirements for WooCommerce. The plugin requires PHP 7.0.
</p>
<p>
    <a href="https://example.org/my-custom-page">Learn more about updating PHP</a>.
</p>
<p>
    <em>This resource is provided by your web host, and is specific to your site. For more information, <a href="https://wordpress.org/support/update-php/" target="_blank">see the official WordPress documentation</a>.</em></p>

So to make that error message we need their current PHP version and the URLs for updating the PHP version and then have to keep the actual language in sync between WordPress Core and Gutenberg.

The issue from my perspective is that it is common for WordPress error messages to have HTML in them. And I think there are far too many messages, some of which are complex, to natively implement client side. Not to mention a lot of the times a custom error can be returned by plugins, so we couldn't possibly account for them.

[ryelle]

We can use RawHTML in the notice component to render the HTML message returned by the API, but I'm not sure if we need to worry about security issues there.

[TimothyBJacobs]

I'm not sure if we need to worry about security issues there.

I think it should be fine since those errors' HTML would typically be printed as is in the admin currently.

[StevenDufresne]

This is outdated since UI updates were made in #25521. Let's close this ticket and reopen a new one should we need fixes.