## Product Decisions This Supports
- **Feature Development**:
- **API & Webhook Standardization**: Accelerate development of APIs requiring consistent query string handling for pagination (`?page=2&limit=10`), filtering (`?category[]=books&category[]=tech`), or dynamic URL generation (e.g., affiliate tracking).
- **URL Shortener/Link Builder**: Simplify logic for generating shareable links with complex query parameters (e.g., marketing campaigns, UTM tracking).
- **Crawler/Scraper Integration**: Standardize parsing of query strings from external APIs (e.g., Google Fonts, third-party services) where formats vary (e.g., `family=Roboto&family=Baloo` vs. `family[]=Roboto&family[]=Baloo`).
- **Form & Data Processing**: Streamline server-side handling of GET/POST requests with nested or repeated parameters (e.g., multi-select forms, bulk actions in admin panels).
- **Legacy System Modernization**: Normalize query strings from outdated systems (e.g., converting `foo=bar&foo=baz` to `foo[]=bar&foo[]=baz`) to align with modern Laravel conventions.
- **Roadmap Prioritization**:
- **Build vs. Buy Decision**: Justify adopting this package over custom solutions for teams lacking query string expertise or time to maintain edge-case logic (e.g., handling `[]` arrays, URL encoding/decoding, or malformed input like `&foo=bar`).
- **Tech Debt Reduction**: Replace inconsistent query string parsing (e.g., regex, `parse_str`, or manual `http_build_query` hacks) with a maintained, feature-rich library that handles edge cases out-of-the-box.
- **Cross-Team Consistency**: Enforce uniform query string handling across microservices or monoliths where multiple teams manage HTTP requests (e.g., API clients, crawlers, or analytics tools).
- **Use Cases**:
- **Laravel API Development**: Parse and reconstruct query strings for API endpoints (e.g., `Route::get('/search', [SearchController::class, 'index'])` where `$request->query()` is converted to a `Query` object for easier manipulation).
- **SEO & URL Canonicalization**: Manipulate URLs for parameter sorting, duplicate content detection, or generating canonical links (e.g., `?sort=price&sort=name` → `?sort[]=price&sort[]=name`).
- **Analytics & Tracking**: Handle UTM parameters or custom dimensions in event-based systems (e.g., parsing `?utm_source=google&utm_medium=cpc` into a structured array).
- **Client Libraries & SDKs**: Standardize query string generation for internal tools (e.g., a `GitHubClient` that builds URLs like `?repo[]=laravel/framework&repo[]=crwlr/query-string`).
- **Legacy Migration**: Normalize query strings from older systems (e.g., converting `?ids=1&ids=2` to `?ids[]=1&ids[]=2`) to support modern Laravel features like `Request::query('ids', [])`.
---
## When to Consider This Package
- **Adopt When**:
- Your application frequently handles **complex query strings** (nested arrays, repeated keys, URL-encoded values) and you want to avoid manual parsing or string manipulation.
- You need **consistent behavior** across PHP versions (8.0+) for converting between `array` and `string` representations of query strings (e.g., preserving order, handling `[]` notation).
- Your team interacts with **external APIs or legacy systems** that use non-standard query string formats (e.g., Google Fonts, older Laravel versions, or third-party services).
- You prioritize **developer productivity** over minimal dependencies (MIT license, no external services, and active maintenance).
- Your use case aligns with the library’s strengths:
- Parsing malformed query strings (e.g., `&foo=bar`, `foo=bar&`, or `foo=bar=bar==`).
- Generating URL-safe query strings from PHP arrays (e.g., `['foo' => ['bar']]` → `foo%5Bbar%5D=1`).
- Preserving key-value order during conversion (critical for analytics or debugging).
- You’re using **Laravel** and want to integrate seamlessly with `Request` objects, `Route` parameters, or `FormRequest` validation.
- **Look Elsewhere If**:
- You need **query string validation** (e.g., schema enforcement for required/optional fields) or **sanitization** (e.g., stripping non-alphanumeric characters). Use Laravel’s `ValidatedRequest` or libraries like `respect/validation`.
- Your project requires **query string signing** (e.g., for security tokens) or **rate-limiting**. Use Laravel middleware (e.g., `throttle`, `signed`) or packages like `spatie/laravel-query-builder`.
- You’re working with **non-HTTP contexts** (e.g., CLI tools, database queries, or WebSocket messages). Query strings are irrelevant here.
- Your team prefers **built-in PHP functions** (e.g., `parse_str`, `http_build_query`) for simplicity, despite their limitations (e.g., no native support for repeated keys or nested arrays).
- You need **real-time query string updates** (e.g., WebSockets) or **client-side manipulation**. Use JavaScript’s `URLSearchParams` or frontend frameworks like React Router.
- Your application relies on **query string parameters for authentication** (e.g., API keys in URLs). Use Laravel’s `api` middleware or OAuth packages instead.
---
## How to Pitch It (Stakeholders)
### **For Executives**:
*"This PHP package solves a hidden technical debt problem: **query strings are a mess**, and our teams are wasting time fixing edge cases that shouldn’t exist. Currently, we rely on inconsistent solutions like `parse_str`, regex, or manual loops to handle query strings—leading to bugs in APIs, crawlers, and integrations.
By adopting **crwlr/query-string**, we’ll:
- **Eliminate bugs** in URL generation/parsing (e.g., Google Fonts API compatibility, repeated parameters like `?category[]=books&category[]=tech`).
- **Save 10–20 hours/month** by replacing custom logic with a maintained library (last updated 2023).
- **Future-proof** our HTTP interactions with a scalable, zero-dependency solution (MIT license).
- **Align with Laravel best practices** by standardizing query string handling across APIs, crawlers, and analytics.
**Cost**: $0. **ROI**: Faster development, fewer production issues, and happier engineers. Let’s prototype this in [Project X] and measure the impact—if it works, we’ll roll it out company-wide."*
---
### **For Engineers**:
*"**Problem**: Query strings are a nightmare in PHP. Built-in tools like `parse_str` and `http_build_query` can’t handle modern use cases:
- Repeated keys (`?foo=bar&foo=baz` → should become `?foo[]=bar&foo[]=baz`).
- Nested arrays (`?user[address][city]=London`).
- Malformed input (`&foo=bar`, `foo=bar&`, or `foo=bar=bar==`).
- URL encoding/decoding inconsistencies.
Our current solutions (regex, manual loops) are fragile, inconsistent, and hard to maintain.
**Solution**: **crwlr/query-string** fixes this with a clean API:
```php
// Parse a query string into an array
$query = new \Crwlr\QueryString('foo=bar&foo=baz');
$array = $query->toArray();
// ['foo' => ['bar', 'baz']]
// Generate a query string from an array
$query = new \Crwlr\QueryString(['user' => ['name' => 'John']]);
$string = $query->toString();
// 'user%5Bname%5D=John'
// Integrate with Laravel Request
$requestQuery = new \Crwlr\QueryString($request->query());
$categories = $requestQuery->get('category', []); // ['books', 'tech']
Why This?
parse_str or http_build_query quirks.Request, Route, and FormRequest.composer.json and start using it.Ask: Let’s replace our custom query string logic in [Module Y] with this library. If it handles our edge cases (e.g., [specific example]), we’ll:
composer.json today.Risk: Minimal—MIT license, PHP 8.0+, and active maintenance. We can A/B test against our current solution in [Z]."*
*"This package is a ‘build vs. buy’ win for query string handling. Instead of wasting dev cycles on custom parsing logic (which is error-prone and hard to
How can I help you explore Laravel packages today?