Merge pull request #256 from neo4j-php/feat/testkit

feat: Bring Back Initial Testkit Support

Author: transistive

.github/workflows/testkit.yml

@@ -0,0 +1,78 @@
+name: Testkit Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    name: "Run Testkit Tests"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Restore Neo4j Image Cache if it exists
+        id: cache-docker-neo4j
+        uses: actions/cache@v4
+        with:
+          path: ci/cache/docker/neo4j
+          key: cache-docker-neo4j-5-enterprise
+
+      - name: Update Neo4j Image Cache if cache miss
+        if: steps.cache-docker-neo4j.outputs.cache-hit != 'true'
+        run: |
+          docker pull neo4j:5-enterprise
+          mkdir -p ci/cache/docker/neo4j
+          docker image save neo4j:5-enterprise --output ./ci/cache/docker/neo4j/neo4j-5-enterprise.tar
+
+      - name: Use Neo4j Image Cache if cache hit
+        if: steps.cache-docker-neo4j.outputs.cache-hit == 'true'
+        run: docker image load --input ./ci/cache/docker/neo4j/neo4j-5-enterprise.tar
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Build & cache client image
+        uses: docker/build-push-action@v3
+        with:
+          context: .
+          file: Dockerfile
+          load: true
+          push: false
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: PHP_VERSION=8.1
+          tags: integration-client:8.1
+
+      - name: Populate .env
+        run: |
+          echo "PHP_VERSION=8.1" > .env
+          echo "CONNECTION=neo4j://neo4j:testtest@server1" >> .env
+
+      - name: Cache PHP deps
+        id: cache-php-deps
+        uses: actions/cache@v4
+        with:
+          path: vendor
+          key: ${{ runner.os }}-php-8.1-${{ hashFiles('**/composer.json') }}
+          restore-keys: |
+            ${{ runner.os }}-php-8.1-
+
+      - name: Install PHP deps
+        if: steps.cache-php-deps.outputs.cache-hit != 'true'
+        run: |
+          docker compose run --rm client composer install
+
+      - name: Run integration tests
+        run: |
+          docker compose up -d --remove-orphans --wait --no-build \
+            server1 \
+            server2 \
+            server3 \
+            server4 \
+            testkit_backend
+
+          docker compose run --rm testkit ./testkit.sh

.gitignore

@@ -14,3 +14,4 @@ composer.lock
 /docs/_build
 cachegrind.out.*
 .phpunit.cache/
+/testkit-backend/testkit/

.php-cs-fixer.dist.php

@@ -33,7 +33,8 @@
 try {
     $finder = PhpCsFixer\Finder::create()
         ->in(__DIR__.'/src')
-        ->in(__DIR__.'/tests');
+        ->in(__DIR__.'/tests')
+        ->in(__DIR__.'/testkit-backend');
 } catch (Throwable $e) {
     echo $e->getMessage()."\n";
 

composer.json

@@ -57,7 +57,8 @@
         "cache/integration-tests": "dev-master",
         "kubawerlos/php-cs-fixer-custom-fixers": "3.13.*",
         "rector/rector": "^1.0",
-        "psr/log": "^3.0"
+        "psr/log": "^3.0",
+        "php-di/php-di": "^6.3"
     },
     "autoload": {
         "psr-4": {
@@ -66,7 +67,8 @@
     },
     "autoload-dev": {
         "psr-4": {
-            "Laudis\\Neo4j\\Tests\\": "tests/"
+            "Laudis\\Neo4j\\Tests\\": "tests/",
+            "Laudis\\Neo4j\\TestkitBackend\\": "testkit-backend/src"
         }
     },
     "minimum-stability": "stable",
@@ -81,6 +83,7 @@
     },
     "scripts": {
         "fix-cs": "./vendor/bin/php-cs-fixer fix",
+        "check-cs": "./vendor/bin/php-cs-fixer fix --dry-run",
         "psalm": "./vendor/bin/psalm"
     }
 }

docker-compose.yml

@@ -65,6 +65,8 @@ services:
       NEO4J_server_bolt_advertised__address: neo4j:7687
       NEO4J_server_http_advertised__address: neo4j:7474
 
+
+
   server1:
     <<: *common-cluster
     hostname: server1
@@ -113,3 +115,32 @@ services:
       NEO4J_initial_server_mode__constraint: 'SECONDARY'
       NEO4J_server_bolt_advertised__address: server4:7687
       NEO4J_server_http_advertised__address: server4:7474
