Query String Laravel Package

Getting Started

Minimal Steps

1. Installation: Add the package via Composer:

   composer require spatie/query-string
   

2. Basic Usage: Import the QueryString class and instantiate it with a URI:

   use Spatie\QueryString\QueryString;
   $queryString = new QueryString('https://example.com/path?existing=param');
   

3. First Use Case: Modify a query string in a Laravel route or controller:

   $uri = $queryString->toggle('filter'); // Adds `?filter` if missing, removes it if present
   

Where to Look First

• README: Focus on the Usage section for core methods like toggle(), add(), remove(), and get().
• Source Code: Explore src/QueryString.php for method signatures and edge-case handling (e.g., malformed URIs).
• Tests: Check tests/ for real-world examples (e.g., handling nested routes, special characters).

Implementation Patterns

Core Workflows

1. Query String Manipulation in Controllers

Use QueryString to dynamically adjust query parameters based on user actions (e.g., toggling filters):

public function toggleFilter(Request $request, string $filter)
{
    $uri = new QueryString($request->fullUrl());
    $uri->toggle($filter);
    return redirect($uri->get());
}

2. URL Generation with Conditional Parameters

Build URLs with optional query strings (e.g., for pagination or sorting):

$baseUrl = route('products.index');
$query = new QueryString($baseUrl);
$query->add('sort', 'price')->add('page', 2);
$url = $query->get(); // "/products?sort=price&page=2"

3. Integration with Laravel’s Url Facade

Combine with Laravel’s Url helper for seamless URL generation:

$url = Url::current();
$query = new QueryString($url);
$query->remove('utm_source'); // Clean up tracking params
return redirect($query->get());

4. Form Actions with Dynamic Query Strings

Preserve existing query parameters when submitting forms:

// In a Blade template
<form action="{{ $queryString->add('action', 'search')->get() }}">

5. API Response Headers

Modify Location headers in API responses to include/exclude query params:

return response()->redirectTo($queryString->toggle('debug')->get());

Advanced Patterns

Query String Validation

Use the package to validate incoming query strings (e.g., whitelist allowed params):

$allowedParams = ['page', 'per_page', 'sort'];
$query = new QueryString($request->fullUrl());
$cleanUrl = $query->filter(fn($key) => in_array($key, $allowedParams))->get();

Deep Query String Manipulation

Handle nested or complex query structures (e.g., arrays):

$query->set('filters', ['category' => 'books', 'price' => ['min' => 10]]);
// Result: "?filters[category]=books&filters[price][min]=10"

Testing

Mock query strings in tests to simulate user interactions:

$query = new QueryString('https://example.com?old=param');
$this->assertEquals('https://example.com?new=param', $query->remove('old')->add('new', 'param')->get());

Gotchas and Tips

Pitfalls

1. URI Parsing Quirks

   • Issue: Malformed URIs (e.g., missing ? before params) may break parsing. Fix: Use QueryString::createFromUriString() or validate input with parse_url().
   • Example:

     $query = new QueryString('https://example.compath?param=1'); // Fails silently
     // Solution: Sanitize input first.
     

2. Parameter Overwriting

   • Issue: add() or set() overwrites existing values without warning. Fix: Use toggle() for boolean flags or check with has() first:

     if (!$query->has('debug')) {
         $query->add('debug', 'true');
     }
     

3. Encoding/Decoding Mismatches

   • Issue: Special characters (e.g., &, =) in values may cause parsing errors. Fix: Manually encode values before passing to add()/set():

     $query->add('search', urlencode('foo & bar'));
     

4. Fragment Handling

   • Issue: Query strings after # (fragments) are ignored. Fix: Strip fragments before processing:

     $uriWithoutFragment = strtok($uri, '#');
     $query = new QueryString($uriWithoutFragment);
     

5. Laravel-Specific Conflicts

   • Issue: Conflicts with Laravel’s Illuminate\Support\Str or Url facade methods. Fix: Prefix methods or use fully qualified names:

     \Spatie\QueryString\QueryString::createFromUriString($uri);
     

Debugging Tips

1. Inspect Raw Input Log the input URI to debug parsing issues:

   \Log::debug('Raw URI:', ['uri' => $uri]);
   

2. Check for Silent Failures Always validate the output with get() after modifications:

   $uri = $query->toggle('param')->get();
   $this->assertStringContainsString('param=', $uri);
   

3. Test Edge Cases Test with:

   • Empty query strings (/).
   • Multiple ? characters (http://example.com??param=1).
   • Unicode characters (?search=café).

Extension Points

1. Custom Parameter Handlers Extend the class to add domain-specific logic (e.g., auto-encoding for API params):

   class ApiQueryString extends QueryString
   {
       public function addApiParam(string $key, $value): self
       {
           return $this->add($key, json_encode($value));
       }
   }
   

2. Integration with Laravel Services Bind the package to Laravel’s service container for dependency injection:

   // In a service provider
   $this->app->bind(QueryString::class, function () {
       return new QueryString(request()->fullUrl());
   });
   

3. Middleware for Query String Sanitization Create middleware to clean query strings globally:

   public function handle($request, Closure $next)
   {
       $uri = new QueryString($request->fullUrl());
       $cleanUri = $uri->filter(fn($key) => !str_starts_with($key, 'utm_'))->get();
       $request->merge(pathinfo($cleanUri, PATH_QUERY));
       return $next($request);
   }
   

4. Event-Based Query String Changes Trigger events when query strings are modified (e.g., for analytics):

   $query->onChange(function ($oldUri, $newUri) {
       event(new QueryStringChanged($oldUri, $newUri));
   });
   // Requires extending the class to support events.