feat: PHPStan extension inferring SQL return shapes

[marcreichel]

Summary

Adds a custom PHPStan extension that analyses the literal SQL string passed to the connection's query methods and narrows their return type to a constant array shape derived from the SELECT list. Also ships a custom rule that flags placeholder/parameter count mismatches.

The extension is shipped inside this package and auto-registered for downstream consumers via extra.phpstan.includes (picked up by phpstan/extension-installer). Consumers of artemeon/database get the improved types for free.

What's covered

• Connection::getPArray() → list<array{...}>
• Connection::getPRow() → array{}|array{...}
• Connection::getGenerator() → Generator<int, array{...}>
• PlaceholderCountRule: errors when literal ? count ≠ literal $params array length on getPArray, getPRow, getGenerator, _pQuery

Design choices

• Schema-agnostic: the extension only infers row shape (keys) from the SQL; all values are typed mixed. No DB connection or schema dump required.
• Parser: phpmyadmin/sql-parser (added to require so analysers downstream don't need to add it).
• Fallbacks: SELECT * → array<string, mixed>. Non-literal SQL, INSERT/UPDATE/DELETE, UNION, CTEs, and unparseable SQL silently keep the declared return type.
• Identifier handling: aliases preferred; otherwise the column name as written (backticks/double-quotes stripped, case preserved). JOIN column collisions: last occurrence wins.

Tests

• tests/PHPStan/SqlReturnShapeAnalyserTest.php — Pest tests on the analyser (8 cases).
• tests/PHPStan/PlaceholderCountRuleTest.php — PHPStan RuleTestCase.
• tests/PHPStan/data/return-types.php — assertType() fixture verifying the inferred return types end-to-end (run via tests/PHPStan/phpstan-fixtures.neon).

Baseline

phpstan-baseline.neon was regenerated. The newly-surfaced entries are real findings where existing test code accesses keys on getPRow() results without first checking the empty-row case — left in the baseline for incremental cleanup.

🤖 Generated with Claude Code