Feat: Flat query parser (#5)

Author: bpolaszek

README.md

@@ -15,7 +15,7 @@ Because I needed an intuitive way to add or remove parameters from a query strin
 
 Oh, and, I also wanted that `['foos' => ['foo', 'bar']]` resolved to `foos[]=foo&foos[]=bar` instead of `foos[0]=foo&foos[1]=bar`, unlike many libraries do.
 
-This behavior is not the default one of that library, but there's an [easy way to change it](doc/RenderAsString.md#change-renderer).
+Thanks to object-oriented design, you can define the way query strings are [parsed](doc/Instantiation.md) and [rendered](doc/RenderAsString.md#change-renderer).
 
 ## Usage
 
@@ -44,15 +44,15 @@ print $qs; // foo=foofoo&ho=hi
 
 ## Documentation
 
-[Instanciation](doc/Instanciation.md)
+[Instantiation / Parsing](doc/Instantiation.md)
 
 [Manipulate parameters](doc/ManipulateParameters.md)
 
 [Render as string](doc/RenderAsString.md)
 
 ## Installation
 PHP 7.1+ is required.
-> composer require bentools/querystring 1.0.x-dev
+> composer require bentools/querystring:^1.0
 
 ## Tests
 > ./vendor/bin/phpunit

doc/Instanciation.md doc/Instantiation.mddoc/Instanciation.md renamed to doc/Instantiation.md

@@ -1,4 +1,4 @@
-# Instanciation
+# Instantiation
 
 You can create a `QueryString` object from a PSR-7 `UriInterface` object, a string or an array of values.
 
@@ -27,7 +27,7 @@ use BenTools\QueryString\QueryString;
 $qs = QueryString::factory('foo=bar&baz=bat'); // Same argument requirements
 ```
 
-## Instanciate from current location
+## Instantiate from current location
 
 It will read `$_SERVER['QUERY_STRING']`.
 
@@ -43,6 +43,21 @@ $qs = QueryString::createFromCurrentLocation();
 
 Of course this will throw a `RuntimeException` when trying to run this from `cli` :smile:
 
+## Flat query parser
+
+By default, PHP considers that `?foo=bar&foo=baz` has a single parameter `foo` with value `baz`.
+
+If you need to parse such query strings, you can use the `FlatParser`: multiple keys will be detected and converted to arrays.
+
+```php
+use BenTools\QueryString\Parser\FlatParser;
+use function BenTools\QueryString\query_string;
+
+$qs = query_string('foo=bar&foo=baz&bar=foo', new FlatParser());
+var_dump($qs->getParam('foo')); // array('bar', 'baz')
+var_dump($qs->getParam('bar')); // string 'foo'
+```
+
 ## Create your own parser
 
 [bentools/querystring](https://github.com/bpolaszek/querystring) relies on PHP's `parse_str()` function to create an array of parameters from your query string.
@@ -100,4 +115,4 @@ QueryString::restoreDefaultParser();
 ```
 
 
-[Next](ManipulateParameters.md) - Manipulate parameters
+[Next](ManipulateParameters.md) - Manipulate parameters

doc/ManipulateParameters.md

@@ -127,6 +127,6 @@ Output:
 ```
 
 
-[Previous](Instanciation.md) - Instanciation
+[Previous](Instantiation.md) - Instantiation
 
 [Next](RenderAsString.md) - Render as string

src/Parser/FlatParser.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace BenTools\QueryString\Parser;
+
+use function explode;
+use function is_array;
+use function urldecode;
+
+final class FlatParser implements QueryStringParserInterface
+{
+    /**
+     * @var string
+     */
+    private $separator;
+
+    public function __construct(string $separator = '&')
+    {
+        $this->separator = $separator;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function parse(string $queryString): array
+    {
+        $params = [];
+        $pairs = explode($this->separator, $queryString);
+        foreach ($pairs as $pair) {
+            if (!isset($params[$pair]) && false === strpos($pair, '=')) {
+                $key = urldecode($pair);
+                $params[$key] = null;
+                continue;
+            }
+            [$key, $value] = explode('=', $pair);
+            $key = urldecode($key);
+            $value = urldecode($value);
+            if (!isset($params[$key])) {
+                $params[$key] = $value;
+            } elseif (!is_array($params[$key])) {
+                $params[$key] = [$params[$key], $value];
+            } else {
+                $params[$key][] = $value;
+            }
+        }
+
+        return $params;
+    }
+}

tests/FlatParserTest.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BenTools\QueryString\Tests;
+
+use BenTools\QueryString\Parser\FlatParser;
+use PHPUnit\Framework\TestCase;
+
+use function BenTools\QueryString\query_string;
+
+class FlatParserTest extends TestCase
+{
+    public function testFlatQueryParser(): void
+    {
+        $qs = query_string('topic=foo&topic=bar&topic=foo%20bar&foo=bar&hi', new FlatParser());
+        $expected = [
+            'topic' => ['foo', 'bar', 'foo bar'],
+            'foo' => 'bar',
+            'hi' => null,
+        ];
+        $this->assertEquals($expected, $qs->getParams());
+    }
+}