I’ve recently released version For those with sharp eyes\u2014and who carefully read the full PHP8.4,1 release CHANGELOG<\/a>\u2014the following line may have stood out:<\/p>\n\n\n\n At first glance, this change seems harmless. Unfortunately, its implications went largely unnoticed for several reasons.<\/p>\n\n\n\n First, the new behavior was only properly documented almost a year after it had landed in the PHP codebase. Second, the discussion around the change was confined to the pull request that introduced it. Third\u2014and most importantly\u2014the change never reached the PHP Internals mailing list. As a result, its implementation and potential consequences were never openly discussed.<\/p>\n\n\n\n This lack of visibility matters.<\/p>\n\n\n\n To be clear, I fully understand why<\/em> support for backed enums in The outcome was a subtle\u2014but significant\u2014BC break, one that only surfaced later in codebase or libraries like mine that still depend on To illustrate the backward compatibility break, consider the following enums:<\/p>\n\n\n When passing this This change is particularly surprising because the previous behavior\u2014while arguably imperfect\u2014was stable and widely relied upon. Code that had worked consistently across multiple PHP versions can now fail at runtime, even when dealing with simple, well-formed enum values.<\/p>\n\n\n\n The This conversion respects property visibility, which means that serialization results may be surprising when objects such as Until PHP 8.4, enums were no exception to this rule. Since PHP enums are specialized objects, This already represents a significant behavioral shift, but there is more.<\/p>\n\n\n\n Prior to these changes, For example, if we replace the This highlights the full extent of the change. Not only has That combination\u2014changed output and changed failure modes\u2014constitutes a subtle but impactful backward compatibility break.<\/p>\n\n\n\n To allow for a controlled migration\u2014and to reduce the impact of this BC break\u2014I took three steps in my URI packages:<\/p>\n\n\n\n As a result, the latest version of the packages give you explicit control over how query strings are composed.<\/p>\n\n\n\n You can opt in to the legacy behavior using This mode mirrors the historical behavior of You can also enable the new PHP 8.4 enum semantics explicitly using This mode enforces strict enum handling and fails fast when non-backed enums are encountered.<\/p>\n\n\n If you prefer the new serialization semantics without introducing exceptions, use Finally, for completeness, One might argue that all of this is useful for migrating to PHP 8.4+, but once a codebase has been fully patched, what remains in it for developers?<\/p>\n\n\n\n Looking at the amount of complexity required to account for this change, it becomes clear that the rules governing The function should likely be left untouched. That does not mean, however, that we should continue to rely on it.<\/p>\n\n\n\n What we need instead is a new, simpler, and more predictable algorithm.<\/p>\n\n\n\n This is why I introduced an additional mode, named This mode preserves data, handles value lists correctly, and gives These rules were not chosen arbitrarily. They are directly inspired by the behavior currently proposed in the RFC introducing new QueryParams classes as part of the If you are interested in this direction\u2014or if you have opinions, concerns, or improvements to suggest\u2014I strongly encourage you to engage in the discussion on the PHP Internals mailing list, where the PHP RFC: Followup Improvements for ext\/uri<\/a> is being discussed.<\/p>\n\n\n\n These \u201cboring\u201d changes will shape how PHP parses and encodes URL query strings for the foreseeable future. If we want a cleaner, saner, and more predictable API, now is the time to make our voices heard.<\/p>\n\n\n\n Backward compatibility breaks happen in every language and library\u2014sometimes by accident, sometimes by design. Those breaks are acceptable, as long as users are aware of them and understand their intent.<\/p>\n\n\n\n PHP has historically done a good job at avoiding accidental BC breaks, which makes the rare ones all the more disruptive. When they occur, they often surface in unexpected places and create real challenges for users and library authors alike\u2014especially when long-standing, foundational functions are involved. This is why changes to legacy PHP APIs require extra care. The evolution of 7.8<\/code> of my PHP URI toolkit<\/a>. Three of the features introduced in this release were the result of a backward compatibility (BC) break in PHP that went unnoticed during the PHP 8.4 release cycle.<\/p>\n\n\n\n\n
\n
What Went Wrong<\/h2>\n\n\n\n
http_build_query()<\/code> was added. The feature itself makes sense. However, because there was no broader discussion prior to its implementation, developers with deep experience and historical context around http_build_query()<\/code> were never given the opportunity to provide feedback, raise concerns, or suggest alternative approaches.<\/p>\n\n\n\nhttp_build_query()<\/code>.<\/p>\n\n\n\nThe Breaking Change<\/h2>\n\n\n\n
\nenum Feature: string\n{\n case Enabled = 'enabled';\n case Disabled = 'disabled';\n}\n\nenum Coercion\n{\n case On;\n case Off;\n}\n\n$data = (object) [\n 'feature' => Feature::Enabled,\n 'coercion' => Coercion::Off,\n];\n<\/pre><\/div>\n\n\n$data<\/code> object to http_build_query()<\/code>, the behavior differs between PHP versions prior to 8.4 and PHP 8.4+.<\/p>\n\n\n\necho http_build_query($data);\n\/\/ in PHP8.4- returns feature%5Bname%5D=Enabled&feature%5Bvalue%5D=enabled&coercion%5Bname%5D=Off\n\/\/ in PHP8.4- decoded feature[name]=Enabled&feature[value]=enabled&coercion[name]=Off\n\/\/ in PHP8.4+ a ValueError is thrown\n<\/pre><\/div>\n\n\n
The Explanation<\/h2>\n\n\n\n
http_build_query()<\/code> function was introduced in PHP 5. It accepts an array or an object as input and serializes the provided data into a query string. When an object is passed, the function first converts it into an associative array by calling get_object_vars()<\/code> before performing the serialization.<\/p>\n\n\n\nTraversable<\/code> or DateTimeInterface<\/code> instances are provided. The output depends on the object\u2019s internal structure and\u2014particularly for internal classes\u2014may vary across PHP versions as implementations evolve.<\/p>\n\n\n\nhttp_build_query()<\/code> treated them like any other object and serialized them using get_object_vars()<\/code>. However, starting with PHP 8.4, this behavior changed:<\/p>\n\n\n\n\n
json_encode<\/code><\/li>\n\n\n\nValueError<\/code> when encountered as a value inside the input array or object.<\/li>\n\n\n\nTypeError<\/code> when passed directly as the function’s input.<\/li>\n<\/ul>\n\n\n\nhttp_build_query()<\/code> never threw exceptions. When it encountered a value it could not serialize, it would simply ignore it and silently skip the corresponding array entry or object property.<\/p>\n\n\n\nCoercion<\/code> enum from the previous example with a PHP resource\u2014which cannot be serialized\u2014the function quietly drops it:<\/p>\n\n\n\n$data = (object) [\n 'feature' => Feature::Enabled,\n 'coercion' => tmpfile(),\n];\n\necho http_build_query($data);\n\/\/ in PHP8.4- returns "feature%5Bname%5D=Enabled&feature%5Bvalue%5D=enabled"\n\/\/ in PHP8.4+ returns "feature=enabled"\n<\/pre><\/div>\n\n\n
http_build_query()<\/code> adopted a new serialization strategy for enums, it has also introduced inconsistent error-handling semantics. Depending on the type of invalid data encountered, the function may now either throw an exception or silently ignore the offending value.<\/p>\n\n\n\nThe Mitigation<\/h2>\n\n\n\n
\n
http_build_query<\/code> named QueryString::compose()<\/code>.<\/li>\n\n\n\nQueryComposeMode<\/code> enum to explicitly model all supported serialization behaviors.<\/li>\n\n\n\nBackedEnum<\/code> across the entire URI toolkit.<\/li>\n<\/ul>\n\n\n\nPreserve pre\u2013PHP 8.4 behavior in newer PHP versions<\/h3>\n\n\n\n
QueryComposeMode::Compatible<\/code>:<\/p>\n\n\n\nhttp_build_query()<\/code> prior to PHP 8.4 and is useful when maintaining backward compatibility across PHP versions.<\/p>\n\n\n\nuse League\\Uri\\QueryComposeMode;\nuse League\\Uri\\QueryString;\n\necho QueryString::compose($data, composeMode: QueryComposeMode::Compatible);\n\/\/ returns feature%5Bname%5D=Enabled&feature%5Bvalue%5D=enabled&coercion%5Bname%5D=Off\n\/\/ decoded feature[name]=Enabled&feature[value]=enabled&coercion[name]=Off\n<\/pre><\/div>\n\n\n
Opt in to enum-aware behavior on older PHP versions<\/h3>\n\n\n\n
QueryComposeMode::EnumCompatible<\/code>:<\/p>\n\n\n\n\necho QueryString::compose($data, composeMode: QueryComposeMode::EnumCompatible);\n\/\/ throw an Errror if a non BackedEnum is present\necho QueryString::compose(\n ['feature' => Feature::Enabled],\n composeMode: QueryComposeMode::EnumCompatible\n);\n\/\/ returns feature=enabled\n\/\/ BackedEnum are serialized using their backed value\n<\/pre><\/div>\n\n\n
Use enum-aware behavior without exceptions<\/h3>\n\n\n\n
QueryComposeMode::EnumLenient<\/code>. In this mode, non-backed enums are silently ignored\u2014just like resources:<\/p>\n\n\n\necho QueryString::compose($data, composeMode: QueryComposeMode::EnumLenient);\n\/\/ returns feature=enabled\n\/\/ non BackedEnum are ignore like resources\n<\/pre><\/div>\n\n\n
Mirror native PHP behavior<\/h3>\n\n\n\n
QueryComposeMode::Native<\/code> directly mirrors http_build_query()<\/code> and therefore inherits its PHP-version\u2013dependent behavior:<\/p>\n\n\n\necho QueryString::compose(\n ['feature' => Feature::Enabled],\n composeMode: QueryComposeMode::Native\n);\n\/\/ http_build_query behavior (PHP version dependent)\n<\/pre><\/div>\n\n\n
The Evolution<\/h2>\n\n\n\n
http_build_query()<\/code> are already complex\u2014and are now capable of contradicting themselves. Continuously adapting http_build_query()<\/code> to new edge cases seems, to me, like a poor long-term strategy.<\/p>\n\n\n\nQueryComposeMode::Safe<\/code>. This mode is entirely independent of http_build_query()<\/code>. Its goal is not backward compatibility, but clarity, predictability, and correctness. In QueryComposeMode::Safe<\/code> mode, the following rules apply:<\/p>\n\n\n\n\n
BackedEnum<\/code>, string<\/code>, int<\/code>, float<\/code>, boolean<\/code> and null<\/code>.<\/li>\n\n\n\narrays<\/code> may be used for composition.<\/li>\n\n\n\nTypeError<\/code>.<\/li>\n\n\n\nnull<\/code> the key is present but no =<\/code> is appended<\/li>\n<\/ul>\n\n\n\n$data = [\n 'foo' => [\n Feature::Enabled,\n null,\n true\n ],\n];\n\necho QueryString::compose($data, composeMode: QueryComposeMode::Safe);\n\/\/ returns foo%5B%5D=enabled&foo%5B%5D&foo%5B%5D=1\n\/\/ decoded foo[]=enabled&foo[]&foo[]=1\n<\/pre><\/div>\n\n\n
null<\/code> a well-defined and consistent representation.<\/p>\n\n\n\next\/uri<\/code> extension.<\/p>\n\n\n\nPost-Mortem<\/h2>\n\n\n\n
http_build_query()<\/code> highlights this tension well. While the change itself is understandable, its impact shows how fragile the current API is.<\/p>\n\n\n\n