PHP 7.1 json_encode() Float Issue
Upgrading a codebase from PHP 7.0 to PHP 7.1 often reveals subtle behavioral shifts that aren't immediately obvious in standard documentation. A common culprit is the change in how floating-point numbers are serialized within JSON responses. Specifically, upgrading to PHP 7.1.x introduces a side effect where json_encode() may output extended precision for double values, turning a clean number like 472.185 into 472.18500000000006.
This behavior stems from a deliberate internal change in PHP's implementation of the JSON extension. In earlier versions (PHP 7.0 and prior), the json_encode() function relied on the global precision setting when formatting doubles. This setting was designed to control how many decimal places were displayed, effectively rounding long floating-point artifacts that resulted from IEEE 754 binary representation limitations.
However, starting in PHP 7.1, the behavior shifted. The JSON extension began relying on the serialize_precision option instead. While this might seem like a minor configuration update, it fundamentally altered how floats are handled by default. If your application relied on the global precision directive to mask these floating-point inaccuracies during JSON serialization, that protection is now bypassed unless you explicitly configure serialize_precision.
The result is often seen in API responses where client-side logic expects a specific number of decimal places. For example, a value stored as 472.185 might appear in the JSON output as 472.18500000000006. This extra precision can break downstream systems that perform string comparisons or parse JSON expecting limited decimal depth.
Understanding the Configuration Change
The core issue lies in which configuration directive controls the output. In PHP 7.0, json_encode() respected the global precision setting found in php.ini:
precision = 14
In PHP 7.1 and later, json_encode() respects serialize_precision instead. If this directive is not explicitly set in your php.ini, or if it is set to -1 (the default), PHP will use the full precision of the underlying float type, which often exposes those trailing digits.
To maintain backward compatibility with applications expecting rounded floats without reverting to an older PHP version, you can adjust this setting:
serialize_precision = 14
Setting serialize_precision to a specific integer tells PHP to limit the number of significant digits in the output. This effectively mimics the behavior of the old precision directive but applies specifically to JSON serialization.
Alternatively, you can pass the option directly into the json_encode() function call:
$json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_NUMERIC_CHECK);
// Or explicitly set precision if supported by your PHP version and extension build
$json = json_encode($data, JSON_PRETTY_PRINT);
// Note: Direct precision argument is not standard in core json_encode until specific versions/extensions
While passing options directly to json_encode allows for per-call control, relying on the global serialize_precision setting is often cleaner for framework-level consistency.
Trade-offs and Considerations
Disabling full float precision is necessary for API cleanliness, but it comes with a caveat: you are now responsible for defining what constitutes an acceptable number of decimal places. Setting serialize_precision too low might cause loss of legitimate data if your floats genuinely require higher accuracy. Conversely, leaving it at the default (-1) preserves all bits, which can confuse consumers of your API.
If you must revert to PHP 7.0.16 due to this limitation, consider whether the underlying issue is truly a bug or a feature difference. In many cases, upgrading to a later patch in PHP 7.1 (like 7.1.2) might include further refinements, though the default behavior regarding serialize_precision generally remained consistent across minor updates.
For modern PHP versions (8.x), this issue is often addressed differently or handled with stricter defaults depending on the JSON extension version. However, for those stuck in the 7.x branch, understanding and configuring serialize_precision is the most reliable path forward without compromising your stack's integrity.