Merge branch 'name-generation' into name-generation

Author: transistive

src/Alias.php

@@ -5,25 +5,31 @@
 use WikibaseSolutions\CypherDSL\Types\AnyType;
 use function sprintf;
 
+/**
+ * Represents aliasing an expression or variable.
+ *
+ * @see https://neo4j.com/docs/cypher-manual/current/clauses/return/#return-column-alias
+ * @see https://neo4j.com/docs/cypher-manual/current/clauses/with/#with-introduce-variables
+ */
 class Alias implements AnyType
 {
     /**
-     * @var QueryConvertable The original item to be aliased
+     * @var AnyType The original item to be aliased
      */
-    private QueryConvertable $original;
+    private AnyType $original;
 
     /**
      * @var Variable The new variable aliasing the original
      */
     private Variable $variable;
 
     /**
-     * BinaryOperator constructor.
+     * Alias constructor.
      *
-     * @param QueryConvertable $original The original item to be aliased
+     * @param AnyType $original The original item to be aliased
      * @param Variable $variable The new variable aliasing the original
      */
-    public function __construct(QueryConvertable $original, Variable $variable)
+    public function __construct(AnyType $original, Variable $variable)
     {
         $this->original = $original;
         $this->variable = $variable;
@@ -40,9 +46,9 @@ public function toQuery(): string
     /**
      * Gets the original item of the alias.
      *
-     * @return QueryConvertable
+     * @return AnyType
      */
-    public function getOriginal(): QueryConvertable
+    public function getOriginal(): AnyType
     {
         return $this->original;
     }

src/AndOperator.php

@@ -21,7 +21,6 @@
 
 namespace WikibaseSolutions\CypherDSL;
 
-use WikibaseSolutions\CypherDSL\Traits\AliasableTrait;
 use WikibaseSolutions\CypherDSL\Traits\BooleanTypeTrait;
 use WikibaseSolutions\CypherDSL\Types\PropertyTypes\BooleanType;
 

src/Literals/Boolean.php

@@ -31,7 +31,6 @@
 class Boolean implements BooleanType
 {
     use BooleanTypeTrait;
-    use AliasableTrait;
 
     /**
      * @var bool The value

src/Literals/Decimal.php

@@ -31,7 +31,6 @@
 class Decimal implements NumeralType
 {
     use NumeralTypeTrait;
-    use AliasableTrait;
 
     /**
      * @var string The value

src/Literals/StringLiteral.php

@@ -34,7 +34,6 @@
 class StringLiteral implements StringType
 {
     use StringTypeTrait;
-    use AliasableTrait;
 
     /**
      * @var string

src/Patterns/Node.php

@@ -67,6 +67,8 @@ public function getLabels(): array
     }
 
     /**
+     * Adds a label to the node.
+     *
      * @param string $label
      * @return Node
      */
@@ -108,6 +110,13 @@ public function toQuery(): string
         return "($nodeInner)";
     }
 
+    /**
+     * Returns a property on the node.
+     *
+     * @param string $property The name of the property.
+     *
+     * @return Property
+     */
     public function property(string $property): Property
     {
         return new Property($this->getName(), $property);

src/Patterns/Path.php

@@ -39,18 +39,32 @@ public function __construct($nodes = null, $relationships = null)
         $this->relationships = is_array($relationships) ? array_values($relationships) : [$relationships];
     }
 
+    /**
+     * @inheritDoc
+     */
     public function toQuery(): string
     {
+        // If there are no nodes in the path, it must be empty.
         if (count($this->nodes) === 0) {
             return '';
         }
 
         $cql = '';
+        // If a variable exists, we need to assign following the expression to it
         if ($this->getVariable() !== null) {
             $cql = $this->getName()->toQuery() . ' = ';
         }
 
+        // We use the relationships as a reference point to iterate over.
+        // The nodes position will be calculated using the index of the current relationship.
+        // If R is the position of the relationship, N is the position of te node, and x the amount of relationships
+        // in the path, then the positional structure is like this:
+        // N0 - R0 - N1 - R1 - N2 - ... - Nx - Rx - N(x + 1)
         foreach ($this->relationships as $i => $relationship) {
+            // To avoid a future crash, we already look for the node at the end of the relationship.
+            // If the following node does not exist, we must break the loop early.
+            // This case will be triggered if the amount of nodes is equal or less than the amount of relationships
+            // and is thus very unlikely.
             if (!array_key_exists($i + 1, $this->nodes)) {
                 --$i;
                 break;
@@ -59,6 +73,10 @@ public function toQuery(): string
             $cql .= $relationship->toQuery();
         }
 
+        // Since the iteration leaves us at the final relationship, we still need to add the final node.
+        // If the path is simply a single node, $i won't be defined, hence the null coalescing operator with -1. By
+        // coalescing with -1 instead of 0, we remove the need of a separate if check, making both cases valid when they
+        // are incremented by 1.
         $cql .= $this->nodes[($i ?? -1) + 1]->toQuery();
 
         return $cql;
@@ -84,6 +102,9 @@ public function getRelationships(): array
         return $this->relationships;
     }
 
+    /**
+     * @inheritDoc
+     */
     public function relationship(RelationshipType $relationship, NodeType $node): Path
     {
         $this->relationships[] = $relationship;
@@ -92,20 +113,29 @@ public function relationship(RelationshipType $relationship, NodeType $node): Pa
         return $this;
     }
 
+    /**
+     * @inheritDoc
+     */
     public function relationshipTo(NodeType $node, ?string $type = null, $properties = null, $name = null): Path
     {
         $relationship = $this->buildRelationship(Relationship::DIR_RIGHT, $type, $properties, $name);
 
         return $this->relationship($relationship, $node);
     }
 
+    /**
+     * @inheritDoc
+     */
     public function relationshipFrom(NodeType $node, ?string $type = null, $properties = null, $name = null): Path
     {
         $relationship = $this->buildRelationship(Relationship::DIR_LEFT, $type, $properties, $name);
 
         return $this->relationship($relationship, $node);
     }
 
+    /**
+     * @inheritDoc
+     */
     public function relationshipUni(NodeType $node, ?string $type = null, $properties = null, $name = null): Path
     {
         $relationship = $this->buildRelationship(Relationship::DIR_UNI, $type, $properties, $name);

src/Patterns/Relationship.php

@@ -26,7 +26,7 @@
 use LogicException;
 use WikibaseSolutions\CypherDSL\Property;
 use WikibaseSolutions\CypherDSL\Traits\EscapeTrait;
-use WikibaseSolutions\CypherDSL\Traits\RelationshipTrait;
+use WikibaseSolutions\CypherDSL\Traits\RelationshipTypeTrait;
 use WikibaseSolutions\CypherDSL\Types\StructuralTypes\RelationshipType;
 
 /**
@@ -38,7 +38,7 @@
 class Relationship implements RelationshipType
 {
     use EscapeTrait;
-    use RelationshipTrait;
+    use RelationshipTypeTrait;
 
     public const DIR_RIGHT = ["-", "->"];
     public const DIR_LEFT = ["<-", "-"];

src/RawExpression.php

@@ -31,7 +31,7 @@
 use WikibaseSolutions\CypherDSL\Traits\MapTypeTrait;
 use WikibaseSolutions\CypherDSL\Traits\NodeTypeTrait;
 use WikibaseSolutions\CypherDSL\Traits\NumeralTypeTrait;
-use WikibaseSolutions\CypherDSL\Traits\RelationshipTrait;
+use WikibaseSolutions\CypherDSL\Traits\RelationshipTypeTrait;
 use WikibaseSolutions\CypherDSL\Traits\PointTrait;
 use WikibaseSolutions\CypherDSL\Traits\StringTypeTrait;
 use WikibaseSolutions\CypherDSL\Traits\TimeTrait;
@@ -78,7 +78,7 @@ class RawExpression implements
     use PointTrait;
     use NodeTypeTrait;
     use NumeralTypeTrait;
-    use RelationshipTrait;
+    use RelationshipTypeTrait;
     use StringTypeTrait;
     use TimeTrait;
     use AliasableTrait;
@@ -90,7 +90,7 @@ class RawExpression implements
 
     /**
      * RawExpression constructor.
-     *\
+     *
      * @param string $expression The raw expression
      */
     public function __construct(string $expression)

src/Traits/BooleanTypeTrait.php

@@ -33,6 +33,7 @@
 trait BooleanTypeTrait
 {
     use PropertyTypeTrait;
+    use AliasableTrait;
 
     /**
      * Create a conjunction between this expression and the given expression.