How to pass an array within a query string?
There is no formal standard for passing arrays via query strings. While many frameworks and libraries handle this gracefully, the underlying HTTP specification does not define a canonical format for multi-valued parameters. As noted in discussions regarding JavaScript URLSearchParams, the behavior is largely implementation-dependent. This lack of a rigid standard means that while you can pass multiple values, interpreting them requires specific logic on both the client and server sides.
The most common convention involves repeating the parameter name. If you want to send a list of tags or IDs, the URL typically looks like this:
?filter=apple&filter=banana&filter=cherry
When parsed by standard libraries in PHP, Python, or Node.js, these frameworks usually aggregate repeated keys into an array automatically. In PHP, for instance, accessing $_GET['filter'] will return a list containing "apple", "banana", and "cherry". However, this automatic aggregation is a convenience layer provided by the framework or language runtime, not a guarantee of the HTTP protocol itself.
If your requirement is stricterâspecifically, you need to distinguish between a single value and an array of values explicitly in the URL structureârelying solely on parameter repetition can be ambiguous. Consider a scenario where a developer wants to pass a configuration object as an array:
?settings[name]=admin&settings[role]=editor&settings[id]=5
This "dot notation" or bracketed key syntax is widely supported in frameworks like Laravel, Django, and Express.js. It treats the entire string following the key as a single scalar value if no brackets are present, but parses it as an object or array if brackets are used. This approach avoids the ambiguity of repeated keys because the structure itself signals that an array (or map) is intended.
However, there is a significant trade-off with this method: data validation becomes more complex. If you receive ?settings[name]=admin&settings[role]=editor, a naive parser might treat this as two separate parameters if it doesn't explicitly look for the bracketed syntax. In PHP, you must ensure your retrieval logic accounts for nested structures or uses functions like array_get() or custom parsing to handle the flattened query string correctly.
A critical pitfall arises when mixing scalar and array values for the same key prefix without clear delimiters. For example:
?items[]=1&items[]=2&items[]=3
The [] suffix is another convention, specifically supported by PHP's $_GET to force array behavior even if only one value is present. This is distinct from ?items=1, which would typically be treated as a scalar string unless the application logic explicitly checks for an empty default or uses specific parsing rules.
When working with JavaScript, you should be aware that URLSearchParams.getAll('key') returns all values for a key regardless of how they were formatted in the URL. If you rely on a framework like Express, middleware often flattens these into a single array automatically. Without such middleware, you must manually parse the string or use searchParams.get() which only returns the first occurrence, potentially losing data if multiple values are intended.
If you are building an API with Laravel, the framework handles this via its query string parser configuration. By default, Laravel will collapse repeated keys into arrays. You can customize this behavior in your application configuration to ensure consistent parsing across different environments. For more complex nested structures, Laravelâs request helpers provide methods to access these values as associative arrays, maintaining data integrity without manual string manipulation.
Ultimately, the choice between repeated keys and bracketed syntax depends on your specific needs for backward compatibility and strictness. Repeated keys are simpler but less structured; bracketed syntax is more explicit but requires careful implementation in both client and server code to avoid parsing errors.