integrated parameterhelper

Author: transistive

Dockerfile

@@ -19,7 +19,7 @@ RUN apt-get update && apt-get install -y \
 ARG WITH_XDEBUG=false
 
 RUN if [ $WITH_XDEBUG = "true" ] ; then \
-        pecl install channel://pecl.php.net/xdebug-3.0.1; \
+        pecl install channel://pecl.php.net/xdebug-2.9.3; \
         docker-php-ext-enable xdebug; \
 fi;
 RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

README.md

@@ -127,6 +127,21 @@ $tsx->rollback();
 $tsx->commit([Statement::create('MATCH (x) RETURN x LIMIT 100')]);
 ```
 
+### Differentiating between parameter type
+
+Cypher has lists and maps. This notion can be problematic as the standard php arrays encapsulate both. When you provide an empty array as a parameter, it will be impossible to determine if it is an empty list or map.
+
+The `ParameterHelper` class is the ideal companion for this:
+
+```php
+use Laudis\Neo4j\ParameterHelper;
+
+$client->run('MATCH (x) WHERE x.slug in $listOrMap RETURN x', ['listOrMap' => ParameterHelper::asList([])]); // will return an empty set
+$client->run('MATCH (x) WHERE x.slug in $listOrMap RETURN x', ['listOrMap' => ParameterHelper::asMap([])]); // will error
+$client->run('MATCH (x) WHERE x.slug in $listOrMap RETURN x', ['listOrMap' => []]); // will error
+```
+
+This helper can also be used to make intent explicit.
 
 ### Providing custom injections
 
@@ -163,9 +178,9 @@ Flexibility is maintained where possible by making all parameters iterables if t
 
 ```php
 // Vanilla flavour
-$client->run('MATCH (x {slug: $slug})', ['slug' => 'a']);
+use Ds\Map;$client->run('MATCH (x {slug: $slug})', ['slug' => 'a']);
 // php-ds implementation
