feat(ci): add staabm/phpstan-dba to type-check raw SQL (#1100)

Wires phpstan-dba into the existing PHPStan gate so column renames,
schema drift, and statement-syntax bugs in `Database::query(...)` calls
fail static analysis instead of waiting for runtime. The CI job spins up
schema-only MariaDB, renders `web/install/includes/sql/struc.sql` the
same way `docker/db-init/00-render-schema.sh` does locally, and points
the bootstrap at it. `DBA_REQUIRE=1` keeps the gate from silently
disabling itself on a creds drift.

The project's `:prefix_<table>` placeholder convention is handled by
`SbppPrefixAwareReflector` (resolves `:prefix` -> `sb` before the SQL
hits MariaDB) and `SbppSyntaxErrorInQueryMethodRule` (replacement for
phpstan-dba's built-in rule, which short-circuits on placeholder
counting and would skip every query in this codebase). Bound values
live in follow-up `bind()` calls out of scope, so we stub `:name` and
`?` placeholders with neutral literals and validate structure only —
table/column existence and SQL syntax — which is the bug class the
issue calls out.

Surfaced and fixed one shipped bug along the way: `Log.php`'s
`case "date":` arm was building `... AND l.created :valueOther`,
missing the comparison operator, so the admin log page threw
SQLSTATE 42000 whenever someone filtered by date. The new rule
flags it as a syntax error; the fix is a one-character `<`.

Disable locally with `PHPSTAN_DBA_DISABLE=1`. Bootstrap also
soft-fails if the DB is unreachable so a fresh checkout without
`./sbpp.sh up` keeps working.

Author: rumblefrog

.github/workflows/phpstan.yml

@@ -19,14 +19,35 @@ jobs:
     defaults:
       run:
         working-directory: web
+
+    # Schema-only MariaDB so phpstan-dba (#1100) can introspect column types.
+    # Mirrors test.yml's service block deliberately — same image, same creds —
+    # so a contributor's mental model of "MariaDB lives at 127.0.0.1:3306" works
+    # for both jobs.
+    services:
+      mariadb:
+        image: mariadb:10.11
+        ports:
+          - 3306:3306
+        env:
+          MARIADB_ROOT_PASSWORD: root
+          MARIADB_DATABASE: sourcebans
+          MARIADB_USER: sourcebans
+          MARIADB_PASSWORD: sourcebans
+        options: >-
+          --health-cmd="healthcheck.sh --connect --innodb_initialized"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=10
+
     steps:
       - uses: actions/checkout@v4
 
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
           php-version: '8.2'
-          extensions: pdo, openssl, gmp, mbstring, sodium
+          extensions: pdo, pdo_mysql, openssl, gmp, mbstring, sodium
           coverage: none
           tools: composer:v2
 
@@ -44,5 +65,42 @@ jobs:
       - name: Install dependencies
         run: composer install --no-progress --prefer-dist --no-interaction
 
+      - name: Wait for MariaDB
+        run: |
+          for i in {1..30}; do
+            if mysqladmin ping -h 127.0.0.1 -P 3306 -u root -proot --silent; then
+              echo "ready"; exit 0
+            fi
+            sleep 2
+          done
+          echo "MariaDB never came up" >&2; exit 1
+
+      # phpstan-dba doesn't execute queries, but it does call
+      # information_schema for column metadata, so the schema needs to be
+      # loaded against the same DB the bootstrap connects to. Render the
+      # `{prefix}` / `{charset}` placeholders the same way docker/db-init
+      # does locally so we can't drift.
+      - name: Render and load schema for phpstan-dba
+        run: |
+          tmp=$(mktemp)
+          sed -e 's/{prefix}/sb/g' -e 's/{charset}/utf8mb4/g' \
+              install/includes/sql/struc.sql > "$tmp"
+          mysql -h 127.0.0.1 -u root -proot sourcebans < "$tmp"
+          # Sanity check: a known table should now exist.
+          mysql -h 127.0.0.1 -u root -proot sourcebans -e 'SHOW TABLES LIKE "sb_admins"' \
+            | grep -q sb_admins
+
       - name: Run PHPStan
+        env:
+          DBA_HOST: 127.0.0.1
+          DBA_PORT: 3306
+          DBA_NAME: sourcebans
+          DBA_USER: sourcebans
+          DBA_PASS: sourcebans
+          DBA_PREFIX: sb
+          DBA_CHARSET: utf8mb4
+          # The whole point of the new MariaDB service is to gate schema drift.
+          # Refuse to run if the bootstrap can't connect — otherwise a creds
+          # mismatch would silently disable phpstan-dba and CI would stay green.
+          DBA_REQUIRE: '1'
         run: includes/vendor/bin/phpstan analyse --no-progress --error-format=github --memory-limit=1G

docker/README.md

@@ -67,6 +67,35 @@ don't leak onto the host filesystem.
 ./sbpp.sh rebuild                 # `--no-cache` rebuild of the web image
 ```
 
+## Static analysis with phpstan-dba
+
+`./sbpp.sh phpstan` runs PHPStan inside the web container with
+[`staabm/phpstan-dba`](https://github.com/staabm/phpstan-dba) wired up against
+the running `db` service. The wrapper exports `DBA_HOST=db` (plus `DBA_USER`,
+`DBA_PASS`, `DBA_NAME`, `DBA_PREFIX`) so `web/phpstan-dba-bootstrap.php` can
+introspect the live schema and type-check raw SQL strings — column names,
+table names, and statement syntax in every `Database::query(...)` call get
+validated against `web/install/includes/sql/struc.sql` as it would be loaded
+by the seed script.
+
+To skip the DBA pass (useful when the DB container is down or you're
+iterating on unrelated rules), set `PHPSTAN_DBA_DISABLE=1`:
+
+```sh
+PHPSTAN_DBA_DISABLE=1 ./sbpp.sh phpstan
+```
+
+The bootstrap also degrades gracefully if it can't reach the DB at all, so a
+fresh checkout without `./sbpp.sh up` won't break the gate — it just runs the
+non-DBA rules.
+
+CI mirrors this: `.github/workflows/phpstan.yml` spins up MariaDB 10.11,
+renders `struc.sql` (no `data.sql` — phpstan-dba only needs structure), and
+points the same env vars at it. Renaming or removing a column in `struc.sql`
+without updating its callers will fail the PHPStan job. CI also sets
+`DBA_REQUIRE=1` so a missing service or credentials drift fails the job
+loudly instead of silently disabling the SQL checks.
+
 ## How the bootstrap works
 
 1. **DB**: MariaDB only runs `/docker-entrypoint-initdb.d/*` on the **first**

sbpp.sh

@@ -83,7 +83,19 @@ case "$cmd" in
         # found" warnings disappear and triggers PHPStan's
         # `reportUnmatchedIgnoredErrors`. Stash config.php for the duration of
         # the analysis so locally we get the same result CI does.
-        dc exec web bash -lc '
+        #
+        # phpstan-dba (#1100) needs a live MariaDB to introspect schema; the
+        # dev `db` service is reachable from inside the web container as
+        # `db:3306`. Set PHPSTAN_DBA_DISABLE=1 to bypass when working
+        # offline — the bootstrap also degrades gracefully if the connection
+        # fails for any other reason.
+        dc exec \
+            -e DBA_HOST=db -e DBA_PORT=3306 \
+            -e DBA_NAME=sourcebans \
+            -e DBA_USER=sourcebans -e DBA_PASS=sourcebans \
+            -e DBA_PREFIX=sb -e DBA_CHARSET=utf8mb4 \
+            -e PHPSTAN_DBA_DISABLE="${PHPSTAN_DBA_DISABLE:-}" \
+            web bash -lc '
             cd /var/www/html/web
             cleanup() { [ -f config.php.devstash ] && mv config.php.devstash config.php; }
             trap cleanup EXIT

web/composer.json

@@ -34,9 +34,13 @@
             "Sbpp\\": "includes/"
         }
     },
+    "autoload-dev": {
+        "classmap": ["phpstan/"]
+    },
     "require-dev": {
         "phpstan/phpstan": "^2.1",
-        "phpunit/phpunit": "^11"
+        "phpunit/phpunit": "^11",
+        "staabm/phpstan-dba": "^0.4"
     },
     "scripts": {
         "test": "phpunit",