[12.x] Add test coverage for Uri::withQueryIfMissing method (#54923)

* Add initial test for Uri::withQueryIfMissing method

This test verifies that the withQueryIfMissing method adds parameters only when they don't exist
while preserving the values of existing parameters.

* Expand withQueryIfMissing tests to cover nested arrays

This commit adds cases for complex nested arrays and indexed arrays to ensure
the method correctly handles multi-dimensional data structures in query parameters.

* Complete withQueryIfMissing tests for advanced array handling

This commit finalizes tests for the withQueryIfMissing method, covering:
- Partial merging of associative arrays
- Preservation of indexed arrays
- Verification of both encoded query strings and parsed arrays

* docs: add PHPDoc annotation for withQueryIfMissing method

* Update Uri.php

---------

Co-authored-by: Taylor Otwell <taylor@laravel.com>

Author: mohammadrasoulasghari

tests/Support/SupportUriTest.php

@@ -126,4 +126,66 @@ public function test_decoding_the_entire_uri()
 
         $this->assertEquals('https://laravel.com/docs/11.x/installation?tags[0]=first&tags[1]=second', $uri->decode());
     }
+
+    public function test_with_query_if_missing()
+    {
+        // Test adding new parameters while preserving existing ones
+        $uri = Uri::of('https://laravel.com?existing=value');
+
+        $uri = $uri->withQueryIfMissing([
+            'new' => 'parameter',
+            'existing' => 'new_value',
+        ]);
+
+        $this->assertEquals('existing=value&new=parameter', $uri->query()->decode());
+
+        // Test adding complex nested arrays to empty query string
+        $uri = Uri::of('https://laravel.com');
+
+        $uri = $uri->withQueryIfMissing([
+            'name' => 'Taylor',
+            'role' => [
+                'title' => 'Developer',
+                'focus' => 'PHP',
+            ],
+            'tags' => [
+                'person',
+                'employee',
+            ],
+        ]);
+
+        $this->assertEquals('name=Taylor&role[title]=Developer&role[focus]=PHP&tags[0]=person&tags[1]=employee', $uri->query()->decode());
+
+        // Test partial array merging and preserving indexed arrays
+        $uri = Uri::of('https://laravel.com?name=Taylor&tags[0]=person');
+
+        $uri = $uri->withQueryIfMissing([
+            'name' => 'Changed',
+            'age' => 38,
+            'tags' => ['should', 'not', 'change'],
+        ]);
+
+        $this->assertEquals('name=Taylor&tags[0]=person&age=38', $uri->query()->decode());
+        $this->assertEquals(['name' => 'Taylor', 'tags' => ['person'], 'age' => 38], $uri->query()->all());
+
+        $uri = Uri::of('https://laravel.com?user[name]=Taylor');
+
+        $uri = $uri->withQueryIfMissing([
+            'user' => [
+                'name' => 'Should Not Change',
+                'age' => 38,
+            ],
+            'settings' => [
+                'theme' => 'dark',
+            ],
+        ]);
+        $this->assertEquals([
+            'user' => [
+                'name' => 'Taylor',
+            ],
+            'settings' => [
+                'theme' => 'dark',
+            ],
+        ], $uri->query()->all());
+    }
 }