test: Add PHPUnit harness and require PHP 8.1

.github/workflows/phpunit.yml

@@ -0,0 +1,159 @@
+name: Tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: PHP lint
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ["8.1", "8.2", "8.3", "8.4"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+      - name: Lint sources
+        run: find core/components/pdotools/src core/components/pdotools/elements -name '*.php' -exec php -l {} +
+
+  unit:
+    name: Unit
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ["8.1", "8.2", "8.3", "8.4"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+          tools: composer
+      - name: Install
+        working-directory: core/components/pdotools
+        run: composer install --no-interaction --prefer-dist
+      - name: Unit tests
+        working-directory: core/components/pdotools
+        run: composer test
+
+  integration:
+    name: Integration
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ["8.1", "8.2", "8.3", "8.4"]
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: modx
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping -h 127.0.0.1 -uroot -proot"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+    steps:
+      - uses: actions/checkout@v5
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: pdo_mysql, mysqli, gd, zip, json, xml, mbstring, curl, tokenizer
+          coverage: none
+          tools: composer
+      - name: Install package deps
+        working-directory: core/components/pdotools
+        run: composer install --no-interaction --prefer-dist
+      - name: Download MODX 3.2.4-pl
+        run: |
+          curl -fsSL -o modx.zip https://modx.s3.amazonaws.com/releases/3.2.4/modx-3.2.4-pl.zip
+          unzip -q modx.zip
+          mv modx-3.2.4-pl modx
+          rm modx.zip
+      - name: Install MODX (CLI)
+        working-directory: modx
+        run: |
+          MODX_ROOT="${GITHUB_WORKSPACE}/modx"
+          cat > setup/config.xml <<XML
+          <modx>
+            <database_type>mysql</database_type>
+            <database_server>127.0.0.1</database_server>
+            <database>modx</database>
+            <database_user>root</database_user>
+            <database_password>root</database_password>
+            <database_connection_charset>utf8mb4</database_connection_charset>
+            <database_charset>utf8mb4</database_charset>
+            <database_collation>utf8mb4_unicode_ci</database_collation>
+            <table_prefix>modx_</table_prefix>
+            <https_port>443</https_port>
+            <http_host>localhost</http_host>
+            <inplace>0</inplace>
+            <unpacked>0</unpacked>
+            <language>en</language>
+            <cmsadmin>admin</cmsadmin>
+            <cmspassword>AdminAdmin1</cmspassword>
+            <cmsadminemail>admin@example.com</cmsadminemail>
+            <core_path>${MODX_ROOT}/core/</core_path>
+            <context_mgr_path>${MODX_ROOT}/manager/</context_mgr_path>
+            <context_mgr_url>/manager/</context_mgr_url>
+            <context_connectors_path>${MODX_ROOT}/connectors/</context_connectors_path>
+            <context_connectors_url>/connectors/</context_connectors_url>
+            <context_web_path>${MODX_ROOT}/</context_web_path>
+            <context_web_url>/</context_web_url>
+            <remove_setup_directory>0</remove_setup_directory>
+          </modx>
+          XML
+          sed -i 's/^[[:space:]]*//' setup/config.xml
+          php setup/index.php --installmode=new --config="${MODX_ROOT}/setup/config.xml"
+          test -f core/config/config.inc.php
+          test -f config.core.php
+      - name: Enable package auto-install
+        run: sed -i "s/const PKG_AUTO_INSTALL = false;/const PKG_AUTO_INSTALL = true;/" _build/build.config.php
+      - name: Build and install transport
+        run: php _build/ci-install-package.php
+      - name: Integration tests
+        working-directory: core/components/pdotools
+        env:
+          MODX_TEST_BASE: ${{ github.workspace }}/modx/
+        run: composer test:integration
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.2"
+          coverage: pcov
+          tools: composer
+      - name: Install
+        working-directory: core/components/pdotools
+        run: composer install --no-interaction --prefer-dist
+      - name: Unit coverage
+        working-directory: core/components/pdotools
+        run: composer test:coverage
+      - name: Upload HTML report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: core/components/pdotools/coverage/html
+      - name: Upload to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: core/components/pdotools/coverage/clover.xml
+          fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/release.yml

@@ -61,11 +61,11 @@ jobs:
         working-directory: core/components/pdotools
         run: composer install --no-dev --no-interaction --prefer-dist
 
-      - name: Download MODX 3.0.5-pl
+      - name: Download MODX 3.2.4-pl
         run: |
-          curl -fsSL -o modx.zip https://modx.s3.amazonaws.com/releases/3.0.5/modx-3.0.5-pl.zip
+          curl -fsSL -o modx.zip https://modx.s3.amazonaws.com/releases/3.2.4/modx-3.2.4-pl.zip
           unzip -q modx.zip
-          mv modx-3.0.5-pl modx
+          mv modx-3.2.4-pl modx
           rm modx.zip
 
       - name: Install MODX (CLI)

.gitignore

@@ -2,3 +2,6 @@ config.core.php
 .idea
 node_modules
 /core/components/pdotools/vendor/
+/core/components/pdotools/.phpunit.cache
+/core/components/pdotools/coverage/
+/core/components/pdotools/tests/tmp/

README.md

@@ -1,11 +1,33 @@
 ## pdoTools
 
-pdoTools 3 is a set of everyday [MODX Revolution](https://modx.com/) 3 snippets plus a small library that keeps them fast. Queries are built with xPDO and run through PDO. Elements can live in the database or in files. Tickets and [MiniShop3](https://github.com/modx-pro/MiniShop3) use it.
+[![Tests](https://github.com/modx-pro/pdoTools3/actions/workflows/phpunit.yml/badge.svg)](https://github.com/modx-pro/pdoTools3/actions/workflows/phpunit.yml)
+[![PHP](https://img.shields.io/badge/php-8.1%20%7C%208.2%20%7C%208.3%20%7C%208.4-777BB4)](https://github.com/modx-pro/pdoTools3/actions/workflows/phpunit.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/modx-pro/pdoTools3)](https://codecov.io/gh/modx-pro/pdoTools3)
 
-This branch requires **MODX 3** and **PHP 7.2+**. For MODX 2 use [pdoTools 2.x](https://github.com/modx-pro/pdoTools).
+pdoTools 3 is a set of everyday [MODX Revolution](https://modx.com/) 3 snippets plus a small library that keeps them fast. Queries are built with xPDO and run through PDO. Elements can live in the database or in files. [MiniShop3](https://github.com/modx-pro/MiniShop3) use it.
+
+This branch requires **MODX 3** and **PHP 8.1+**. For MODX 2 use [pdoTools 2.x](https://github.com/modx-pro/pdoTools).
 
 **Documentation:** [docs.modx.pro/components/pdotools](https://docs.modx.pro/components/pdotools/)
 
+### Tests
+
+From `core/components/pdotools`:
+
+```bash
+composer install
+composer test
+```
+
+Integration tests need a live MODX 3 tree (CI installs 3.2.4-pl and the transport with `PKG_AUTO_INSTALL=true`):
+
+```bash
+export MODX_TEST_BASE=/path/to/modx/
+composer test:integration
+```
+
+Coverage (pcov or xdebug): `composer test:coverage`. HTML report lands in `coverage/html`.
+
 ### Advantages
 
 Every pdoTools snippet shares the same core:

_build/build.transport.php

@@ -165,7 +165,7 @@
     'license' => file_get_contents($sources['docs'] . 'license.txt'),
     'readme' => file_get_contents($sources['docs'] . 'readme.txt'),
     'requires' => [
-        'php' => '>=7.2.0',
+        'php' => '>=8.1.0',
         'modx' => '>=3.0.0-beta',
     ],
 ]);

_build/ci-install-package.php

@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * Builds the transport package against a CLI-installed MODX tree.
+ * Used by .github/workflows/phpunit.yml so the workflow has no inline php -r.
+ */
+$workspace = getenv('GITHUB_WORKSPACE');
+if ($workspace === false || $workspace === '') {
+    fwrite(STDERR, "GITHUB_WORKSPACE is not set\n");
+    exit(1);
+}
+
+$_SERVER['MODX_BASE_PATH'] = rtrim($workspace, '/') . '/modx/';
+require $workspace . '/_build/build.transport.php';

codecov.yml

@@ -0,0 +1,11 @@
+comment:
+  require_changes: true
+
+coverage:
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        informational: true

core/components/pdotools/bootstrap.php

@@ -1,7 +1,9 @@
 <?php
 /** @var MODX\Revolution\modX $modx */
 
-require_once MODX_CORE_PATH . 'components/pdotools/vendor/autoload.php';
+if (!class_exists(\ModxPro\PdoTools\CoreTools::class)) {
+    require_once MODX_CORE_PATH . 'components/pdotools/vendor/autoload.php';
+}
 
 // Add factories
 $modx->services[ModxPro\PdoTools\CoreTools::class] = $modx->services->factory(function ($c) use ($modx) {

core/components/pdotools/composer.json

@@ -16,17 +16,42 @@
         }
     ],
     "type": "library",
-    "minimum-stability": "dev",
+    "minimum-stability": "stable",
+    "prefer-stable": true,
     "autoload": {
         "psr-4": {
             "ModxPro\\PdoTools\\": "src/"
         }
     },
+    "autoload-dev": {
+        "psr-4": {
+            "ModxPro\\PdoTools\\Tests\\": "tests/"
+        }
+    },
     "require": {
-        "php": ">=7.2",
+        "php": ">=8.1",
         "fenom/fenom": "^2.11"
     },
     "require-dev": {
-        "modx/revolution": "3.x-dev"
+        "phpunit/phpunit": "^9.6",
+        "modx/revolution": "3.2.4-pl"
+    },
+    "config": {
+        "platform": {
+            "php": "8.1.31"
+        },
+        "audit": {
+            "block-insecure": false,
+            "ignore": [
+                "PKSA-7k8y-pxvq-y5kc",
+                "GHSA-674v-3g2w-84gx"
+            ]
+        }
+    },
+    "scripts": {
+        "test": "phpunit --configuration phpunit.xml.dist --testsuite Unit",
+        "test:integration": "phpunit --configuration phpunit.xml.dist --testsuite Integration",
+        "test:all": "phpunit --configuration phpunit.xml.dist",
+        "test:coverage": "phpunit --configuration phpunit.xml.dist --testsuite Unit --coverage-clover coverage/clover.xml --coverage-html coverage/html"
     }
 }