Merge pull request #100 from neo4j-php/89-use-php-80-union-types

Upgrade to PHP 8.1

Author: marijnvanwezel

.github/CONTRIBUTING.md

@@ -37,7 +37,7 @@ Feel free to propose a new feature by [opening an issue for it](https://github.c
 
 1. Fork the repository.
 1. Create a new branch.
-   1. If you are **implementing new functionality**, create your branch from `development`.
+   1. If you are **implementing new functionality**, create your branch from `main`.
    1. If you are **fixing a bug**, create your branch from the oldest [supported](https://github.com/neo4j-php/php-cypher-dsl/blob/main/LIFECYCLE.md) branch that is affected by the bug.
 1. Implement your change and add tests for it.
 1. Make sure the test suite passes.
@@ -50,18 +50,6 @@ Some things to keep in mind:
 * Keep backwards compatibility breaks to a minimum.
 * You are encouraged to [sign your commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) with GPG.
 
-## Branching model
-
-The branching model used by this project is [gitflow](https://nvie.com/posts/a-successful-git-branching-model/), with the following changes/additions:
-
-1. Feature branches must follow the naming convention `feature/*`.
-1. The name of a feature branch should reflect the feature added (e.g. `feature/support-indexing-operator` instead of `feature/feature-1`).
-1. Release branches must follow the naming convention `release/x.y`, where `x` and `y` are the major and minor version of the release respectively. A release branch should never be made for a patch.
-1. Hotfix branches must follow the naming convention `hotfix/x.y.z`, where `x`, `y` and `z` are the major, minor and patch version of the hot respectively. 
-1. Hotfix branches must branch off from the oldest [supported](https://github.com/neo4j-php/php-cypher-dsl/blob/main/LIFECYCLE.md) branch that is affected by the bug.
-1. Right before a new **major** version is released, a *support* branch is created from `main`.
-1. Support branches must follow the naming convention `support/x.y`, where `x` and `y` are the major and minor version of the most recent release respectively.
-
 ## Coding guidelines
 
 This project comes with a [configuration file](https://github.com/neo4j-php/php-cypher-dsl/blob/main/.php-cs-fixer.dist.php) for `php-cs-fixer` that you can use to format your code:
@@ -81,7 +69,7 @@ After making your changes and adding your tests, you can check whether the minim
 ```
 $ XDEBUG_MODE=coverage php vendor/bin/phpunit --testsuite unit
 $ php vendor/bin/coverage-check coverage/clover.xml 90
-$ XDEBUG_MODE=coverage php vendor/bin/infection --min-msi=80
+$ XDEBUG_MODE=coverage php vendor/bin/infection --min-msi=85
 ```
 
 ## Running test suites

.github/workflows/test.yml

@@ -14,13 +14,13 @@ jobs:
 
     strategy:
       matrix:
-        php-version: [ "7.4", "8.0", "8.1", "8.2" ]
+        php-version: [ "8.1", "8.2", "8.3", "8.4", "8.5" ]
 
     env:
       COMPOSER_VERSION: 2
       COVERAGE_DRIVER: xdebug
       MINIMUM_COVERAGE_PERCENTAGE: 90
-      MINIMUM_MSI_PERCENTAGE: 80
+      MINIMUM_MSI_PERCENTAGE: 85
 
     steps:
       - name: Checkout repository

CHANGELOG.md

@@ -6,6 +6,24 @@ file. A changelog has been kept from version 5.0.0 onwards.
 The format is based on [Keep a Changelog], and this project adheres to
 [Semantic Versioning].
 
+## 7.0.0 - T.B.D.
+
+### Changed
+
+- Changed the minimum required PHP version to 8.1.
+- Changed the signature of many functions to use PHP 8 union types.
+- Changed the `Relationship::DIR_*` to the `Direction` enum.
+
+### Removed
+
+- Removed unnecessary dependency for the `openssl` PHP library.
+- Removed `ErrorTrait` in favor of PHP 8.0 union types.
+- Removed `CastTrait` in favor of the static functions in `CastUtils`.
+- Removed `NameGenerationTrait` in favor of the static functions in `NameUtils`.
+- Removed `EscapeTrait` in favor of the static functions in `NameUtils`.
+- Removed `Relationship::DIR_UNI`, `Relationship::DIR_LEFT` and `Relationship::DIR_RIGHT` constants
+  in favor of the `Direction` enum.
+
 ## 6.0.0 - 2023-09-19
 
 ### Changed

LIFECYCLE.md

@@ -16,7 +16,8 @@ loss and/or corruption.
 
 ## Supported versions
 
-| Major version    | PHP version | Initial release | End of bugfix support |
-|------------------|-------------|-----------------|-----------------------|
-| php-cypher-dsl 5 | >=7.4    | Jan 9th, 2023   | Mar 19th, 2024        |
-| php-cypher-dsl 6 | >=7.4    | Sep 19th, 2023  | To be determined      |
+| Major version    | PHP version | Initial release   | End of bugfix support |
+|------------------|-------------|-------------------|-----------------------|
+| php-cypher-dsl 5 | >=7.4    | Jan 9th, 2023     | Mar 19th, 2024        |
+| php-cypher-dsl 6 | >=7.4    | Sep 19th, 2023    | To be determined      |
+| php-cypher-dsl 7 | >=8.1    | To be determined  | To be determined      |

README.md

@@ -1,24 +1,20 @@
 # php-cypher-dsl
 
-The `php-cypher-dsl` library provides a way to construct advanced Cypher
-queries in an object-oriented and type-safe manner.
+The `php-cypher-dsl` library provides a way to construct Cypher queries in a type-safe manner.
 
 ## Documentation
 
-[The documentation can be found on the wiki
-here.](https://github.com/WikibaseSolutions/php-cypher-dsl/wiki)
+[The documentation can be found on the wiki here.](https://github.com/WikibaseSolutions/php-cypher-dsl/wiki)
 
 ## Installation
 
 ### Requirements
 
-`php-cypher-dsl` requires PHP 7.4 or greater; using the latest version of PHP
-is highly recommended.
+`php-cypher-dsl` requires PHP 8.1 or greater; using the latest version of PHP is highly recommended.
 
 ### Installation through Composer
 
-You can install `php-cypher-dsl` through composer by running the following
-command:
+You can install `php-cypher-dsl` through Composer by running the following command:
 
 ```
 composer require "wikibase-solutions/php-cypher-dsl"
@@ -30,8 +26,7 @@ Please refer to [CONTRIBUTING.md](https://github.com/neo4j-php/php-cypher-dsl/bl
 
 ## Example
 
-To construct a query to find all of Tom Hanks' co-actors, you can use the
-following code:
+To construct a query to find all of Tom Hanks' co-actors, you can use the following code:
 
 ```php
 use function WikibaseSolutions\CypherDSL\node;
@@ -41,7 +36,13 @@ $tom = node("Person")->withProperties(["name" => "Tom Hanks"]);
 $coActors = node();
 
 $statement = query()
-    ->match($tom->relationshipTo(Query::node(), "ACTED_IN")->relationshipFrom($coActors, "ACTED_IN"))
+    ->match($tom->relationshipTo(node(), "ACTED_IN")->relationshipFrom($coActors, "ACTED_IN"))
     ->returning($coActors->property("name"))
     ->build();
 ```
+
+This produces the following Cypher query (where `$1` is a random variable name):
+
+```
+MATCH (:Person {name: 'Tom Hanks'})-[:ACTED_IN]->()<-[:ACTED_IN]-($1) RETURN $1.name
+```

composer.json

@@ -1,6 +1,6 @@
 {
   "name": "wikibase-solutions/php-cypher-dsl",
-  "description": "A query builder for the Cypher query language written in PHP",
+  "description": "A query builder for the Cypher query language",
   "type": "library",
   "keywords": [
     "neo4j",
@@ -46,18 +46,15 @@
     "source": "https://github.com/WikibaseSolutions/php-cypher-dsl"
   },
   "require": {
-    "php": ">=7.4",
-    "ext-ctype": "*",
-    "ext-openssl": "*",
-    "symfony/polyfill-php80": "^1.25",
-    "symfony/polyfill-php81": "^1.25"
+    "php": ">=8.1",
+    "ext-ctype": "*"
   },
   "require-dev": {
-    "phpunit/phpunit": "~9.0",
-    "infection/infection": "^0.25.5",
+    "phpunit/phpunit": "^10.0",
+    "infection/infection": "^0.29",
     "friendsofphp/php-cs-fixer": "^3.0",
     "rregeer/phpunit-coverage-check": "^0.3.1",
-    "phpstan/phpstan": "^1.8"
+    "phpstan/phpstan": "^2.0"
   },
   "autoload": {
     "files": [

phpstan.neon.dist

@@ -1,5 +1,10 @@
 parameters:
   paths:
     - src
-  level: 7
-  treatPhpDocTypesAsCertain: false
+  level: 9
+  treatPhpDocTypesAsCertain: false
+  ignoreErrors:
+    - "#Method [a-zA-Z0-9\\_\\\\:\\(\\)]+ has parameter \\$[a-zA-Z0-9_]+ with no value type specified in iterable type array#"
+    - "#Function [a-zA-Z0-9\\_\\\\:\\(\\)]+ has parameter \\$[a-zA-Z0-9_]+ with no value type specified in iterable type array#"
+    - "#Method [a-zA-Z0-9\\_\\\\:\\(\\)]+ has parameter \\$[a-zA-Z0-9_]+ with no value type specified in iterable type iterable#"
+    - "#Method [a-zA-Z0-9\\_\\\\:\\(\\)]+ return type has no value type specified in iterable type array#"

phpunit.xml.dist

@@ -1,7 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit colors="true" verbose="true"
+<phpunit colors="true"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         displayDetailsOnTestsThatTriggerDeprecations="true"
+         displayDetailsOnTestsThatTriggerErrors="true"
+         displayDetailsOnTestsThatTriggerNotices="true"
+         displayDetailsOnTestsThatTriggerWarnings="true"
+         displayDetailsOnPhpunitDeprecations="true"
          bootstrap="vendor/autoload.php"
 >
     <testsuites>
@@ -15,16 +20,18 @@
             <directory>tests/integration</directory>
         </testsuite>
     </testsuites>
-    <coverage processUncoveredFiles="true" cacheDirectory="coverage/cache" pathCoverage="true">
-        <report>
-            <clover outputFile="coverage/clover.xml" />
-            <html outputDirectory="coverage/" />
-        </report>
+    <source>
         <include>
             <directory suffix=".php">src</directory>
         </include>
         <exclude>
             <file>src/functions.php</file>
         </exclude>
+    </source>
+    <coverage cacheDirectory="coverage/cache" pathCoverage="true">
+        <report>
+            <clover outputFile="coverage/clover.xml" />
+            <html outputDirectory="coverage/" />
+        </report>
     </coverage>
 </phpunit>

src/Clauses/CallClause.php

@@ -12,8 +12,7 @@
 use WikibaseSolutions\CypherDSL\Expressions\Variable;
 use WikibaseSolutions\CypherDSL\Patterns\Pattern;
 use WikibaseSolutions\CypherDSL\Query;
-use WikibaseSolutions\CypherDSL\Traits\CastTrait;
-use WikibaseSolutions\CypherDSL\Traits\ErrorTrait;
+use WikibaseSolutions\CypherDSL\Utils\CastUtils;
 
 /**
  * This class represents a CALL {} (subquery) clause. The CALL {} clause evaluates a subquery that returns
@@ -26,9 +25,6 @@
  */
 final class CallClause extends Clause
 {
-    use CastTrait;
-    use ErrorTrait;
-
     /**
      * @var null|Query The sub-query to call, or NULL if no sub-query has been set yet
      */
@@ -56,18 +52,14 @@ public function withSubQuery(Query $subQuery): self
     /**
      * Add one or more variables to include in the WITH clause.
      *
-     * @param Pattern|string|Variable ...$variables
-     *
-     * @return $this
-     *
      * @see https://neo4j.com/docs/cypher-manual/current/clauses/call-subquery/#subquery-correlated-importing
      */
-    public function addWithVariable(...$variables): self
+    public function addWithVariable(Pattern|Variable|string ...$variables): self
     {
         $res = [];
 
         foreach ($variables as $variable) {
-            $res[] = self::toVariable($variable);
+            $res[] = CastUtils::toVariable($variable);
         }
 
         $this->withVariables = array_merge($this->withVariables, $res);

src/Clauses/CallProcedureClause.php

@@ -12,7 +12,7 @@
 use WikibaseSolutions\CypherDSL\Expressions\Procedures\Procedure;
 use WikibaseSolutions\CypherDSL\Expressions\Variable;
 use WikibaseSolutions\CypherDSL\Syntax\Alias;
-use WikibaseSolutions\CypherDSL\Traits\CastTrait;
+use WikibaseSolutions\CypherDSL\Utils\CastUtils;
 
 /**
  * This class represents a CALL procedure clause.
@@ -25,24 +25,20 @@
  */
 final class CallProcedureClause extends Clause
 {
-    use CastTrait;
-
     /**
      * @var null|Procedure The procedure to call
      */
     private ?Procedure $procedure = null;
 
     /**
-     * @var Alias[]|Variable[]|(Alias|Variable)[] The result fields that are yielded
+     * @var Alias[]|(Alias|Variable)[]|Variable[] The result fields that are yielded
      */
     private array $yields = [];
 
     /**
      * Sets the procedure to call.
      *
      * @param Procedure $procedure The procedure to call
-     *
-     * @return $this
      */
     public function setProcedure(Procedure $procedure): self
     {
@@ -55,15 +51,13 @@ public function setProcedure(Procedure $procedure): self
      * Adds a variable to yield.
      *
      * @param Alias|string|Variable $yields The variable to yield
-     *
-     * @return $this
      */
     public function addYield(...$yields): self
     {
         $res = [];
 
         foreach ($yields as $yield) {
-            $res[] = $yield instanceof Alias ? $yield : self::toName($yield);
+            $res[] = $yield instanceof Alias ? $yield : CastUtils::toName($yield);
         }
 
         $this->yields = array_merge($this->yields, $res);
@@ -73,8 +67,6 @@ public function addYield(...$yields): self
 
     /**
      * Returns the procedure to call.
-     *
-     * @return Procedure
      */
     public function getProcedure(): ?Procedure
     {
@@ -84,7 +76,7 @@ public function getProcedure(): ?Procedure
     /**
      * Returns the variables to yield.
      *
-     * @return Alias[]|Variable[]|(Alias|Variable)[]
+     * @return (Alias|Variable)[]
      */
     public function getYields(): array
     {