+
+  testkit:
+    image: python:3.13
+    volumes:
+      - .:/opt/project
+    working_dir: /opt/project/testkit-backend
+    networks:
+      - neo4j
+    environment:
+      TEST_NEO4J_HOST: neo4j
+      TEST_NEO4J_USER: neo4j
+      TEST_NEO4J_PASS: testtest
+      TEST_DRIVER_NAME: php
+      TEST_DRIVER_REPO: /opt/project
+      TEST_BACKEND_HOST: testkit_backend
+
+  testkit_backend:
+    <<: *common-php
+    environment:
+      PHP_IDE_CONFIG: "serverName=myserver"
+    command: php -d xdebug.mode=debug -d xdebug.start_with_request=yes -d xdebug.client_host=host.docker.internal ./testkit-backend/index.php
+    networks:
+      - neo4j
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    depends_on:
+      - neo4j
+    ports:
+      - "9876:9876"

src/Bolt/BoltConnection.php

@@ -38,6 +38,7 @@
 use Psr\Http\Message\UriInterface;
 use Psr\Log\LogLevel;
 use Throwable;
+use Traversable;
 use WeakReference;
 
 /**
@@ -209,12 +210,14 @@ public function reset(): void
      * Begins a transaction.
      *
      * Any of the preconditioned states are: 'READY', 'INTERRUPTED'.
+     *
+     * @param iterable<string, scalar|array|null>|null $txMetaData
      */
-    public function begin(?string $database, ?float $timeout, BookmarkHolder $holder): void
+    public function begin(?string $database, ?float $timeout, BookmarkHolder $holder, ?iterable $txMetaData): void
     {
         $this->consumeResults();
 
-        $extra = $this->buildRunExtra($database, $timeout, $holder, AccessMode::WRITE());
+        $extra = $this->buildRunExtra($database, $timeout, $holder, AccessMode::WRITE(), $txMetaData);
         $message = $this->messageFactory->createBeginMessage($extra);
         $response = $message->send()->getResponse();
         $this->assertNoFailure($response);
@@ -248,8 +251,9 @@ public function run(
         ?float $timeout,
         BookmarkHolder $holder,
         ?AccessMode $mode,
+        ?iterable $tsxMetadata,
     ): array {
-        $extra = $this->buildRunExtra($database, $timeout, $holder, $mode);
+        $extra = $this->buildRunExtra($database, $timeout, $holder, $mode, $tsxMetadata);
         $message = $this->messageFactory->createRunMessage($text, $parameters, $extra);
         $response = $message->send()->getResponse();
         $this->assertNoFailure($response);
@@ -327,7 +331,7 @@ public function close(): void
         }
     }
 
-    private function buildRunExtra(?string $database, ?float $timeout, BookmarkHolder $holder, ?AccessMode $mode): array
+    private function buildRunExtra(?string $database, ?float $timeout, BookmarkHolder $holder, ?AccessMode $mode, ?iterable $metadata): array
     {
         $extra = [];
         if ($database !== null) {
@@ -345,6 +349,13 @@ private function buildRunExtra(?string $database, ?float $timeout, BookmarkHolde
             $extra['mode'] = AccessMode::WRITE() === $mode ? 'w' : 'r';
         }
 
+        if ($metadata !== null) {
+            $metadataArray = $metadata instanceof Traversable ? iterator_to_array($metadata) : $metadata;
+            if (count($metadataArray) > 0) {
+                $extra['tx_metadata'] = $metadataArray;
+            }
+        }
+
         return $extra;
     }
 

src/Bolt/BoltUnmanagedTransaction.php

@@ -138,7 +138,8 @@ public function runStatement(Statement $statement): SummarizedResult
                 $this->database,
                 $this->tsxConfig->getTimeout(),
                 $this->bookmarkHolder,
-                $this->config->getAccessMode()
+                $this->config->getAccessMode(),
+                $this->tsxConfig->getMetaData()
             );
         } catch (Throwable $e) {
             $this->state = TransactionState::TERMINATED;

src/Bolt/Session.php

@@ -188,7 +188,7 @@ private function startTransaction(TransactionConfiguration $config, SessionConfi
         try {
             $connection = $this->acquireConnection($config, $sessionConfig);
 
-            $connection->begin($this->config->getDatabase(), $config->getTimeout(), $this->bookmarkHolder);
+            $connection->begin($this->config->getDatabase(), $config->getTimeout(), $this->bookmarkHolder, $config->getMetaData());
         } catch (Neo4jException $e) {
             if (isset($connection) && $connection->getServerState() === 'FAILED') {
                 $connection->reset();

src/Databags/ServerInfo.php

@@ -61,7 +61,7 @@ public function toArray(): array
     {
         return [
             'address' => $this->address,
-            'protocol' => $this->protocol,
+            'protocolVersion' => $this->protocol,
             'agent' => $this->agent,
         ];
     }

src/Types/CypherMap.php

@@ -572,8 +572,9 @@ public function getAsWGS843DPoint(string $key): WGS843DPoint
 
     public function key(): string
     {
-        /** @var string */
-        return $this->cacheKey();
+        // we have to cast to a string, as the value is potentially an integer if the key is numeric:
+        // https://stackoverflow.com/questions/4100488/a-numeric-string-as-array-key-in-php
+        return (string) $this->cacheKey();
     }
 
     /**