Merge branch 'main' into 5.0.0-typing-and-consistency

Author: marijnvanwezel

README.md

@@ -27,30 +27,13 @@ composer require "wikibase-solutions/php-cypher-dsl"
 To construct a query to find all of Tom Hanks' co-actors, you can use the following code:
 
 ```php
-$tom = Query::variable("tom");
-$tomNode = Query::node("Person")->withProperties([
-	"name" => Query::literal("Tom Hanks")
-])->named($tom);
-
-$movie = Query::variable("m");
-$movieNode = Query::node()->named($movie);
-
-$coActors = Query::variable("coActors");
-$coActorsNode = Query::node()->named($coActors);
+$tom = Query::node("Person")->withProperties(["name" => Query::literal("Tom Hanks")]);
+$coActors = Query::node();
 
 $statement = Query::new()
-	->match($tomNode->relationshipTo($movieNode)->withType("ACTED_IN")->relationshipFrom($coActorsNode)->withType("ACTED_IN"))
-	->returning($coActors->property("name"))
-	->build();
+    ->match($tom->relationshipTo(Query::node(), "ACTED_IN")->relationshipFrom($coActors, "ACTED_IN"))
+    ->returning($coActors->property("name"))
+    ->build();
 
-$this->assertSame("MATCH (tom:Person {name: 'Tom Hanks'})-[:`ACTED_IN`]->(m)<-[:`ACTED_IN`]-(coActors) RETURN coActors.name", $statement);
+$this->assertStringMatchesFormat("MATCH (:Person {name: 'Tom Hanks'})-[:`ACTED_IN`]->()<-[:`ACTED_IN`]-(%s) RETURN %s.name", $statement);
 ```
-
-## Roadmap
-
-Below are some things that still need to be implemented.
-
-- Add missing clauses
-- Add missing function definitions
-- Add missing expressions
-- Improve documentation

src/Traits/EscapeTrait.php

@@ -21,7 +21,9 @@
 
 namespace WikibaseSolutions\CypherDSL\Traits;
 
-use InvalidArgumentException;
+use function preg_match;
+use function sprintf;
+use function str_replace;
 
 /**
  * Trait for encoding certain structures that are used in multiple clauses in a
@@ -30,25 +32,31 @@
 trait EscapeTrait
 {
     /**
-     * Escapes the given 'name'. A name is an unquoted literal in a Cypher query, such as variables,
-     * types or property names.
+     * Escapes a 'name' if it needs to be escaped.
+     * @see https://neo4j.com/docs/cypher-manual/4.4/syntax/naming
+     * A 'name' in cypher is any string that should be included directly in a cypher query,
+     * such as variable names, labels, property names and relation types
      *
      * @param string $name
      * @return string
      */
     private static function escape(string $name): string
     {
-        if ($name === "") {
-            return "";
-        }
-
-        if (ctype_alnum($name) && !ctype_digit($name)) {
+        if (preg_match('/^\p{L}[\p{L}\d_]*$/u', $name)) {
             return $name;
         }
 
-        if (strpos($name, '`') !== false) {
-            throw new InvalidArgumentException("A name must not contain a backtick (`)");
-        }
+        return self::escapeRaw($name);
+    }
+
+    /**
+     * Escapes the given $name to be used directly in a CYPHER query.
+     * Note: according to https://github.com/neo4j/neo4j/issues/12901 backslashes might give problems in some Neo4j versions.
+     */
+    public static function escapeRaw($name)
+    {
+        // Escape backticks that are included in $name by doubling them.
+        $name = str_replace('`', '``', $name);
 
         return sprintf("`%s`", $name);
     }

tests/Unit/Expressions/ParameterTest.php

@@ -68,10 +68,7 @@ public function provideThrowsExceptionOnInvalidData(): array
     {
         return [
             [""],
-            ["@"],
-            ["!"],
-            ["-"],
-            [''],
+            [str_repeat('a', 65535)],
         ];
     }
 }

