Allow to define JSON encoding options in Eloquent API Resources

[Gummibeer]

PHP supports several options on how to encode JSON - some of the most important ones for APIs could be JSON_PRESERVE_ZERO_FRACTION or JSON_UNESCAPED_UNICODE. But it's not possible to pass these options to the JSON encoding point from within an Eloquent API Resource.

\Illuminate\Http\Resources\Json\JsonResource::toResponse()

framework/src/Illuminate/Http/Resources/Json/JsonResource.php

Lines 214 to 223 in 6e9baa0

	/**
	* Create an HTTP response that represents the object.
	*
	* @param \Illuminate\Http\Request $request
	* @return \Illuminate\Http\JsonResponse
	*/
	public function toResponse($request)
	{
	return (new ResourceResponse($this))->toResponse($request);
	}

\Illuminate\Http\Resources\Json\ResourceResponse::toResponse()

framework/src/Illuminate/Http/Resources/Json/ResourceResponse.php

Lines 29 to 49 in 6e9baa0

	/**
	* Create an HTTP response that represents the object.
	*
	* @param \Illuminate\Http\Request $request
	* @return \Illuminate\Http\JsonResponse
	*/
	public function toResponse($request)
	{
	return tap(response()->json(
	$this->wrap(
	$this->resource->resolve($request),
	$this->resource->with($request),
	$this->resource->additional
	),
	$this->calculateStatus()
	), function ($response) use ($request) {
	$response->original = $this->resource->resource;
	$this->resource->withResponse($request, $response);
	});
	}

Idea 1 - new method to define options
The idea to solve this would be a new (optional) method jsonEncodingOptions() on the resource class itself which is used in the ResourceResponse class and passed to the response()->json() method as you would do in your own controller.
The downside of that would be that one resource can contain another resource and they could define different options but only the top one used to generate the response would be respected. This could produce unexpected behavior for the users if not properly communicated.

Idea 2 - resolve ResourceResponse via container
My second idea would be to resolve the ResourceResponse class via the container in the JsonResource class which would allow the user to override and rebind that single class. Would define one set of options for the whole application and doesn't require the user to override and extend classes only to be able to add custom behavior to one single method.

---

In theory that is also a bigger "problem" as it could also be helpful to define application-wide encoding options used by default instead of 0 everywhere. So something like a config('app.json_encoding_options', 0). Which is used by every class that implements some kind of toJson() method.
As the default wouldn't change none of these changes should be breaking - so it could be added to every version but because of the massive optional behavior change it could be useful to add these things to Laravel 9 - only to stay safe.

[mikemand]

The second part of your Idea 2 would be fantastic (some kind of global configuration option that sets the same JSON options throughout the application). I currently manually call ->toJson() on a lot of stuff, because I want PHP to throw on any JSON error rather than outputting malformed JSON. I also pass JSON_NUMERIC_CHECK, because 9 times out of 10 I'm working with the JSON in JavaScript and would rather have some typing rather than everything as strings. You can't have floating-point errors with strings, after all. Where's the fun in that?

[Gummibeer]

Hey,
yes - this would be a very cool addition but also a much larger refactoring that's why I've only added it but would say that it's a bit out of scope of that idea/issue. To clarify it I've added a divider in my original post.

But I totally agree that an overall JSON configuration would solve many problems. Would be similar like other settings we already have - language used for translations and carbon for example.
So I think that having one option to define the overall application/framework JSON behavior would be great.

[Gummibeer]

Only for completeness: one default set of JSON options could also get problematic as you would want to use different options to write JSON to files than for your API responses.
So keeping them separated and allowing/having the user to override several classes and define the options there would be more work for the user but fewer problems overall.

[nope123nope]

This would be a very cool addition for those, who use resource transformers as a platform for json response.
For me, passing UGC html througt api (utf-8 encoded as default) it's to heavy.
Upvoted this discussion @Gummibeer thanks for mentioning this approach

[tripleten]

Don't we already have a method to set the encoding options in the API Resource?

You can do it by adding the below method either in your API collection or resource class:

/**
     * Customize the outgoing response for the resource.
     *
     * @param  \Illuminate\Http\Request
     * @param  \Illuminate\Http\Response
     * @return void
     */
    public function withResponse($request, $response)
    {   
        $response->header('Charset', 'utf-8');
        $response->header('Any-other-header', 'header-value');
        $response->setEncodingOptions(JSON_UNESCAPED_UNICODE);
    }

Thoughts, @Gummibeer @mikemand & @nope123nope ?

[NicoHood]

This works great for me!

[NicoHood]

Why isnt that documented in the docs?

[NicoHood]

I've improved it a bit:

/**
 * Customize the outgoing response for the resource.
 *
 * @param  \Illuminate\Http\Request
 * @param  \Illuminate\Http\Response
 * @return void
 */
public function withResponse($request, $response)
{
    $charset = $request->header('Accept-Charset', 'utf-8');
    if ($charset === 'utf-8') {
        $response->header('Charset', 'utf-8');
        $response->header('Content-Type','application/json; charset=utf-8');
        $response->setEncodingOptions(JSON_UNESCAPED_UNICODE);
    }
    // Alternative: iso-8859-1 which will be encoded by default using json escaping.
}