feat(Arguments): Added Array Stackable argument

Needed that to match IN filters of freshbooks queries
They using non standard query params with the following format:
?search[statusids][]=1&search[statusids][]=2

Author: philippe-bourdeau

src/Request/Api/BaseRequest.php

@@ -14,6 +14,8 @@
 use ZEROSPAM\Framework\SDK\Request\Arguments\Mergeable\IMergeableArgument;
 use ZEROSPAM\Framework\SDK\Request\Arguments\Mergeable\Worker\ArgMerger;
 use ZEROSPAM\Framework\SDK\Request\Arguments\Stackable\IStackableArgument;
+use ZEROSPAM\Framework\SDK\Request\Arguments\Stackable\IStackableArrayArgument;
+use ZEROSPAM\Framework\SDK\Request\Arguments\Stackable\Worker\ArgArrayCollector;
 use ZEROSPAM\Framework\SDK\Request\Arguments\Stackable\Worker\ArgCollector;
 use ZEROSPAM\Framework\SDK\Request\Type\RequestType;
 use ZEROSPAM\Framework\SDK\Response\Api\IResponse;
@@ -43,6 +45,9 @@ abstract class BaseRequest implements IRequest
      */
     private $stackableArguments = [];
 
+    /** @var ArgArrayCollector[] */
+    private $stackableArrayArguments = [];
+
     /**
      * @var \ZEROSPAM\Framework\SDK\Response\Api\IResponse
      */
@@ -74,7 +79,16 @@ public function addArgument(IArgument $arg): IRequest
 
             return $this;
         }