tests/Unit/Patterns/NodeTest.php

@@ -21,7 +21,6 @@
 
 namespace WikibaseSolutions\CypherDSL\Tests\Unit\Patterns;
 
-use InvalidArgumentException;
 use PHPUnit\Framework\TestCase;
 use TypeError;
 use WikibaseSolutions\CypherDSL\Expressions\Literals\Number;
@@ -44,13 +43,19 @@ public function testEmptyNode(): void
         $this->assertSame("()", $node->toQuery());
     }
 
-    public function testBacktickThrowsException(): void
+    // Further tests can be found in Traits/EscapeTraitTest
+    public function testBacktickIsEscaped(): void
     {
         $node = new Node();
 
+<<<<<<< HEAD
         $this->expectException(InvalidArgumentException::class);
         $this->expectDeprecationMessage('A name can only contain alphanumeric characters and underscores');
         $node->withVariable('abcdr`eer');
+=======
+        $node->named('abcdr`eer');
+        $this->assertEquals('(`abcdr``eer`)', $node->toQuery());
+>>>>>>> main
     }
 
     /**

tests/Unit/Traits/EscapeTraitTest.php

@@ -21,7 +21,6 @@
 
 namespace WikibaseSolutions\CypherDSL\Tests\Unit\Traits;
 
-use InvalidArgumentException;
 use PHPUnit\Framework\TestCase;
 use WikibaseSolutions\CypherDSL\Traits\EscapeTrait;
 
@@ -66,58 +65,29 @@ public function testUnsafeValueIsEscaped(string $value)
         $this->assertSame($expected, $actual);
     }
 
-    public function testValueWithBacktickThrowsException()
-    {
-        $this->expectException(InvalidArgumentException::class);
-
-        $this->trait->escape("foo`bar");
-    }
-
     public function provideSafeValueIsNotEscapedData(): array
     {
         return [
             ['foobar'],
             ['fooBar'],
             ['FOOBAR'],
+            ['foo_bar'],
+            ['FOO_BAR'],
             ['aaa'],
-            ['bbb'],
-            ['ccc'],
-            ['ddd'],
-            ['eee'],
-            ['fff'],
-            ['ggg'],
-            ['hhh'],
-            ['iii'],
-            ['jjj'],
-            ['kkk'],
-            ['lll'],
-            ['mmm'],
-            ['nnn'],
-            ['ooo'],
-            ['ppp'],
-            ['qqq'],
-            ['rrr'],
-            ['sss'],
-            ['ttt'],
-            ['uuu'],
-            ['vvv'],
-            ['www'],
-            ['xxx'],
-            ['yyy'],
-            ['zzz'],
-            [''],
             ['aaa100'],
             ['a0'],
             ['z10'],
             ['z99'],
+            ['ça'],
+            ['日'],
         ];
     }
 
     public function provideUnsafeValueIsEscapedData(): array
     {
         return [
-            ['foo_bar'],
-            ['FOO_BAR'],
+            [''],
+            ['__FooBar__'],
             ['_'],
             ['__'],
             ['\''],
@@ -129,4 +99,23 @@ public function provideUnsafeValueIsEscapedData(): array
             ['2'],
         ];
     }
+
+    /**
+     * @dataProvider provideValueWithBacktickIsProperlyEscapedData
+     */
+    public function testValueWithBacktickIsProperlyEscaped($input, $expected)
+    {
+        $this->assertSame('`foo``bar`', $this->trait->escape("foo`bar"));
+    }
+
+    public function provideValueWithBacktickIsProperlyEscapedData(): array
+    {
+        return [
+            ['foo`bar','`foo``bar`'],
+            ['`foo','```foo`'],
+            ['foo`','`foo```'],
+            ['foo``bar','`foo````bar`'],
+            ['`foo`','```foo```'],
+        ];
+    }
 }