[4.x] Multilingual support for error renderers

[adriansuter]

Of course, Slim should stay slim - but I was wondering if it would make sense to add some sort of multilingual support for the following error renderers?

• \Slim\Error\Renderers\HtmlErrorRenderer
• \Slim\Error\Renderers\PlainTextErrorRenderer

They define some texts (hard-coded in the source code) like the title Slim Application Error or The application could not run because of the following error or A website error has occurred. Sorry for the temporary inconvenience and so on.

Or should that be left to the user? So he/she has to write a custom error handler. I mean, the user might even decide to use Twig or any other templating engine to do the rendering.

Notice 1:
The XML and JSON error renderers do not contain texts that should be translatable.

Notice 2:
The error messages itselves (at least the php error messages) would still be in english, of course. But in production, these error messages should not be shown ($displayErrorDetails = false) anyway.

[l0gicgate]

I think we need to refactor those two renderers and give the ability to change those hard coded messages. I have not yet thought about how to do it in a way that makes it easy for the end user to customize these. Definitely open to suggestions on how we could implement this.

This is why I haven't merged #2717 yet. I'm trying to think of a better way to do this.

[Brammm]

Just thinking out loud here: wouldn't it be easier to put the HTML and strings etc in some kind of template file (just straight up PHP, not using a library) and make those easily replaceable?

The easiest would be to make it configurable, but I see version 4 has just done away with the configuration, so not sure what the best solution would be. Haven't delved too much in the internals of v4.

[l0gicgate]

I think the best way to do this is to include a setter for the renderer on the ErrorHandler component that we ship so you don't have to extend it to change the rendering.

https://github.com/slimphp/Slim/blob/4.x/Slim/Handlers/ErrorHandler.php#L85

This solution works for both the 3.x and 4.x branch. That way the end user can easily create their own renderer and set it on the error handler.

[adriansuter]

The problem is, that we would not know, what renderer we need to set, until the ErrorHandler gets invoked. Currently that would be decided in the method

Slim/Slim/Handlers/ErrorHandler.php

Line 204 in ccefb2f

protected function determineRenderer(): ErrorRendererInterface

Idea 1

Probably we could add something like an ErrorRendererDeterminer (or ErrorRendererFactory) to the ErrorHandler which, if set, gets called instead of the whole if condition below

Slim/Slim/Handlers/ErrorHandler.php

Lines 220 to 240 in ccefb2f

	if ($renderer === null) {
	switch ($this->contentType) {
	case 'application/json':
	$renderer = JsonErrorRenderer::class;
	break;
	case 'text/xml':
	case 'application/xml':
	$renderer = XmlErrorRenderer::class;
	break;
	case 'text/plain':
	$renderer = PlainTextErrorRenderer::class;
	break;
	default:
	case 'text/html':
	$renderer = HtmlErrorRenderer::class;
	break;
	}
	}

The ErrorHandler would then pass the content type to the "determiner" which eventually returns an ErrorRendererInterface. So the user can implement a custom error renderer determiner, which might return a custom error renderer (based of content types).

That way, it would even be possible, that the user injects a template engine into the custom error renderer determiner which could then be injected to the custom error renderer.

Or is this too complicated?

Idea 2

We could also define something like an ErrorRendererProvider which holds an array of known error renderers, where the keys are the content types.

$errorRenderers = [
    'application/json' => JsonErrorRenderer::class,
    'text/xml' => XmlErrorRenderer::class,
    'application/xml' => XmlErrorRenderer::class,
    // ...
];

So the user could add/set custom error renderers. But how do we get the Container into the renderer, in case the user would like to use a template engine?

[l0gicgate]

If the $renderer is set (default is null) in ErrorHandler, it will bypass the determination process as seen here

Slim/Slim/Handlers/ErrorHandler.php

Line 220 in ccefb2f

if ($renderer === null) {

This was so a user can extend ErrorHandler and override that property. But a setter would be much easier in this case.

We will also need to revisit the instantiation logic of that renderer. Right now there’s an assumption that it will be a classname only.

I don’t think we need to offer the flexibility of setting multiple different renderers. Would someone serve different content types and expect multiple different types of error handling based on the content type in one app? Seems unlikely. I’m not opposed to adding it, I don’t think it’s necessary though.

[adriansuter]

Once I wrote a simple app, that mostly served html, but used some ajax requests to load json data. So it is possible to have an app with multiple content types.

Maybe we could write a middleware that sets the error renderer (depending on the content type). The problem with this: If the renderer is instantiated already here, every request would create that object - even if not used, which should be the case for most requests. If the renderer is a string, class name, then we would not be able to access the container inside the renderer. But then we can't use services like a template engine.

[adriansuter]

Idea 2 (continued)

I added the following to the \Slim\Handlers\ErrorHandler

    protected $renderers = [
        '_default' => HtmlErrorRenderer::class,
        'application/json' => JsonErrorRenderer::class,
        'text/xml' => XmlErrorRenderer::class,
        'application/xml' => XmlErrorRenderer::class,
        'text/plain' => PlainTextErrorRenderer::class,
        'text/html' => HtmlErrorRenderer::class,
    ];

    public function setErrorRenderer(string $type, string $renderer): void
    {
        $this->renderers[$type] = $renderer;
    }

and replaced the whole switch block

Slim/Slim/Handlers/ErrorHandler.php

Line 221 in ccefb2f

switch ($this->contentType) {

with

            if (array_key_exists($this->contentType, $this->renderers)) {
                $renderer = $this->renderers[$this->contentType];
            } else {
                $renderer = $this->renderers['_default'];
            }

So the default error handler would search the error renderer in this array.

With this modifications, a user would be able to create a custom error renderer class

class MyCustomHtmlErrorRenderer implements ErrorRendererInterface
{
    /**
     * {@inheritdoc}
     */
    public function render(Throwable $exception, bool $displayErrorDetails): string
    {
        return 'Custom Error Renderer';
    }
}

and then in the index.php the user can register that error renderer to be used in case of a specific content type

// $errorMiddleware is a \Slim\Middleware\ErrorMiddleware instantiated
// before and added to the app.
$errorHandler = $errorMiddleware->getDefaultErrorHandler();
$errorHandler->setErrorRenderer('text/html', MyCustomHtmlErrorRenderer::class);
$errorMiddleware->setDefaultErrorHandler($errorHandler);

What's your opinion? How do we get the container into the renderer (in case the user wants to use a template engine, or in case the renderer needs to know/access other information like the current language (multilingual apps)?

[l0gicgate]

I think that's a great approach. If you want to PR that let's go ahead with it! The only thing is we'll need to figure out a way to add more customization on the Slim 3 branch where the error handling is entirely different than Slim 4.