Merge pull request #71 from wgevaert/5.0.0-typing-and-consistency

minor improvements to 5.0.0 typing and consistency

Author: wgevaert

src/Expressions/Literals/Float_.php

@@ -48,6 +48,13 @@ public function getValue(): float
      */
     public function toQuery(): string
     {
-        return (string)$this->value;
+        $value = (string) $this->value;
+        if (
+            ctype_digit($value)
+            || ($value[0] === '-' && ctype_digit(substr($value,1)) )
+        ) {
+            $value .= '.0';
+        }
+        return $value;
     }
 }

src/Expressions/Literals/Integer.php

@@ -11,6 +11,7 @@
 
 use WikibaseSolutions\CypherDSL\Traits\TypeTraits\PropertyTypeTraits\IntegerTypeTrait;
 use WikibaseSolutions\CypherDSL\Types\PropertyTypes\IntegerType;
+use TypeError;
 
 /**
  * Represents an integer literal.
@@ -20,25 +21,40 @@ final class Integer implements IntegerType
     use IntegerTypeTrait;
 
     /**
-     * @var int The value
+     * @var string The value
      */
-    private int $value;
+    private string $value;
 
     /**
-     * @param int $value The value
+     * @param int|string $value The value
      * @internal This function is not covered by the backwards compatibility guarantee of php-cypher-dsl
      */
-    public function __construct(int $value)
+    public function __construct($value)
     {
-        $this->value = $value;
+        if (!is_int($value) && !is_string($value)) {
+            throw new TypeError('An integer should be given as a string or integer, '.gettype($value).' received.');
+        }
+        $parsedValue = filter_var($value, FILTER_SANITIZE_NUMBER_INT);
+
+        if (false === $parsedValue) {
+           throw new TypeError(
+               'A non-integer string has been provided: "'.$value.'".'
+           );
+        } elseif (is_string($value) && $parsedValue !== $value) {
+           throw new TypeError(
+               'A non-integer string has been provided: "'.$value.'", should be something like "'.$parsedValue.'".'
+           );
+        }
+
+        $this->value = $parsedValue;
     }
 
     /**
-     * Returns the integer value.
+     * Returns a string representation of the integer value.
      *
-     * @return int
+     * @return string
      */
-    public function getValue(): int
+    public function getValue(): string
     {
         return $this->value;
     }
@@ -48,6 +64,6 @@ public function getValue(): int
      */
     public function toQuery(): string
     {
-        return (string)$this->value;
+        return $this->value;
     }
 }

src/Expressions/Literals/Literal.php

@@ -69,8 +69,12 @@ public static function literal($literal)
             return array_is_list($literal) ? self::list($literal) : self::map($literal);
         }
 
+        if (is_object($literal) && method_exists($literal, '__toString')) {
+            return self::string($literal->__toString());
+        }
+
         throw new InvalidArgumentException(
-            "The literal type " . is_object($literal) ? get_class($literal) : gettype($literal) . " is not supported by Cypher"
+            "The literal type " . get_debug_type($literal) . " is not supported by Cypher"
         );
     }
 
@@ -153,8 +157,11 @@ public static function float(float $value): Float_
      * @param array $value
      * @return List_
      */
-    public static function list(array $value): List_
+    public static function list(iterable $value): List_
     {
+        if (is_object($value)) {
+            $value = iterator_to_array($value);
+        }
         return new List_(array_map([self::class, 'toAnyType'], $value));
     }
 

src/Expressions/Literals/Map.php

@@ -43,7 +43,7 @@ final class Map implements MapType
      */
     public function __construct(array $elements = [])
     {
-        self::assertClassArray('properties', AnyType::class, $elements);
+        self::assertClassArray('elements', AnyType::class, $elements);
         $this->elements = $elements;
     }
 

src/Expressions/Operators/ExclusiveOr.php renamed to src/Expressions/Operators/ExclusiveDisjunction.php

@@ -10,12 +10,12 @@
 namespace WikibaseSolutions\CypherDSL\Expressions\Operators;
 
 /**
- * Represents the application of the exclusive or (XOR) operator.
+ * Represents the application of the exclusive disjunction (XOR) operator.
  *
  * @see https://s3.amazonaws.com/artifacts.opencypher.org/openCypher9.pdf (page 50)
  * @see https://neo4j.com/docs/cypher-manual/current/syntax/operators/#query-operators-boolean
  */
