Rewrite additional clauses and unit tests

Author: marijnvanwezel

.github/SECURITY.md

@@ -6,7 +6,7 @@
 
 If you discover a security vulnerability within php-cypher-dsl, please send an e-mail to Marijn van Wezel at [email protected]. All security vulnerabilities will be promptly addressed.
 
-You may optionally encrypt your report with GPG, using the following key (fingerprint: `98ED 96AA 2260 D7E3`, proof: [keybase.io](https://keybase.io/01101101)):
+You may optionally encrypt your report with PGP, using the following key (fingerprint: `98ED96AA2260D7E3`, proof: [keybase.io](https://keybase.io/01101101)):
 
 ```text
 -----BEGIN PGP PUBLIC KEY BLOCK-----

src/Clauses/CallClause.php

@@ -19,7 +19,7 @@
  * This class represents a CALL {} (subquery) clause. The CALL {} clause evaluates a subquery that returns
  * some values.
  *
- * @note This feature is not officially part of the openCypher standard. For more information, see https://github.com/opencypher/openCypher/blob/a507292d35280aca9e37bf938cdec4fdd1e64ba9/docs/standardisation-scope.adoc.
+ * @note This feature is not part of the openCypher standard. For more information, see https://github.com/opencypher/openCypher/blob/a507292d35280aca9e37bf938cdec4fdd1e64ba9/docs/standardisation-scope.adoc.
  *
  * @see https://neo4j.com/docs/cypher-manual/current/clauses/call-subquery/
  * @see Query::call() for a more convenient method to construct this class

src/Clauses/CallProcedureClause.php

@@ -1,159 +1,89 @@
-<?php
-
+<?php declare(strict_types=1);
 /*
- * Cypher DSL
- * Copyright (C) 2021  Wikibase Solutions
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License
- * as published by the Free Software Foundation; either version 2
- * of the License, or (at your option) any later version.
+ * This file is part of php-cypher-dsl.
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * Copyright (C) 2021-  Wikibase Solutions
  *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
  */
-
 namespace WikibaseSolutions\CypherDSL\Clauses;
 
+use WikibaseSolutions\CypherDSL\Expressions\Procedures\Procedure;
 use WikibaseSolutions\CypherDSL\Expressions\Variable;
+use WikibaseSolutions\CypherDSL\Traits\CastTrait;
 use WikibaseSolutions\CypherDSL\Traits\ErrorTrait;
 use WikibaseSolutions\CypherDSL\Traits\EscapeTrait;
-use WikibaseSolutions\CypherDSL\Types\AnyType;
-use WikibaseSolutions\CypherDSL\Types\PropertyTypes\PropertyType;
 
 /**
- * This class represents a CALL procedure clause. The CALL clause is used to call a procedure deployed in the database.
+ * This class represents a CALL procedure clause.
+ *
+ * The CALL clause is used to call a procedure deployed in the database.
  *
  * @see https://s3.amazonaws.com/artifacts.opencypher.org/openCypher9.pdf (page 122)
  * @see https://neo4j.com/docs/cypher-manual/current/clauses/call/
  * @see Query::callProcedure() for a more convenient method to construct this class
  */
-class CallProcedureClause extends Clause
+final class CallProcedureClause extends Clause
 {
+    use CastTrait;
     use EscapeTrait;
     use ErrorTrait;
 
     /**
-     * @var string|null The procedure to call
+     * @var Procedure|null The procedure to call
      */
-    private ?string $procedure = null;
+    private ?Procedure $procedure = null;
 
     /**
-     * @var PropertyType[] The arguments passed to the procedure
-     */
-    private array $arguments = [];
-
-    /**
-     * @var Variable[] The result fields that will be returned
+     * @var Variable[] The result fields that yielded
      */
     private array $yields = [];
 
     /**
-     * Sets the procedure to call. This can be for instance "apoc.load.json".
+     * Sets the procedure to call.
      *
-     * @param string $procedure The procedure to call
+     * @param Procedure $procedure The procedure to call
      * @return $this
      */
-    public function setProcedure(string $procedure): self
+    public function setProcedure(Procedure $procedure): self
     {
         $this->procedure = $procedure;
 
         return $this;
     }
 
     /**
-     * Sets the literal arguments to pass to this procedure call. This overwrites any previously passed
-     * arguments.
+     * Adds a variable to yield.
      *
-     * @param AnyType[] $arguments The arguments to pass to the procedure
-     * @return $this
-     */
-    public function setArguments(array $arguments): self
-    {
-        foreach ($arguments as $argument) {
-            $this->assertClass('arguments', AnyType::class, $argument);
-        }
-
-        $this->arguments = $arguments;
-
-        return $this;
-    }
-
-    /**
-     * Add a literal argument to pass to this procedure call.
+     * TODO: Allow variables to be aliased
      *
-     * @param AnyType $argument The argument to pass to the procedure
+     * @param Variable|string $yields The variable to yield
      * @return $this
      */
-    public function addArgument(AnyType $argument): self
+    public function addYield(...$yields): self
     {
-        $this->arguments[] = $argument;
+        $res = [];
 
-        return $this;
-    }
-
-    /**
-     * Used to explicitly select which available result fields are returned as newly-bound
-     * variables. If a key is non-numerical, it will be used as an alias.
-     *
-     * @param Variable[] $variables
-     * @return $this
-     */
-    public function setYields(array $variables): self
-    {
-        foreach ($variables as $variable) {
-            $this->assertClass('variables', Variable::class, $variable);
+        foreach ($yields as $yield) {
+            $res[] = self::toName($yield);
         }
 
-        $this->yields = $variables;
-
-        return $this;
-    }
-
-    /**
-     * Adds a variable to yield.
-     *
-     * @param Variable $variable The variable to yield
-     * @param string|null $alias Optionally the alias to use for the variable
-     * @return $this
-     */
-    public function addYield(Variable $variable, ?string $alias = null): self
-    {
-        if ($alias !== null) {
-            $this->yields[$alias] = $variable;
-        } else {
-            $this->yields[] = $variable;
-        }
+        $this->yields = array_merge($this->yields, $res);
 
         return $this;
     }
 
     /**
      * Returns the procedure to call.
      *
-     * @return string|null
+     * @return Procedure
      */
-    public function getProcedure(): ?string
+    public function getProcedure(): ?Procedure
     {
         return $this->procedure;
     }
 
-    /**
-     * Returns the arguments of the procedure.
-     *
-     * @return AnyType[]
-     */
-    public function getArguments(): array
-    {
-        return $this->arguments;
-    }
-
     /**
      * Returns the variables to yield.
      *
@@ -181,27 +111,13 @@ protected function getSubject(): string
             return "";
         }
 
-        $procedure = implode(
-            '.',
-            array_map(fn (string $part): string => $this->escape($part), explode('.', $this->procedure))
-        );
-
-        $arguments = implode(
-            ", ",
-            array_map(fn (AnyType $pattern): string => $pattern->toQuery(), $this->arguments)
-        );
-
-        if (count($this->yields) > 0) {
-            $yieldParameters = [];
-            foreach ($this->yields as $alias => $yieldVariable) {
-                $yieldParameters[] = is_int($alias) ?
-                    $yieldVariable->toQuery() :
-                    sprintf("%s AS %s", $yieldVariable->toQuery(), $this->escape($alias));
-            }
-
-            return sprintf("%s(%s) YIELD %s", $procedure, $arguments, implode(", ", $yieldParameters));
+        $subject = $this->procedure->toQuery();
+
+        if (!empty($this->yields)) {
+            $yields = array_map(fn (Variable $variable): string => $variable->toQuery(), $this->yields);
+            $subject .= sprintf(" YIELD %s", implode(", ", $yields));
         }
 
-        return sprintf("%s(%s)", $procedure, $arguments);
+        return $subject;
     }
 }

src/Clauses/CreateClause.php

@@ -1,82 +1,53 @@
-<?php
-
+<?php declare(strict_types=1);
 /*
- * Cypher DSL
- * Copyright (C) 2021  Wikibase Solutions
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License
- * as published by the Free Software Foundation; either version 2
- * of the License, or (at your option) any later version.
+ * This file is part of php-cypher-dsl.
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * Copyright (C) 2021-  Wikibase Solutions
  *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
  */
-
 namespace WikibaseSolutions\CypherDSL\Clauses;
 
-use WikibaseSolutions\CypherDSL\Patterns\Node;
-use WikibaseSolutions\CypherDSL\Patterns\Path;
+use WikibaseSolutions\CypherDSL\Patterns\CompletePattern;
 use WikibaseSolutions\CypherDSL\Query;
 use WikibaseSolutions\CypherDSL\Traits\ErrorTrait;
 
 /**
- * This class represents a CREATE clause. The CREATE clause is used to create graph elements.
+ * This class represents a CREATE clause.
+ *
+ * The CREATE clause is used to create graph elements — nodes and relationships.
  *
  * @see https://s3.amazonaws.com/artifacts.opencypher.org/openCypher9.pdf (page 99)
  * @see https://neo4j.com/docs/cypher-manual/current/clauses/create/
  * @see Query::create() for a more convenient method to construct this class
  */
-class CreateClause extends Clause
+final class CreateClause extends Clause
 {
     use ErrorTrait;
 
     /**
-     * @var Path[]|Node[] The patterns to create
+     * @var CompletePattern[] The patterns to create
      */
     private array $patterns = [];
 
     /**
-     * Sets the pattern to create. This overwrites any previously added patterns.
-     *
-     * @param Path[]|Node[] $patterns The patterns to put in the CREATE clause
-     * @return $this
-     */
-    public function setPatterns(array $patterns): self
-    {
-        foreach ($patterns as $pattern) {
-            $this->assertClass('patterns', [Path::class, Node::class], $pattern);
-        }
-
-        $this->patterns = $patterns;
-
-        return $this;
-    }
-
-    /**
-     * Add a pattern to create.
+     * Add one or more patterns to create.
      *
-     * @param Path|Node $pattern The pattern to add to the CREATE clause
+     * @param CompletePattern ...$pattern The patterns to add to the CREATE clause
      * @return $this
      */
-    public function addPattern($pattern): self
+    public function addPattern(CompletePattern ...$pattern): self
     {
-        $this->assertClass('pattern', [Path::class, Node::class], $pattern);
-        $this->patterns[] = $pattern;
+        $this->patterns = array_merge($this->patterns, $pattern);
 
         return $this;
     }
 
     /**
      * Returns the patterns of the CREATE clause.
      *
-     * @return Path[]|Node[]
+     * @return CompletePattern[]
      */
     public function getPatterns(): array
     {
@@ -96,6 +67,9 @@ protected function getClause(): string
      */
     protected function getSubject(): string
     {
-        return implode(", ", array_map(fn ($pattern): string => $pattern->toQuery(), $this->patterns));
+        return implode(
+            ", ",
+            array_map(fn (CompletePattern $pattern): string => $pattern->toQuery(), $this->patterns)
+        );
     }
 }

src/Clauses/LimitClause.php

@@ -16,6 +16,8 @@
 /**
  * This class represents a LIMIT clause.
  *
+ * LIMIT constrains the number of records in the output.
+ *
  * @see https://neo4j.com/docs/cypher-manual/current/clauses/limit/
  * @see https://s3.amazonaws.com/artifacts.opencypher.org/openCypher9.pdf (page 98)
  * @see Query::limit() for a more convenient method to construct this class