-$client->run('MATCH (x {slug: $slug})', new \Ds\Map(['slug' => 'a']));
+$client->run('MATCH (x {slug: $slug})', new Map(['slug' => 'a']));
 // laravel style
 $client->run('MATCH (x {slug: $slug})', collect(['slug' => 'a']));
 ```

src/Databags/Statement.php

@@ -13,21 +13,19 @@
 
 namespace Laudis\Neo4j\Databags;
 
-use Ds\Map;
-
 final class Statement
 {
     private string $text;
-    /** @var array<string, scalar|iterable|null> */
-    private array $parameters;
+    /** @var iterable<string, scalar|iterable|null> */
+    private iterable $parameters;
 
     /**
      * @param iterable<string, scalar|iterable|null> $parameters
      */
     public function __construct(string $text, iterable $parameters)
     {
         $this->text = $text;
-        $this->parameters = (new Map($parameters))->toArray();
+        $this->parameters = $parameters;
     }
 
     /**
@@ -44,9 +42,9 @@ public function getText(): string
     }
 
     /**
-     * @return array<string, scalar|iterable|null>
+     * @return iterable<string, scalar|iterable|null>
      */
-    public function getParameters(): array
+    public function getParameters(): iterable
     {
         return $this->parameters;
     }

src/Formatter/HttpCypherFormatter.php

@@ -21,6 +21,7 @@
 use Laudis\Neo4j\Databags\RequestData;
 use Laudis\Neo4j\Databags\Statement;
 use Laudis\Neo4j\Databags\StatementStatistics;
+use Laudis\Neo4j\ParameterHelper;
 use stdClass;
 
 /**
@@ -151,8 +152,8 @@ public function prepareBody(iterable $statements, RequestData $config): string
                 'resultDataContents' => ['ROW'],
                 'includeStats' => $config->includeStats(),
             ];
-            $parameters = $statement->getParameters();
-            $st['parameters'] = $parameters === [] ? new stdClass() : $parameters;
+            $parameters = ParameterHelper::formatParameters($statement->getParameters());
+            $st['parameters'] = $parameters->count() === 0 ? new stdClass() : $parameters->toArray();
             $tbr[] = $st;
         }
 

src/Network/Bolt/BoltSession.php

@@ -26,6 +26,7 @@
 use Laudis\Neo4j\Exception\Neo4jException;
 use Laudis\Neo4j\Formatter\BoltCypherFormatter;
 use Laudis\Neo4j\HttpDriver\Transaction;
+use Laudis\Neo4j\ParameterHelper;
 use Throwable;
 
 final class BoltSession implements SessionInterface
@@ -117,20 +118,19 @@ public function openTransaction(iterable $statements = null): TransactionInterfa
      */
     private function runStatements(iterable $statements, Bolt $bolt): Vector
     {
-        try {
-            $tbr = new Vector();
-            foreach ($statements as $statement) {
-                $extra = ['db' => $this->injections->database()];
-                /** @var array $parameters */
-                $parameters = $statement->getParameters();
+        $tbr = new Vector();
+        foreach ($statements as $statement) {
+            $extra = ['db' => $this->injections->database()];
+            $parameters = ParameterHelper::formatParameters($statement->getParameters());
+            try {
                 /** @var array{fields: array<int, string>} $meta */
-                $meta = $bolt->run($statement->getText(), $parameters, $extra);
+                $meta = $bolt->run($statement->getText(), $parameters->toArray(), $extra);
                 /** @var array<array> $results */
                 $results = $bolt->pullAll();
-                $tbr->push($this->formatter->formatResult($meta, $results));
+            } catch (Throwable $e) {
+                throw new Neo4jException(new Vector([new Neo4jError('', $e->getMessage())]), $e);
             }
-        } catch (Throwable $e) {
-            throw new Neo4jException(new Vector([new Neo4jError('', $e->getMessage())]), $e);
+            $tbr->push($this->formatter->formatResult($meta, $results));
         }
 
         return $tbr;

src/ParameterHelper.php

@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Laudis Neo4j package.
+ *
+ * (c) Laudis technologies <http://laudis.tech>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Laudis\Neo4j;
+
+use Ds\Map;
+use Ds\Sequence;
+use Ds\Vector;
+use InvalidArgumentException;
+use stdClass;
+
+final class ParameterHelper
+{
+    public static function asList(iterable $iterable): Sequence
+    {
+        return new Vector($iterable);
+    }
+
+    public static function asMap(iterable $iterable): Map
+    {
+        return new Map($iterable);
+    }
+
+    /**
+     * @param iterable|scalar|null $value
+     *
+     * @return iterable|scalar|stdClass|null
+     */
+    public static function asParameter($value)
+    {
+        if ($value instanceof Sequence && $value->count() === 0) {
+            return [];
+        }
+        if (($value instanceof Map && $value->count() === 0) ||
+            (is_array($value) && count($value) === 0)
+        ) {
+            return new stdClass();
+        }
+        if (is_iterable($value)) {
+            return self::iterableToArray($value);
+        }
+
+        return $value;
+    }
+
+    /**
+     * @param iterable<iterable|scalar|null> $parameters
+     *
+     * @return Map<array-key, iterable|scalar|stdClass|null>
+     */
+    public static function formatParameters(iterable $parameters): iterable
+    {
+        /** @var Map<array-key, iterable|scalar|stdClass|null> $tbr */
+        $tbr = new Map();
+        foreach ($parameters as $key => $value) {
+            if (!(is_int($key) || is_string($key))) {
+                $msg = 'The parameters must have an integer or string as key values, '.gettype($key).' received.';
+                throw new InvalidArgumentException($msg);
+            }
+            $tbr->put($key, self::asParameter($value));
+        }
+
+        return $tbr;
+    }
+
+    private static function iterableToArray(iterable $value): array
+    {
+        $tbr = [];
+        /**
+         * @var mixed $key
+         * @var mixed $val
+         */
+        foreach ($value as $key => $val) {
+            if (is_int($key) || is_string($key)) {
+                /** @psalm-suppress MixedAssignment */
+                $tbr[$key] = $val;
+            } else {
+                $msg = 'Iterable parameters must have an integer or string as key values, '.gettype($key).' received.';
+                throw new InvalidArgumentException($msg);
+            }
+        }
+
+        return $tbr;
+    }
+}

tests/Integration/ComplexQueryTests.php

@@ -13,8 +13,12 @@
 
 namespace Laudis\Neo4j\Tests\Integration;
 
+use Generator;
+use InvalidArgumentException;
 use Laudis\Neo4j\ClientBuilder;
 use Laudis\Neo4j\Contracts\ClientInterface;
+use Laudis\Neo4j\Exception\Neo4jException;
+use Laudis\Neo4j\ParameterHelper;
 use PHPUnit\Framework\TestCase;
 
 final class ComplexQueryTests extends TestCase
@@ -25,11 +29,106 @@ protected function setUp(): void
     {
         parent::setUp();
         $this->client = ClientBuilder::create()
-            ->addBoltConnection('bolt', 'bolt://neo4j:test@neo4j')
-            ->addHttpConnection('http', 'http://neo4j:test@neo4j')
+            ->addBoltConnection('bolt', 'bolt://neo4j:test@neo4j-42')
+            ->addHttpConnection('http', 'http://neo4j:test@neo4j-42')
             ->build();
     }
 
+    /**
+     * @dataProvider transactionProvider
+     */
+    public function testListParameterHelper(string $alias): void
+    {
+        $result = $this->client->run(<<<'CYPHER'
+MATCH (x) WHERE x.slug in $listOrMap RETURN x
+CYPHER, ['listOrMap' => ParameterHelper::asList([])], $alias);
+        self::assertEquals(0, $result->count());
+    }
+
+    /**
+     * @dataProvider transactionProvider
+     */
+    public function testValidListParameterHelper(string $alias): void
+    {
+        $result = $this->client->run(<<<'CYPHER'
+RETURN $listOrMap AS x
+CYPHER, ['listOrMap' => ParameterHelper::asList([1, 2, 3])], $alias);
+        self::assertEquals(1, $result->count());
+        self::assertEquals([1, 2, 3], $result->first()->get('x'));
+    }
+
+    /**
+     * @dataProvider transactionProvider
+     */
+    public function testValidMapParameterHelper(string $alias): void
+    {
+        $result = $this->client->run(<<<'CYPHER'
+RETURN $listOrMap AS x
+CYPHER, ['listOrMap' => ParameterHelper::asMap(['a' => 'b', 'c' => 'd'])], $alias);
+        self::assertEquals(1, $result->count());
+        self::assertEquals(['a' => 'b', 'c' => 'd'], $result->first()->get('x'));
+    }
+
+    /**
+     * @dataProvider transactionProvider
+     */
+    public function testMapParameterHelper(string $alias): void
+    {
+        $this->expectException(Neo4jException::class);
+
+        $this->client->run(<<<'CYPHER'
+MERGE (x:Node {slug: 'a'})
+WITH x
+MATCH (x) WHERE x.slug in $listOrMap RETURN x
+CYPHER, ['listOrMap' => ParameterHelper::asMap(['a' => 'b'])], $alias);
+    }
+
+    /**
+     * @dataProvider transactionProvider
+     */
+    public function testArrayParameterHelper(string $alias): void
+    {
+        $this->expectException(Neo4jException::class);
+        $this->client->run(<<<'CYPHER'
+MERGE (x:Node {slug: 'a'})
+WITH x
+MATCH (x) WHERE x.slug in $listOrMap RETURN x
+CYPHER, ['listOrMap' => []], $alias);
+    }
+
+    /**
+     * @dataProvider transactionProvider
+     */
+    public function testInvalidParameter(string $alias): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->client->run(<<<'CYPHER'
+MERGE (x:Node {slug: 'a'})
+WITH x
+MATCH (x) WHERE x.slug in $listOrMap RETURN x
+CYPHER, ['listOrMap' => self::generate()], $alias);
+    }
+
+    private static function generate(): Generator
+    {
+        foreach (range(1, 3) as $x) {
+            yield true => $x;
+        }
+    }
+
+    /**
+     * @dataProvider transactionProvider
+     */
+    public function testInvalidParameters(string $alias): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->client->run(<<<'CYPHER'
+MERGE (x:Node {slug: 'a'})
+WITH x
+MATCH (x) WHERE x.slug in $listOrMap RETURN x
+CYPHER, self::generate(), $alias);
+    }
+
     /**
      * @dataProvider transactionProvider
      */