-        if ($arg instanceof IStackableArgument) {
+
+        if ($arg instanceof IStackableArrayArgument) {
+            if (!isset($this->stackableArrayArguments[$arg->getKey()])) {
+                $this->stackableArrayArguments[$arg->getKey()] = new ArgArrayCollector();
+            }
+
+            $this->stackableArrayArguments[$arg->getKey()]->addArgument($arg);
+
+            return $this;
+        } elseif ($arg instanceof IStackableArgument) {
             if (!isset($this->stackableArguments[$arg->getKey()])) {
                 $this->stackableArguments[$arg->getKey()] = new ArgCollector();
             }
@@ -185,7 +199,8 @@ public function toUri(): UriInterface
      */
     final public function requestType(): RequestType
     {
-        return $this->requestTypeOverride ?: $this->httpType();
+        return $this->requestTypeOverride
+            ?: $this->httpType();
     }
 
     /**
@@ -277,6 +292,11 @@ private function generateUrl(): string
         foreach ($this->stackableArguments as $key => $value) {
             $query[$key] = $value->toArray();
         }
+
+        foreach ($this->stackableArrayArguments as $key => $value) {
+            $query[$key] = $value->toArray();
+        }
+
         $queryArg = http_build_query($query, null, '&', PHP_QUERY_RFC3986);
 
         $fullUrl = $this->routeUrl() . '?' . preg_replace($re, $subst, $queryArg);

src/Request/Arguments/RequestArg.php

@@ -22,15 +22,16 @@ class RequestArg implements IArgument
     /**
      * @var string
      */
-    private $key;
+    protected $key;
+
     /** @var string */
-    private $value;
+    protected $value;
 
     /**
      * RequestArg constructor.
      *
-     * @param string $key
-     * @param string $value
+     * @param string       $key
+     * @param string|array $value
      */
     public function __construct($key, $value)
     {

src/Request/Arguments/Stackable/IStackableArrayArgument.php

@@ -0,0 +1,20 @@
+<?php
+/**
+ * Created by PhpStorm.
+ * User: pbb
+ * Date: 25/09/18
+ * Time: 9:40 AM
+ */
+
+namespace ZEROSPAM\Framework\SDK\Request\Arguments\Stackable;
+
+/**
+ * Interface IStackableArrayArgument
+ *
+ * Contract for arguments using Freshbooks specific format: ex. ?search[statusids][]=1&search[statusids][]=2
+ *
+ * @package ZEROSPAM\Framework\SDK\Request\Arguments\Stackable
+ */
+interface IStackableArrayArgument extends ISubKeyedStackableArgument
+{
+}

src/Request/Arguments/Stackable/SubKeyedArrayStackableRequestArg.php

@@ -0,0 +1,49 @@
+<?php
+/**
+ * Created by PhpStorm.
+ * User: pbb
+ * Date: 25/09/18
+ * Time: 9:30 AM
+ */
+
+namespace ZEROSPAM\Framework\SDK\Request\Arguments\Stackable;
+
+
+use ZEROSPAM\Framework\SDK\Request\Arguments\RequestArg;
+
+/**
+ * Class SubKeyedArrayStackableRequestArg
+ *
+ * Implementation for arguments using Freshbooks specific format: ex. ?search[statusids][]=1&search[statusids][]=2
+ *
+ * @package ZEROSPAM\Framework\SDK\Request\Arguments\Stackable
+ */
+class SubKeyedArrayStackableRequestArg extends RequestArg implements IStackableArrayArgument
+{
+    /**
+     * @var null|string
+     */
+    private $subKey;
+
+    public function __construct(string $key, string $subKey, array $value)
+    {
+        parent::__construct($key, $value);
+        $this->subKey = $subKey;
+    }
+
+    /**
+     * @return string
+     */
+    public function getSubKey(): string
+    {
+        return $this->subKey;
+    }
+
+    /**
+     * @return float|int|mixed|string
+     */
+    public function toPrimitive()
+    {
+        return $this->value;
+    }
+}

src/Request/Arguments/Stackable/Worker/ArgArrayCollector.php

@@ -0,0 +1,58 @@
+<?php
+/**
+ * Created by PhpStorm.
+ * User: pbb
+ * Date: 25/09/18
+ * Time: 9:23 AM
+ */
+
+namespace ZEROSPAM\Framework\SDK\Request\Arguments\Stackable\Worker;
+
+
+use ZEROSPAM\Framework\SDK\Request\Arguments\Stackable\IStackableArgument;
+use ZEROSPAM\Framework\SDK\Request\Arguments\Stackable\ISubKeyedStackableArgument;
+
+class ArgArrayCollector extends ArgCollector
+{
+    /**
+     * @param IStackableArgument $argument
+     *
+     * @return $this|ArgCollector
+     */
+    public function addArgument(IStackableArgument $argument)
+    {
+        if ($argument instanceof ISubKeyedStackableArgument) {
+            $key = $argument->getSubKey();
+            if (isset($this->args[$key])) {
+                throw new \InvalidArgumentException("Can't override the subkey: $key");
+            }
+        } else {
+            $key = $this->stackKey();
+        }
+
+        $this->args[$key][$argument->getSubKey()] = $argument;
+
+        return $this;
+    }
+
+    /**
+     * @param IStackableArgument $argument
+     *
+     * @return $this|ArgCollector
+     */
+    public function removeArgument(IStackableArgument $argument)
+    {
+        if ($argument instanceof ISubKeyedStackableArgument) {
+            $key = $argument->getSubKey();
+        } else {
+            $key = $this->stackKey();
+        }
+
+        unset($this->args[$key][$argument->getSubKey()]);
+        if (empty($this->args[$key])) {
+            unset($this->args[$key]);
+        }
+
+        return $this;
+    }
+}

src/Request/Arguments/Stackable/Worker/ArgCollector.php

@@ -18,20 +18,20 @@ class ArgCollector implements Arrayable
     /**
      * @var IStackableArgument[][]
      */
-    private $args = [];
+    protected $args = [];
 
     /**
      * @var string
      */
-    private $stackKey;
+    protected $stackKey;
 
 
     /**
      * Get the unique stack key
      *
      * @return string
      */
-    private function stackKey(): string
+    protected function stackKey(): string
     {
         if ($this->stackKey) {
             return $this->stackKey;

tests/src/Base/Argument/SearchArgumentArray.php

@@ -0,0 +1,26 @@
+<?php
+/**
+ * Created by PhpStorm.
+ * User: pbb
+ * Date: 25/09/18
+ * Time: 9:53 AM
+ */
+
+namespace ZEROSPAM\Framework\SDK\Test\Base\Argument;
+
+
+use ZEROSPAM\Framework\SDK\Request\Arguments\Stackable\SubKeyedArrayStackableRequestArg;
+
+class SearchArgumentArray extends SubKeyedArrayStackableRequestArg
+{
+    /**
+     * SearchArrayArgument constructor.
+     *
+     * @param string $searchKey
+     * @param array  $value
+     */
+    public function __construct(string $searchKey, array $value)
+    {
+        parent::__construct('search', $searchKey, $value);
+    }
+}

tests/src/Tests/Argument/StackableArgumentTest.php

@@ -9,6 +9,7 @@
 namespace ZEROSPAM\Framework\SDK\Test\Tests\Argument;
 
 use ZEROSPAM\Framework\SDK\Test\Base\Argument\IncludeStackableArg;
+use ZEROSPAM\Framework\SDK\Test\Base\Argument\SearchArgumentArray;
 use ZEROSPAM\Framework\SDK\Test\Base\Data\TestRequest;
 use ZEROSPAM\Framework\SDK\Test\Base\TestCase;
 
@@ -34,7 +35,6 @@ public function add_argument_stack()
      */
     public function remove_argument_stack()
     {
-        $key     = (new IncludeStackableArg('t'))->getKey();
         $request = new TestRequest();
         $request->addArgument(new IncludeStackableArg('test'))
                 ->addArgument(new IncludeStackableArg('superTest'))
@@ -90,4 +90,37 @@ public function testStackableInUrl(): void
                ->processRequest($request);
         $this->validateQuery($client, 'include[]=test', 'include[]=test2');
     }
+
+    /**
+     *
+     */
+    public function testArrayStackableInUrl(): void
+    {
+        $client = $this->preSuccess([]);
+
+        $request = new TestRequest();
+        $request->addArgument(new SearchArgumentArray('statusids', [1, 2]));
+        $client->getOAuthTestClient()
+               ->processRequest($request);
+        $this->validateQuery($client, 'search[statusids][]=1', 'search[statusids][]=2');
+    }
+
+    /**
+     *
+     */
+    public function removeArrayStackable(): void
+    {
+        $client = $this->preSuccess([]);
+
+        $request = new TestRequest();
+        $request->addArgument(new SearchArgumentArray('statusids', [1]))
+                ->removeArgument(new SearchArgumentArray('statusids', [1]));
+
+        $client->getOAuthTestClient()
+               ->processRequest($request);
+
+        $uri = $request->toUri();
+
+        $this->assertNotContains('search[statusids][]=1', $uri->getQuery());
+    }
 }