-final class ExclusiveOr extends BooleanBinaryOperator
+final class ExclusiveDisjunction extends BooleanBinaryOperator
 {
     /**
      * @inheritDoc

src/Expressions/Operators/ModuloDivision.php

@@ -11,6 +11,7 @@
 
 /**
  * Represents the application of the modulo division (%) operator.
+ * This operator is sometimes simply called "modulo operator".
  *
  * @see https://s3.amazonaws.com/artifacts.opencypher.org/openCypher9.pdf (page 48)
  * @see https://neo4j.com/docs/cypher-manual/current/syntax/operators/#query-operators-mathematical

src/Patterns/Relationship.php

@@ -301,7 +301,7 @@ private function relationshipDetailToString(): string
 
         if (isset($this->properties)) {
             // Only add the properties if they're not empty
-            if (!$this->properties instanceof Map || $this->properties->getProperties() !== []) {
+            if (!$this->properties instanceof Map || $this->properties->getElements() !== []) {
                 $map = $this->properties->toQuery();
 
                 if ($conditionInner !== "") {

src/Query.php

@@ -48,6 +48,7 @@
 use WikibaseSolutions\CypherDSL\Patterns\Relationship;
 use WikibaseSolutions\CypherDSL\Syntax\Alias;
 use WikibaseSolutions\CypherDSL\Syntax\PropertyReplacement;
+use WikibaseSolutions\CypherDSL\Traits\CastTrait;
 use WikibaseSolutions\CypherDSL\Traits\ErrorTrait;
 use WikibaseSolutions\CypherDSL\Traits\EscapeTrait;
 use WikibaseSolutions\CypherDSL\Types\AnyType;
@@ -63,6 +64,7 @@ final class Query implements QueryConvertible
 {
     use EscapeTrait;
     use ErrorTrait;
+    use CastTrait;
 
     // A reference to the Literal class
     public const literal = Literal::class;
@@ -246,7 +248,7 @@ public static function float(float $value): Float_
      * @param array $value
      * @return List_
      */
-    public static function list(array $value): List_
+    public static function list(iterable $value): List_
     {
         return self::literal()::list($value);
     }
@@ -358,7 +360,7 @@ public function call($query = null, $variables = []): self
      * Creates the CALL procedure clause.
      *
      * @param Procedure $procedure The procedure to call
-     * @param string|Variable|Alias|string[]|Variable[]|Alias[] $yields The result fields that should be returned
+     * @param string|Variable|Alias|(string|Variable|Alias)[] $yields The result fields that should be returned
      *
      * @return $this
      *
@@ -370,6 +372,7 @@ public function callProcedure(Procedure $procedure, $yields = []): self
         if (!is_array($yields)) {
             $yields = [$yields];
         }
+        $yields = $this->makeAliasArray($yields, 'toName');
 
         $callProcedureClause = new CallProcedureClause();
         $callProcedureClause->setProcedure($procedure);
@@ -407,7 +410,7 @@ public function match($patterns): self
     /**
      * Creates the RETURN clause.
      *
-     * @param AnyType|Alias|Pattern|int|float|string|bool|array|AnyType[]|Alias[]|Pattern[]|int[]|float[]|string[]|bool[]|array[] $expressions The expressions to return
+     * @param AnyType|Alias|Pattern|int|float|string|bool|array|(AnyType|Alias|Pattern|int|float|string|bool|array)[] $expressions The expressions to return
      * @param bool $distinct Whether to be a RETURN DISTINCT query
      *
      * @return $this
@@ -420,9 +423,11 @@ public function returning($expressions, bool $distinct = false): self
         if (!is_array($expressions)) {
             $expressions = [$expressions];
         }
+        $expressions = $this->makeAliasArray($expressions);
 
         $returnClause = new ReturnClause();
         $returnClause->addColumn(...$expressions);
+
         $returnClause->setDistinct($distinct);
 
         $this->clauses[] = $returnClause;
@@ -482,7 +487,7 @@ public function delete($structures, bool $detach = false): self
     /**
      * Creates the DETACH DELETE clause.
      *
-     * @param StructuralType|Pattern|StructuralType[]|Pattern[] $variables The variables to delete, including relationships
+     * @param StructuralType|Pattern|(StructuralType|Pattern)[] $variables The variables to delete, including nodes, relationships and paths
      *
      * @return $this
      * @see https://neo4j.com/docs/cypher-manual/current/clauses/delete/
@@ -688,7 +693,7 @@ public function where($expressions, string $operator = WhereClause::AND): self
     /**
      * Creates the WITH clause.
      *
-     * @param AnyType|Alias|Pattern|int|float|string|bool|array|AnyType[]|Alias[]|Pattern[]|int[]|float[]|string[]|bool[]|array[] $expressions The entries to add; if the array-key is non-numerical, it is used as the alias
+     * @param AnyType|Alias|Pattern|int|float|string|bool|array|(AnyType|Alias|Pattern|int|float|string|bool|array)[] $expressions The entries to add; if the array-key is non-numerical, it is used as the alias
      *
      * @return $this
      *
@@ -700,6 +705,7 @@ public function with($expressions): self
         if (!is_array($expressions)) {
             $expressions = [$expressions];
         }
+        $expressions = $this->makeAliasArray($expressions);
 
         $withClause = new WithClause();
         $withClause->addEntry(...$expressions);
@@ -813,4 +819,23 @@ public function __toString(): string
     {
         return $this->build();
     }
+
+    /**
+     * Changes an associative array into an array of aliasses.
+     *
+     * @param  array   $array     The array to change into a sequential array
+     * @param  string  $castFunc  Name of the (static) method to use to cast the elements of $array.
+     * @return array   A sequential array, possibly consisting of aliasses.
+     */
+    private function makeAliasArray(array $array, string $castFunc = 'toAnyType'): array
+    {
+        if (array_is_list($array)) {
+            return array_map([self::class, $castFunc], $array);
+        }
+        $newArray = [];
+        foreach ($array as $key => $value) {
+            $newArray []= new Alias(call_user_func([self::class, $castFunc], $value), new Variable($key));
+        }
+        return $newArray;
+    }
 }

src/Traits/CastTrait.php

@@ -165,14 +165,14 @@ private static function toAnyType($value): AnyType
     {
         self::assertClass('value', [AnyType::class, Pattern::class, 'int', 'float', 'string', 'bool', 'array'], $value);
 
-        if ($value instanceof AnyType) {
-            return $value;
-        }
-
         if ($value instanceof Pattern) {
             return $value->getVariable();
         }
 
+        if ($value instanceof AnyType) {
+            return $value;
+        }
+
         return Literal::literal($value);
     }
 }

src/Traits/EscapeTrait.php

@@ -46,8 +46,8 @@ trait EscapeTrait
     private static function escape(string $name): string
     {
         if ($name === "") {
-            // Although some versions of Neo4j do not crash when the empty string is used as a name, there is no real
-            // reason to ever use the empty string as a name
+            // Although some versions of Neo4j do not crash when the empty string is used as a name,
+            // there is no real reason to ever use the empty string as a name
             throw new InvalidArgumentException("A name cannot be the empty string");
         }