Adding QueryComposeMode::EnumLenient

Author: nyamsprod

QueryComposeMode.php

@@ -25,6 +25,26 @@ enum QueryComposeMode
      */
     case Compatible;
 
+    /**
+     * PHP 8.4+ enum-compatible lenient mode.
+     *
+     * Provides stable support for BackedEnum values.
+     * UnitEnum values are skipped.
+     * Uses get_object_vars() for non-enum objects.
+     * Unserializable values are skipped.
+     *
+     * Behaves like {@see QueryComposeMode::EnumCompatible}
+     * but does not throw for UnitEnum values.
+     *
+     * Mirrors http_build_query behavior in PHP 8.4+,
+     * except that error cases are silently ignored
+     * instead of throwing.
+     *
+     * This mode is tolerant by design and skips entries that would otherwise
+     * result in an exception in {@see QueryComposeMode::EnumCompatible}.
+     */
+    case EnumLenient;
+
     /**
      * PHP 8.4+ mode.
      *
@@ -34,8 +54,6 @@ enum QueryComposeMode
      * Unserializable values are skipped.
      *
      * http_build_query behavior in PHP 8.4+.
-     *
-     * Non-enum behavior may evolve in future versions.
      */
     case EnumCompatible;
 

QueryString.php

@@ -147,6 +147,10 @@ public static function composeFromValue(
         ?Converter $converter = null,
         QueryComposeMode $composeMode = QueryComposeMode::Native,
     ): ?string {
+        if (QueryComposeMode::EnumLenient === $composeMode && $data instanceof UnitEnum && !$data instanceof BackedEnum) {
+            return '';
+        }
+
         QueryComposeMode::Safe !== $composeMode || is_array($data) || throw new TypeError('In safe mode only arrays are supported.');
 
         $converter ??= Converter::fromRFC3986();
@@ -173,7 +177,7 @@ private static function composeRecursive(
         SplObjectStorage $seenObjects = new SplObjectStorage(),
     ): iterable {
         QueryComposeMode::Safe !== $composeMode || is_array($data) || throw new TypeError('In safe mode only arrays are supported.');
-        QueryComposeMode::EnumCompatible !== $composeMode || !$data instanceof UnitEnum || throw new TypeError('Argument #1 ($data) must not be an enum, '.((new ReflectionEnum($data::class))->isBacked() ? 'Backed' : 'Pure').' given') ;
+        in_array($composeMode, [QueryComposeMode::EnumCompatible, QueryComposeMode::EnumLenient], true) || !$data instanceof UnitEnum || throw new TypeError('Argument #1 ($data) must not be an enum, '.((new ReflectionEnum($data::class))->isBacked() ? 'Backed' : 'Pure').' given') ;
 
         if (is_object($data)) {
             if ($seenObjects->contains($data)) {
@@ -205,12 +209,20 @@ private static function composeRecursive(
                 continue;
             }
 
-            if (null === $value || is_scalar($value)) {
+            if (is_scalar($value)) {
                 yield [$name, $value];
 
                 continue;
             }
 
+            if (null === $value) {
+                if (QueryComposeMode::Safe === $composeMode) {
+                    yield [$name, $value];
+                }
+
+                continue;
+            }
+
             if ($value instanceof BackedEnum) {
                 if (QueryComposeMode::Compatible !== $composeMode) {
                     yield [$name, $value->value];
@@ -222,6 +234,10 @@ private static function composeRecursive(
             }
 
             if ($value instanceof UnitEnum) {
+                if (QueryComposeMode::EnumLenient === $composeMode) {
+                    continue;
+                }
+
                 QueryComposeMode::Compatible === $composeMode || throw new TypeError('Unbacked enum '.$value::class.' cannot be converted to a string');
 
                 $value = get_object_vars($value);

QueryStringTest.php

@@ -23,6 +23,7 @@
 use ValueError;
 
 use function date_create;
+use function http_build_query;
 use function tmpfile;
 
 use const PHP_QUERY_RFC1738;
@@ -807,6 +808,11 @@ public function test_it_throws_if_a_non_backed_enum_is_given_in_enum_native_mode
         QueryString::compose(['pure' => PureEnum::One], composeMode: QueryComposeMode::EnumCompatible);
     }
 
+    public function test_it_silently_ignore_if_a_non_backed_enum_is_given_in_enum_lenient_mode(): void
+    {
+        self::assertSame('foo=bar', QueryString::compose(['pure' => PureEnum::One, 'foo' => 'bar'], composeMode: QueryComposeMode::EnumLenient));
+    }
+
     public function test_it_throws_if_a_non_backed_enum_is_given_in_strict_mode(): void
     {
         $this->expectException(TypeError::class);
@@ -827,6 +833,7 @@ public function test_it_handles_backed_enums(): void
 
         self::assertSame((PHP_VERSION_ID < 80400 ? $compatible : $enumNative).'&baz=1', QueryString::compose($params, composeMode: QueryComposeMode::Native));
         self::assertSame($compatible.'&baz=1', QueryString::compose($params, composeMode: QueryComposeMode::Compatible));
+        self::assertSame($enumNative.'&baz=1', QueryString::compose($params, composeMode: QueryComposeMode::EnumLenient));
         self::assertSame($enumNative.'&baz=1', QueryString::compose($params, composeMode: QueryComposeMode::EnumCompatible));
         self::assertSame($enumNative.'&baz=1', QueryString::compose($params, composeMode: QueryComposeMode::Safe));
 
@@ -836,6 +843,7 @@ public function test_it_can_handles_empty_array(): void
     {
         self::assertSame('', QueryString::compose([], composeMode: QueryComposeMode::Native));
         self::assertSame('', QueryString::compose([], composeMode: QueryComposeMode::Compatible));
+        self::assertSame('', QueryString::compose([], composeMode: QueryComposeMode::EnumLenient));
         self::assertSame('', QueryString::compose([], composeMode: QueryComposeMode::EnumCompatible));
         self::assertNull(QueryString::compose([], composeMode: QueryComposeMode::Safe));
     }
@@ -847,6 +855,18 @@ public function test_it_can_convert_list_without_indices_in_safe_mode(): void
         self::assertSame('a%5B%5D=foo&a%5B%5D=0&a%5B%5D=1.23', QueryString::compose($data, composeMode: QueryComposeMode::Safe));
         self::assertSame('a%5B0%5D=foo&a%5B1%5D=0&a%5B2%5D=1.23', QueryString::compose($data, composeMode: QueryComposeMode::Native));
     }
+
+    public function test_it_can_handle_null_value_differently_with_composed_mode(): void
+    {
+        $data = ['module' => null, 'action' => '', 'page' => true];
+
+        self::assertSame('module&action=&page=1', QueryString::compose($data, composeMode: QueryComposeMode::Safe));
+        self::assertSame('action=&page=1', QueryString::compose($data, composeMode: QueryComposeMode::EnumLenient));
+        self::assertSame('action=&page=1', QueryString::compose($data, composeMode: QueryComposeMode::EnumCompatible));
+        self::assertSame('action=&page=1', QueryString::compose($data, composeMode: QueryComposeMode::Compatible));
+        self::assertSame('action=&page=1', QueryString::compose($data, composeMode: QueryComposeMode::Native));
+        self::assertSame('action=&page=1', http_build_query($data));
+    }
 }
 
 enum PureEnum