diff --git a/.editorconfig b/.editorconfig index d84f8aa6..0c291cef 100644 --- a/.editorconfig +++ b/.editorconfig @@ -10,3 +10,6 @@ trim_trailing_whitespace = true [*.{yml, yaml}] indent_size = 2 + +[phpstan-baseline.neon] +indent_style = tab diff --git a/.gitattributes b/.gitattributes index a2f21824..0517cf3d 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,7 +1,13 @@ /.* export-ignore /composer.lock export-ignore /phpcs.xml.dist export-ignore +/phpstan-baseline.neon export-ignore +/phpstan.neon.dist export-ignore /phpunit.xml.dist export-ignore /tests export-ignore /docs/specs export-ignore /CLAUDE.md export-ignore +/utils/db-prepare.sh export-ignore +/utils/SchemaDiff.php export-ignore +/utils/db-schema-diff.php export-ignore +/utils/db-schema-diff-accepted.txt export-ignore diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 32e03c63..c9bb8846 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -11,40 +11,46 @@ permissions: jobs: tests: - name: PHP ${{ matrix.php }} Test + name: PHP ${{ matrix.php }}, ${{ matrix.db }} runs-on: ubuntu-latest strategy: + fail-fast: false matrix: - php: ['8.1', '8.2', '8.3', '8.4', '8.5'] - + # Every PHP version on the current MariaDB LTS; the newest PHP also on the + # oldest maintained MariaDB LTS and on both maintained MySQL LTS lines. + include: + - php: '8.1' + db: 'mariadb:12.3' + - php: '8.2' + db: 'mariadb:12.3' + - php: '8.3' + db: 'mariadb:12.3' + - php: '8.4' + db: 'mariadb:12.3' + - php: '8.5' + db: 'mariadb:12.3' + - php: '8.5' + db: 'mariadb:10.11' + - php: '8.5' + db: 'mysql:9.7' + - php: '8.5' + db: 'mysql:8.4' + + # No health check: the admin binary differs per image, and db-prepare waits for the server. services: - mariadb: - image: mariadb:10.3 + db: + image: ${{ matrix.db }} ports: - 3306:3306 env: MYSQL_ROOT_PASSWORD: root - options: --health-cmd="mysqladmin ping" --health-interval=5s --health-timeout=2s --health-retries=3 + MARIADB_ROOT_PASSWORD: root steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Verify MariaDB connection - run: | - while ! mysqladmin ping -h127.0.0.1 -P3306 --silent; do - sleep 1 - done - - - name: Test migrations - run: | - git fetch origin 0.44.1 && git checkout FETCH_HEAD -- structure.sql - mysql -h127.0.0.1 -P3306 -uroot -proot -e "create database telegrambot_migrations; use telegrambot_migrations; source structure.sql;" - git checkout HEAD -- structure.sql - mysql -h127.0.0.1 -P3306 -uroot -proot -e "create database telegrambot; use telegrambot; source structure.sql;" - for SCHEMA_UPDATE_FILE in $(ls utils/db-schema-update); do mysql -h127.0.0.1 -P3306 -uroot -proot -e "use telegrambot_migrations; source utils/db-schema-update/${SCHEMA_UPDATE_FILE};"; done; - - name: Install PHP uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0 with: @@ -66,6 +72,14 @@ jobs: - name: Install dependencies run: composer install --prefer-dist --no-progress + # Fresh schema, then the 0.44.1 schema plus every migration, then the diff of the two. + - name: Prepare databases and diff the schemas + env: + DB_PASSWORD: root + run: | + composer db-prepare + composer schema-diff + - name: Check PHP code run: composer check-code @@ -83,13 +97,36 @@ jobs: # composer test-cov # composer test-cov-upload - # Single status for branch protection, so the PHP matrix can change without touching repository settings. + # Runs once, on the newest PHP; the errors that existed when PHPStan was added are listed in phpstan-baseline.neon. + static-analysis: + name: Static analysis + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install PHP + uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0 + with: + php-version: '8.5' + + - name: Install dependencies + run: composer install --prefer-dist --no-progress + + - name: Run static analysis + run: composer analyse + + # Single status for branch protection, so jobs and the PHP matrix can change without touching repository + # settings. Every other job must be listed in its needs. tests-passed: name: Tests if: always() - needs: tests + needs: [tests, static-analysis] runs-on: ubuntu-latest steps: - - name: Check matrix result - run: test "${{ needs.tests.result }}" = "success" + - name: Check job results + run: | + test "${{ needs.tests.result }}" = "success" + test "${{ needs.static-analysis.result }}" = "success" diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e41c041..7bef6e28 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,11 +6,13 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c ## [Unreleased] ### Notes - [:ledger: View file changes][Unreleased] +- A MySQL database upgraded past 0.61.0 needs DB migration scripts run again: `0.60.0-0.61.0.sql` and `0.62.0-0.63.0.sql`, then `0.82.0-0.83.0.sql` if the database is at 0.83.0 or later. Other files that applied without an error must not be run again. The migration scripts are tested on MariaDB 10.11 and 12.3 and on MySQL 8.4 and 9.7. ### Added ### Changed ### Deprecated ### Removed ### Fixed +- DB migration scripts `0.60.0-0.61.0.sql` and `0.62.0-0.63.0.sql` now run on MySQL, and both can be run more than once on any database. `0.62.0-0.63.0.sql` was meant to drop a duplicate foreign key on `message.forward_from` named `message_ibfk_6`; servers that name it differently, such as MariaDB 12, kept the duplicate, and a re-run of the file removes it. (@akalongman) (#1505) ### Security ## [0.84.0] - 2026-11-11 diff --git a/CLAUDE.md b/CLAUDE.md index 6074c39a..7ab92581 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,17 +10,22 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ```bash composer install -composer check-code # phpcs, PSR-12 over src/, tests/, utils/ (must print nothing) +composer check-code # phpcs, PSR-12 over src/, tests/, utils/ (must report no violations) +composer analyse # PHPStan level 5 over src/, must exit 0; after fixing an error listed in phpstan-baseline.neon, regenerate that file with vendor/bin/phpstan analyse --generate-baseline composer test # phpunit, whole suite vendor/bin/phpunit tests/Unit/Entities/MessageTest.php vendor/bin/phpunit --filter testGetCommand vendor/bin/phpcbf # auto-fix coding standard violations composer test-cov # coverage (needs Xdebug), writes clover.xml +composer db-prepare # drops and recreates telegrambot and telegrambot_migrations on the server DB_HOST and DB_PORT name (default 127.0.0.1:3306), so point it at a throwaway server; stops with exit 1 before dropping anything if either holds a row, unless DB_PREPARE_FORCE=1 +composer schema-diff # compares those two databases: exit 0 clean, 1 a difference not in utils/db-schema-diff-accepted.txt or an entry there that matches no difference, 2 a usage, connection or schema read error, an unreadable accepted file, or a missing or empty database ``` -Test database: only `tests/Unit/ConversationTest.php` touches MySQL. It reads the `PHPUNIT_DB_*` constants from the PHPUnit config and expects a database (default name `telegrambot`) loaded from `structure.sql`. To use other credentials, copy `phpunit.xml.dist` to `phpunit.xml` (gitignored) and edit the constants there. `TestHelpers::emptyDb()` deletes every row from the core tables, so never point it at a database holding real data. +PHPStan is pinned to an exact version in `composer.json`, because `composer.lock` is not committed and the baseline records exact error counts per file; a commit that raises that version also regenerates `phpstan-baseline.neon`. -CI runs MariaDB 10.3, which is more permissive than MySQL 8.4 (for example, MySQL 8.4 rejects a foreign key that references a non-unique column). Keep `structure.sql` loadable on both with default settings. The older migration files are MariaDB-only (`DROP FOREIGN KEY IF EXISTS`). +Test database: `tests/Unit/ConversationTest.php` and `tests/Unit/DBTest.php` touch MySQL. They read the `PHPUNIT_DB_*` constants from the PHPUnit config and expect a database (default name `telegrambot`) loaded from `structure.sql`. To use other credentials, copy `phpunit.xml.dist` to `phpunit.xml` (gitignored) and edit the constants there. `TestHelpers::emptyDb()` deletes every row from the core tables, so never point it at a database holding real data. + +CI runs every job against its own fresh database server: PHP 8.1 through 8.5 on MariaDB 12.3, and PHP 8.5 on MariaDB 10.11, MySQL 9.7 and MySQL 8.4. On each of these four servers it runs the migration chain and the schema diff (see Database schema), then the test suite against the `telegrambot` database that `composer db-prepare` built. MySQL is stricter than MariaDB (for example, it rejects a foreign key that references a non-unique column), so keep `structure.sql` loadable on all four with default settings. The PHPUnit config defines the constant `PHPUNIT_TESTSUITE`. When it is defined, `Request::send()` returns a fake `ServerResponse` built by `Request::generateGeneralFakeServerResponse()` and never calls the network, so tests need no HTTP mocking and cannot assert on real API behavior. @@ -67,11 +72,15 @@ A new API version usually touches several places that must stay in step: - New type: entity class with `@method` docblock and `subEntities()`, plus the parent entity's map. - New method: `Request::$actions` and the `@method` docblock on `Request`. -- New update type: `Update` constant and `subEntities()` entry. If it is persisted, also a `DB::insert*Request()` method wired into `DB::insertRequest()`, the table in `DB::defineTables()`, the `telegram_update` column, `structure.sql`, and a migration. +- New update type: `Update` constant and `subEntities()` entry. If it is persisted, also a `DB::insert*Request()` method wired into `DB::insertRequest()`, the table in `DB::defineTables()`, its `TB_` constant in the `ignoreErrors` list of `phpstan.neon.dist`, the `telegram_update` column, `structure.sql`, and a migration. ### Database schema -`structure.sql` is the full current schema. Each release that changes it also adds `utils/db-schema-update/-.sql`; during development the file is named `-unreleased.sql` and linked from the `[Unreleased]` notes in `CHANGELOG.md`. CI loads the 0.44.1 schema, applies every migration in order, and separately loads the current `structure.sql`; both must succeed, so a schema change needs both files edited. Note that CI does not diff the two results. +`structure.sql` is the full current schema. Each release that changes it also adds `utils/db-schema-update/-.sql`; during development the file is named `-unreleased.sql` and linked from the `[Unreleased]` notes in `CHANGELOG.md`. On each of the four CI servers, `composer db-prepare` loads the current `structure.sql` into `telegrambot` and the 0.44.1 schema plus every migration in order into `telegrambot_migrations`, stopping at the first file that fails. `composer schema-diff` then compares the two through `information_schema`: tables with their engine and collation; columns with type, nullability, default, character set, collation and extra attributes such as `AUTO_INCREMENT`; indexes by column with whether each is the primary key, unique or non-unique; and foreign keys by column with the referenced columns and their `ON DELETE` and `ON UPDATE` rules (not comments, column order or key names). It fails on any difference not listed in `utils/db-schema-diff-accepted.txt`, and on any entry there that no longer matches a difference. Both must pass, so a schema change needs both files edited to the same result. Adding an entry to the accepted list needs the maintainer's agreement. + +Every migration is plain SQL that runs unchanged on all four servers: no stored procedures and no client commands (`source`, `delimiter`). MariaDB-only syntax such as `DROP FOREIGN KEY IF EXISTS` fails on MySQL, and generated key names differ between servers, so look a key up by column in `information_schema` and apply the change through `PREPARE`, as `0.83.1-0.84.0.sql` does. + +To run both scripts locally, start a throwaway server and point them at its port: `docker run -d --name tg-db -p 127.0.0.1:33123:3306 -e MARIADB_ROOT_PASSWORD=root mariadb:12.3`, then `DB_PORT=33123 DB_PASSWORD=root composer db-prepare` and `DB_PORT=33123 DB_PASSWORD=root composer schema-diff`, and remove the server afterwards with `docker rm -f tg-db`. ## Conventions diff --git a/composer.json b/composer.json index 9f803201..47f1dc2b 100644 --- a/composer.json +++ b/composer.json @@ -38,6 +38,7 @@ "guzzlehttp/guzzle": "^7.15.2" }, "require-dev": { + "phpstan/phpstan": "2.3.5", "phpunit/phpunit": "^9.5", "squizlabs/php_codesniffer": "^3.6", "dms/phpunit-arraysubset-asserts": "^0.2", @@ -50,13 +51,17 @@ }, "autoload-dev": { "psr-4": { - "Longman\\TelegramBot\\Tests\\Unit\\": "tests/Unit" + "Longman\\TelegramBot\\Tests\\Unit\\": "tests/Unit", + "Longman\\TelegramBot\\Utils\\": "utils" } }, "scripts": { "check-code": [ "\"vendor/bin/phpcs\"" ], + "analyse": [ + "\"vendor/bin/phpstan\" analyse --memory-limit=1G" + ], "test": [ "\"vendor/bin/phpunit\"" ], @@ -65,6 +70,12 @@ ], "test-cov-upload": [ "@php ocular.phar code-coverage:upload --format=php-clover clover.xml" + ], + "db-prepare": [ + "bash utils/db-prepare.sh" + ], + "schema-diff": [ + "@php utils/db-schema-diff.php telegrambot telegrambot_migrations" ] }, "config": { diff --git a/docs/specs/2026-11-11-ci-hardening-design.md b/docs/specs/2026-11-11-ci-hardening-design.md index 2dcdf345..161a7462 100644 --- a/docs/specs/2026-11-11-ci-hardening-design.md +++ b/docs/specs/2026-11-11-ci-hardening-design.md @@ -81,9 +81,9 @@ file, so more may appear once these are fixed): Rules for a repaired file: - It runs unchanged on MariaDB and MySQL. -- It can be run again on a database where an earlier attempt stopped part-way. - This is what lets a stuck MySQL user recover: re-run the file that failed, - then continue the chain. +- It can be run again on any database, including one where an earlier attempt + stopped part-way. This is what lets a stuck MySQL user recover: re-run, in + order, each file that stopped on their database, and none that applied. - Foreign keys are found by column in `information_schema`, never by a generated name such as `message_ibfk_6`. @@ -93,6 +93,16 @@ stopped. Their `message` table has no `via_bot`. After this change they re-run `0.62.0-0.63.0.sql`: the `poll` columns are detected as present and skipped, the primary key is rebuilt, `via_bot` is added, and every later file applies. +A second case was measured on MySQL 8.4 after the final review (2026-11-12). +A user who kept upgrading release by release (Composer updates the library +whether or not a migration applied) ran every file and went on after each +error: `0.60.0-0.61.0.sql`, `0.62.0-0.63.0.sql` and `0.82.0-0.83.0.sql` +stopped, and every other file applied. Re-running only those three, in that +order, ends without an error and with a clean schema diff. Re-running every +file from the first failure on does not: ten files stop on duplicate or +unknown columns, and `0.72.0-0.73.0.sql` adds back a column that +`0.76.1-0.77.0.sql` had renamed. The changelog gives the first recovery. + Proof that MariaDB is unaffected: before touching a file, dump the migrated MariaDB schema; after the repair the dump must be identical. @@ -117,10 +127,20 @@ schema diff, and runs the test suite. A script under `utils/` compares two databases on one server through `information_schema` and prints every difference: -- tables present on one side only; -- per column: type, nullability, default, character set and collation; -- indexes with their columns and uniqueness; -- foreign keys by column and referenced column, ignoring generated names. +- tables present on one side only, and for a table on both sides its engine + and collation; +- per column: type, nullability, default, character set, collation and extra + attributes such as `AUTO_INCREMENT` and `ON UPDATE CURRENT_TIMESTAMP`; +- indexes with their columns and uniqueness, the primary key told apart from + a unique index on the same columns; +- foreign keys by column and referenced column, with their `ON DELETE` and + `ON UPDATE` rules, ignoring generated names. + +Engine, collation, extra attributes, the primary key and the foreign key rules +were added after the final review (2026-11-12): drift in any of them breaks an +upgraded install while both schemas still load. For example, an `id` that is +`AUTO_INCREMENT` in `structure.sql` and plain `bigint` in the migration fails +every upgraded install's first insert. Column comments and column order are not compared (maintainer may overrule; see open calls). Accepted differences live in one small file next to the @@ -144,7 +164,7 @@ baseline stays reviewable; the builder measures and proposes it. ### Documentation `CLAUDE.md` (commands, the database section) and `CHANGELOG.md` are updated. -The changelog tells MySQL users which file to re-run if an old upgrade stopped. +The changelog tells MySQL users which files to re-run if an old upgrade stopped. ## Calls made by the author, open to correction diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon new file mode 100644 index 00000000..ff05fa49 --- /dev/null +++ b/phpstan-baseline.neon @@ -0,0 +1,571 @@ +parameters: + ignoreErrors: + - + message: '#^Parameter \#3 \$subject of function str_replace expects array\\|string, int given\.$#' + identifier: argument.type + count: 1 + path: src/Commands/AdminCommands/ChatsCommand.php + + - + message: '#^Ternary operator condition is always true\.$#' + identifier: ternary.alwaysTrue + count: 1 + path: src/Commands/AdminCommands/ChatsCommand.php + + - + message: '#^Ternary operator condition is always true\.$#' + identifier: ternary.alwaysTrue + count: 1 + path: src/Commands/AdminCommands/CleanupCommand.php + + - + message: '#^PHPDoc tag @return with type mixed is not subtype of native type Longman\\TelegramBot\\Entities\\ServerResponse\.$#' + identifier: return.phpDocType + count: 1 + path: src/Commands/AdminCommands/DebugCommand.php + + - + message: '#^Ternary operator condition is always true\.$#' + identifier: ternary.alwaysTrue + count: 1 + path: src/Commands/AdminCommands/DebugCommand.php + + - + message: '#^PHPDoc tag @return with type mixed is not subtype of native type Longman\\TelegramBot\\Entities\\ServerResponse\.$#' + identifier: return.phpDocType + count: 2 + path: src/Commands/AdminCommands/SendtochannelCommand.php + + - + message: '#^Ternary operator condition is always true\.$#' + identifier: ternary.alwaysTrue + count: 2 + path: src/Commands/AdminCommands/SendtochannelCommand.php + + - + message: '#^Variable \$result might not be defined\.$#' + identifier: variable.undefined + count: 1 + path: src/Commands/AdminCommands/SendtochannelCommand.php + + - + message: '#^Strict comparison using \!\=\= between string and null will always evaluate to true\.$#' + identifier: notIdentical.alwaysTrue + count: 1 + path: src/Commands/AdminCommands/WhoisCommand.php + + - + message: '#^Ternary operator condition is always true\.$#' + identifier: ternary.alwaysTrue + count: 1 + path: src/Commands/AdminCommands/WhoisCommand.php + + - + message: '#^If condition is always true\.$#' + identifier: if.alwaysTrue + count: 4 + path: src/Commands/Command.php + + - + message: '#^Method Longman\\TelegramBot\\Commands\\Command\:\:__call\(\) should return Longman\\TelegramBot\\Commands\\Command but returns null\.$#' + identifier: return.type + count: 1 + path: src/Commands/Command.php + + - + message: '#^Ternary operator condition is always true\.$#' + identifier: ternary.alwaysTrue + count: 4 + path: src/Commands/Command.php + + - + message: '#^Unreachable statement \- code above always terminates\.$#' + identifier: deadCode.unreachable + count: 3 + path: src/Commands/Command.php + + - + message: '#^Result of \|\| is always false\.$#' + identifier: booleanOr.alwaysFalse + count: 1 + path: src/Commands/SystemCommand.php + + - + message: '#^Strict comparison using \=\=\= between Longman\\TelegramBot\\Entities\\Chat and null will always evaluate to false\.$#' + identifier: identical.alwaysFalse + count: 1 + path: src/Commands/SystemCommand.php + + - + message: '#^Strict comparison using \=\=\= between Longman\\TelegramBot\\Entities\\Message and null will always evaluate to false\.$#' + identifier: identical.alwaysFalse + count: 2 + path: src/Commands/SystemCommand.php + + - + message: '#^Strict comparison using \=\=\= between Longman\\TelegramBot\\Entities\\User and null will always evaluate to false\.$#' + identifier: identical.alwaysFalse + count: 1 + path: src/Commands/SystemCommand.php + + - + message: '#^Strict comparison using \=\=\= between array\\|bool\|int\|Longman\\TelegramBot\\Entities\\Message\\MaybeInaccessibleMessage\|Longman\\TelegramBot\\Entities\\Payments\\SuccessfulPayment\|Longman\\TelegramBot\\Entities\\User\|string and null will always evaluate to false\.$#' + identifier: identical.alwaysFalse + count: 1 + path: src/Commands/SystemCommand.php + + - + message: '#^Ternary operator condition is always true\.$#' + identifier: ternary.alwaysTrue + count: 2 + path: src/Commands/SystemCommand.php + + - + message: '#^PHPDoc tag @return with type mixed is not subtype of native type Longman\\TelegramBot\\Entities\\ServerResponse\.$#' + identifier: return.phpDocType + count: 1 + path: src/Commands/SystemCommands/InlinequeryCommand.php + + - + message: '#^If condition is always true\.$#' + identifier: if.alwaysTrue + count: 23 + path: src/DB.php + + - + message: '#^Instanceof between Longman\\TelegramBot\\Entities\\User and Longman\\TelegramBot\\Entities\\User will always evaluate to true\.$#' + identifier: instanceof.alwaysTrue + count: 1 + path: src/DB.php + + - + message: '#^Left side of && is always true\.$#' + identifier: booleanAnd.leftAlwaysTrue + count: 18 + path: src/DB.php + + - + message: '#^Parameter \#1 \$edited_message of static method Longman\\TelegramBot\\DB\:\:insertEditedMessageRequest\(\) expects Longman\\TelegramBot\\Entities\\Message, Longman\\TelegramBot\\Entities\\Message\\MaybeInaccessibleMessage given\.$#' + identifier: argument.type + count: 1 + path: src/DB.php + + - + message: '#^Parameter \#1 \$message of static method Longman\\TelegramBot\\DB\:\:insertMessageRequest\(\) expects Longman\\TelegramBot\\Entities\\Message, Longman\\TelegramBot\\Entities\\Message\\MaybeInaccessibleMessage given\.$#' + identifier: argument.type + count: 1 + path: src/DB.php + + - + message: '#^Strict comparison using \!\=\= between int and null will always evaluate to true\.$#' + identifier: notIdentical.alwaysTrue + count: 1 + path: src/DB.php + + - + message: '#^Strict comparison using \=\=\= between PDO and null will always evaluate to false\.$#' + identifier: identical.alwaysFalse + count: 1 + path: src/DB.php + + - + message: '#^Ternary operator condition is always true\.$#' + identifier: ternary.alwaysTrue + count: 2 + path: src/DB.php + + - + message: '#^Access to an undefined property Longman\\TelegramBot\\Entities\\Chat\:\:\$type\.$#' + identifier: property.notFound + count: 2 + path: src/Entities/Chat.php + + - + message: '#^PHPDoc tag @property has invalid value \(string type Type of chat, can be either "private ", "group", "supergroup" or "channel"\)\: Unexpected token "type", expected variable at offset 113 on line 6$#' + identifier: phpDoc.parseError + count: 1 + path: src/Entities/Chat.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\ChatBoost\:\:getSource\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\ChatBoostSource\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ChatBoost.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\ChatBoostRemoved\:\:getSource\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\ChatBoostSource\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ChatBoostRemoved.php + + - + message: '#^Class Longman\\TelegramBot\\Entities\\Game not found\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ExternalReplyInfo.php + + - + message: '#^Class Longman\\TelegramBot\\Entities\\Giveaway not found\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ExternalReplyInfo.php + + - + message: '#^Class Longman\\TelegramBot\\Entities\\GiveawayWinners not found\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ExternalReplyInfo.php + + - + message: '#^Class Longman\\TelegramBot\\Entities\\Invoice not found\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ExternalReplyInfo.php + + - + message: '#^Class Longman\\TelegramBot\\Entities\\MessageOrigin not found\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ExternalReplyInfo.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\ExternalReplyInfo\:\:getGame\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\Game\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ExternalReplyInfo.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\ExternalReplyInfo\:\:getGiveaway\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\Giveaway\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ExternalReplyInfo.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\ExternalReplyInfo\:\:getGiveawayWinners\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\GiveawayWinners\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ExternalReplyInfo.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\ExternalReplyInfo\:\:getInvoice\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\Invoice\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ExternalReplyInfo.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\ExternalReplyInfo\:\:getOrigin\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\MessageOrigin\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ExternalReplyInfo.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultAudio\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultAudio.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultCachedAudio\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultCachedAudio.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultCachedDocument\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultCachedDocument.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultCachedGif\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultCachedGif.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultCachedMpeg4Gif\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultCachedMpeg4Gif.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultCachedPhoto\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultCachedPhoto.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultCachedVideo\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultCachedVideo.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultCachedVoice\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultCachedVoice.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultDocument\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultDocument.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultGif\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultGif.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultMpeg4Gif\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultMpeg4Gif.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultPhoto\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultPhoto.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultVideo\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultVideo.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InlineQuery\\InlineQueryResultVoice\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InlineQuery\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InlineQuery/InlineQueryResultVoice.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InputMedia\\InputMediaAnimation\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InputMedia\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InputMedia/InputMediaAnimation.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InputMedia\\InputMediaAudio\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InputMedia\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InputMedia/InputMediaAudio.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InputMedia\\InputMediaDocument\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InputMedia\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InputMedia/InputMediaDocument.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InputMedia\\InputMediaPhoto\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InputMedia\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InputMedia/InputMediaPhoto.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InputMedia\\InputMediaVideo\:\:getCaptionEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InputMedia\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InputMedia/InputMediaVideo.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InputMessageContent\\InputInvoiceMessageContent\:\:getPrices\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InputMessageContent\\LabeledPrice\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InputMessageContent/InputInvoiceMessageContent.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InputMessageContent\\InputInvoiceMessageContent\:\:setPrices\(\) parameter \#1 \$prices contains unknown class Longman\\TelegramBot\\Entities\\InputMessageContent\\LabeledPrice\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InputMessageContent/InputInvoiceMessageContent.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InputMessageContent\\InputTextMessageContent\:\:getEntities\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InputMessageContent\\MessageEntity\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InputMessageContent/InputTextMessageContent.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InputMessageContent\\InputTextMessageContent\:\:getLinkPreviewOptions\(\) return type contains unknown class Longman\\TelegramBot\\Entities\\InputMessageContent\\LinkPreviewOptions\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InputMessageContent/InputTextMessageContent.php + + - + message: '#^PHPDoc tag @method for method Longman\\TelegramBot\\Entities\\InputMessageContent\\InputTextMessageContent\:\:setLinkPreviewOptions\(\) parameter \#1 \$link_preview_options contains unknown class Longman\\TelegramBot\\Entities\\InputMessageContent\\LinkPreviewOptions\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/InputMessageContent/InputTextMessageContent.php + + - + message: '#^Unsafe usage of new static\(\)\.$#' + identifier: new.static + count: 2 + path: src/Entities/Keyboard.php + + - + message: '#^Class Longman\\TelegramBot\\Entities\\MenuButton\\MenuButtonCommands constructor invoked with 2 parameters, 1 required\.$#' + identifier: arguments.count + count: 1 + path: src/Entities/MenuButton/Factory.php + + - + message: '#^Class Longman\\TelegramBot\\Entities\\MenuButton\\MenuButtonDefault constructor invoked with 2 parameters, 1 required\.$#' + identifier: arguments.count + count: 1 + path: src/Entities/MenuButton/Factory.php + + - + message: '#^Class Longman\\TelegramBot\\Entities\\MenuButton\\MenuButtonWebApp constructor invoked with 2 parameters, 1 required\.$#' + identifier: arguments.count + count: 1 + path: src/Entities/MenuButton/Factory.php + + - + message: '#^Instanceof between Longman\\TelegramBot\\Entities\\User and Longman\\TelegramBot\\Entities\\User will always evaluate to true\.$#' + identifier: instanceof.alwaysTrue + count: 1 + path: src/Entities/Message.php + + - + message: '#^Class Longman\\TelegramBot\\Entities\\ReactionType\\ReactionTypeCustomEmoji constructor invoked with 2 parameters, 0\-1 required\.$#' + identifier: arguments.count + count: 1 + path: src/Entities/ReactionType/Factory.php + + - + message: '#^Class Longman\\TelegramBot\\Entities\\ReactionType\\ReactionTypeEmoji constructor invoked with 2 parameters, 0\-1 required\.$#' + identifier: arguments.count + count: 1 + path: src/Entities/ReactionType/Factory.php + + - + message: '#^Method Longman\\TelegramBot\\Entities\\ServerResponse\:\:createResultObject\(\) has invalid return type Longman\\TelegramBot\\Entities\\MenuButton\.$#' + identifier: class.notFound + count: 1 + path: src/Entities/ServerResponse.php + + - + message: '#^Method Longman\\TelegramBot\\Entities\\ServerResponse\:\:createResultObjects\(\) should return array\ but returns list\\.$#' + identifier: return.type + count: 1 + path: src/Entities/ServerResponse.php + + - + message: '#^PHPDoc tag @return with type Longman\\TelegramBot\\Entities\\BotDescription\|Longman\\TelegramBot\\Entities\\BotName\|Longman\\TelegramBot\\Entities\\BotShortDescription\|Longman\\TelegramBot\\Entities\\Chat\|Longman\\TelegramBot\\Entities\\ChatAdministratorRights\|Longman\\TelegramBot\\Entities\\ChatMember\\ChatMember\|Longman\\TelegramBot\\Entities\\File\|Longman\\TelegramBot\\Entities\\MenuButton\|Longman\\TelegramBot\\Entities\\Message\|Longman\\TelegramBot\\Entities\\Poll\|Longman\\TelegramBot\\Entities\\SentWebAppMessage\|Longman\\TelegramBot\\Entities\\StickerSet\|Longman\\TelegramBot\\Entities\\User\|Longman\\TelegramBot\\Entities\\UserProfilePhotos\|Longman\\TelegramBot\\Entities\\WebhookInfo is not subtype of native type Longman\\TelegramBot\\Entities\\Entity\.$#' + identifier: return.phpDocType + count: 1 + path: src/Entities/ServerResponse.php + + - + message: '#^Method Longman\\TelegramBot\\Entities\\Update\:\:getUpdateContent\(\) should return Longman\\TelegramBot\\Entities\\CallbackQuery\|Longman\\TelegramBot\\Entities\\ChatBoostRemoved\|Longman\\TelegramBot\\Entities\\ChatBoostUpdated\|Longman\\TelegramBot\\Entities\\ChatJoinRequest\|Longman\\TelegramBot\\Entities\\ChatMemberUpdated\|Longman\\TelegramBot\\Entities\\ChosenInlineResult\|Longman\\TelegramBot\\Entities\\InlineQuery\|Longman\\TelegramBot\\Entities\\Message\|Longman\\TelegramBot\\Entities\\MessageReactionCountUpdated\|Longman\\TelegramBot\\Entities\\MessageReactionUpdated\|Longman\\TelegramBot\\Entities\\Payments\\PreCheckoutQuery\|Longman\\TelegramBot\\Entities\\Payments\\ShippingQuery\|Longman\\TelegramBot\\Entities\\Poll\|Longman\\TelegramBot\\Entities\\PollAnswer but returns null\.$#' + identifier: return.type + count: 1 + path: src/Entities/Update.php + + - + message: '#^Access to an undefined property Longman\\TelegramBot\\Entities\\InputMedia\\InputMedia\:\:\$media\.$#' + identifier: property.notFound + count: 1 + path: src/Request.php + + - + message: '#^Access to an undefined property Longman\\TelegramBot\\Entities\\InputMedia\\InputMedia\:\:\$raw_data\.$#' + identifier: property.notFound + count: 1 + path: src/Request.php + + - + message: '#^Access to an undefined property Longman\\TelegramBot\\Entities\\InputMedia\\InputMedia\:\:\$thumbnail\.$#' + identifier: property.notFound + count: 1 + path: src/Request.php + + - + message: '#^Call to an undefined method GuzzleHttp\\ClientInterface\:\:get\(\)\.$#' + identifier: method.notFound + count: 1 + path: src/Request.php + + - + message: '#^Call to an undefined method GuzzleHttp\\ClientInterface\:\:post\(\)\.$#' + identifier: method.notFound + count: 1 + path: src/Request.php + + - + message: '#^Call to an undefined method Longman\\TelegramBot\\Entities\\InputMedia\\InputMedia\:\:getMedia\(\)\.$#' + identifier: method.notFound + count: 1 + path: src/Request.php + + - + message: '#^Call to an undefined method Longman\\TelegramBot\\Entities\\InputMedia\\InputMedia\:\:getThumbnail\(\)\.$#' + identifier: method.notFound + count: 1 + path: src/Request.php + + - + message: '#^If condition is always true\.$#' + identifier: if.alwaysTrue + count: 1 + path: src/Request.php + + - + message: '#^Right side of && is always true\.$#' + identifier: booleanAnd.rightAlwaysTrue + count: 1 + path: src/Request.php + + - + message: '#^Ternary operator condition is always true\.$#' + identifier: ternary.alwaysTrue + count: 1 + path: src/Request.php + + - + message: '#^Unreachable statement \- code above always terminates\.$#' + identifier: deadCode.unreachable + count: 1 + path: src/Request.php + + - + message: '#^Call to function is_callable\(\) with callable\(\)\: mixed will always evaluate to true\.$#' + identifier: function.alreadyNarrowedType + count: 1 + path: src/Telegram.php + + - + message: '#^If condition is always true\.$#' + identifier: if.alwaysTrue + count: 3 + path: src/Telegram.php + + - + message: '#^Parameter \#2 \$id of static method Longman\\TelegramBot\\DB\:\:selectTelegramUpdate\(\) expects string, int given\.$#' + identifier: argument.type + count: 1 + path: src/Telegram.php + + - + message: '#^Right side of && is always true\.$#' + identifier: booleanAnd.rightAlwaysTrue + count: 1 + path: src/Telegram.php + + - + message: '#^Strict comparison using \!\=\= between Longman\\TelegramBot\\Entities\\CallbackQuery\|Longman\\TelegramBot\\Entities\\ChosenInlineResult\|Longman\\TelegramBot\\Entities\\InlineQuery\|Longman\\TelegramBot\\Entities\\Message and null will always evaluate to true\.$#' + identifier: notIdentical.alwaysTrue + count: 1 + path: src/Telegram.php + + - + message: '#^Unreachable statement \- code above always terminates\.$#' + identifier: deadCode.unreachable + count: 1 + path: src/Telegram.php diff --git a/phpstan.neon.dist b/phpstan.neon.dist new file mode 100644 index 00000000..254b84a0 --- /dev/null +++ b/phpstan.neon.dist @@ -0,0 +1,15 @@ +includes: + - phpstan-baseline.neon + +parameters: + level: 5 + paths: + - src + ignoreErrors: + # DB::defineTables() and ConversationDB::initializeConversation() define the table + # constants at runtime, with the configured table prefix, so static analysis cannot + # see them. Each name is listed, so a misspelt constant still fails; a table added to + # DB::defineTables() needs its constant added here. + - + message: '#^Constant TB_(?:CALLBACK_QUERY|CHAT|CHAT_BOOST_REMOVED|CHAT_BOOST_UPDATED|CHAT_JOIN_REQUEST|CHAT_MEMBER_UPDATED|CHOSEN_INLINE_RESULT|CONVERSATION|EDITED_MESSAGE|INLINE_QUERY|MESSAGE|MESSAGE_REACTION|MESSAGE_REACTION_COUNT|POLL|POLL_ANSWER|PRE_CHECKOUT_QUERY|REQUEST_LIMITER|SHIPPING_QUERY|TELEGRAM_UPDATE|USER|USER_CHAT) not found\.$#' + identifier: constant.notFound diff --git a/tests/Unit/Utils/SchemaDiffTest.php b/tests/Unit/Utils/SchemaDiffTest.php new file mode 100644 index 00000000..499c6faf --- /dev/null +++ b/tests/Unit/Utils/SchemaDiffTest.php @@ -0,0 +1,194 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Longman\TelegramBot\Tests\Unit\Utils; + +use InvalidArgumentException; +use Longman\TelegramBot\Tests\Unit\TestCase; +use Longman\TelegramBot\Utils\SchemaDiff; + +/** + * @link https://github.com/php-telegram-bot/core + * @author Avtandil Kikabidze + * @copyright Avtandil Kikabidze + * @license http://opensource.org/licenses/mit-license.php The MIT License (MIT) + * @package TelegramTest + */ +class SchemaDiffTest extends TestCase +{ + public function testIdenticalSnapshotsHaveNoDifferences(): void + { + self::assertSame([], SchemaDiff::compare($this->snapshot(), $this->snapshot())); + } + + public function testTableOnOneSideYieldsOnlyTheTableKey(): void + { + $migrated = $this->snapshot(); + $migrated['botan_shortener'] = [ + 'options' => 'InnoDB|utf8mb4_unicode_520_ci', + 'columns' => ['id' => 'bigint|NO|NULL|||'], + 'indexes' => ['p:id'], + 'foreign_keys' => [], + ]; + + self::assertSame(['table botan_shortener'], array_keys(SchemaDiff::compare($this->snapshot(), $migrated))); + } + + public function testTableOnlyInFreshSnapshotIsReported(): void + { + $fresh = $this->snapshot(); + $fresh['chat'] = [ + 'options' => 'InnoDB|utf8mb4_unicode_520_ci', + 'columns' => ['id' => 'bigint|NO|NULL|||'], + 'indexes' => ['p:id'], + 'foreign_keys' => [], + ]; + + self::assertSame(['table chat' => 'fresh only'], SchemaDiff::compare($fresh, $this->snapshot())); + } + + public function testColumnIndexAndForeignKeyDifferences(): void + { + $migrated = $this->snapshot(); + $migrated['user']['columns']['username'] = 'char(255)|YES|NULL|utf8mb4|utf8mb4_unicode_520_ci|'; + $migrated['message']['columns']['new_chat_member'] = 'bigint|YES|NULL|||'; + $migrated['message']['indexes'][] = '0:new_chat_member'; + unset($migrated['message']['foreign_keys'][0]); + + self::assertSame( + ['column message.new_chat_member', 'column user.username', 'fk message(chat_id)', 'index message(new_chat_member)'], + array_keys(SchemaDiff::compare($this->snapshot(), $migrated)) + ); + } + + public function testUniquenessRepeatsAndReferencesAreComparedPerColumns(): void + { + $migrated = $this->snapshot(); + $migrated['user']['indexes'] = ['p:id', '1:username']; + $migrated['message']['indexes'][] = '0:user_id'; + $migrated['message']['foreign_keys'][1] = 'user_id>chat(id) ON DELETE RESTRICT ON UPDATE RESTRICT'; + + self::assertSame( + [ + 'fk message(user_id)' => 'fresh user(id) ON DELETE RESTRICT ON UPDATE RESTRICT; migrated chat(id) ON DELETE RESTRICT ON UPDATE RESTRICT', + 'index message(user_id)' => 'fresh non-unique; migrated non-unique + non-unique', + 'index user(username)' => 'fresh non-unique; migrated unique', + ], + SchemaDiff::compare($this->snapshot(), $migrated) + ); + } + + public function testColumnExtraIsCompared(): void + { + $fresh = $this->snapshot(); + $fresh['message']['columns']['id'] = 'bigint unsigned|NO|NULL|||auto_increment'; + + self::assertSame( + ['column message.id' => 'fresh bigint unsigned|NO|NULL|||auto_increment; migrated bigint unsigned|NO|NULL|||'], + SchemaDiff::compare($fresh, $this->snapshot()) + ); + } + + public function testForeignKeyRulesAreCompared(): void + { + $migrated = $this->snapshot(); + $migrated['message']['foreign_keys'][1] = 'user_id>user(id) ON DELETE CASCADE ON UPDATE RESTRICT'; + + self::assertSame( + ['fk message(user_id)' => 'fresh user(id) ON DELETE RESTRICT ON UPDATE RESTRICT; migrated user(id) ON DELETE CASCADE ON UPDATE RESTRICT'], + SchemaDiff::compare($this->snapshot(), $migrated) + ); + } + + public function testPrimaryKeyIsToldApartFromUniqueIndex(): void + { + $migrated = $this->snapshot(); + $migrated['message']['indexes'][0] = '1:chat_id,id'; + + self::assertSame( + ['index message(chat_id,id)' => 'fresh primary; migrated unique'], + SchemaDiff::compare($this->snapshot(), $migrated) + ); + } + + public function testTableEngineAndCollationAreCompared(): void + { + $other_engine = $this->snapshot(); + $other_engine['message']['options'] = 'MyISAM|utf8mb4_unicode_520_ci'; + + $other_collation = $this->snapshot(); + $other_collation['user']['options'] = 'InnoDB|utf8mb4_general_ci'; + + self::assertSame( + ['table message' => 'fresh InnoDB|utf8mb4_unicode_520_ci; migrated MyISAM|utf8mb4_unicode_520_ci'], + SchemaDiff::compare($this->snapshot(), $other_engine) + ); + self::assertSame( + ['table user' => 'fresh InnoDB|utf8mb4_unicode_520_ci; migrated InnoDB|utf8mb4_general_ci'], + SchemaDiff::compare($this->snapshot(), $other_collation) + ); + } + + public function testEmptySnapshotIsAnError(): void + { + $this->expectException(InvalidArgumentException::class); + SchemaDiff::compare($this->snapshot(), []); + } + + public function testEmptyFreshSnapshotIsAnError(): void + { + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('The fresh snapshot has no tables.'); + SchemaDiff::compare([], $this->snapshot()); + } + + public function testFilterSeparatesUnexpectedAndStale(): void + { + $accepted = SchemaDiff::parseAccepted("# unused, kept on purpose\ntable botan_shortener\n\ncolumn user.username\n"); + $result = SchemaDiff::filter(['table botan_shortener' => 'x', 'column chat.title' => 'y'], $accepted); + + self::assertSame(['column chat.title' => 'y'], $result['unexpected']); + self::assertSame(['column user.username'], $result['stale']); + } + + /** + * Two-table snapshot in the shape the CLI reads from information_schema. + * + * @return array, indexes: array, foreign_keys: array}> + */ + private function snapshot(): array + { + return [ + 'user' => [ + 'options' => 'InnoDB|utf8mb4_unicode_520_ci', + 'columns' => [ + 'id' => 'bigint|NO|NULL|||', + 'username' => 'char(191)|YES|NULL|utf8mb4|utf8mb4_unicode_520_ci|', + ], + 'indexes' => ['p:id', '0:username'], + 'foreign_keys' => [], + ], + 'message' => [ + 'options' => 'InnoDB|utf8mb4_unicode_520_ci', + 'columns' => [ + 'chat_id' => 'bigint|NO|NULL|||', + 'id' => 'bigint unsigned|NO|NULL|||', + 'user_id' => 'bigint|YES|NULL|||', + ], + 'indexes' => ['p:chat_id,id', '0:user_id'], + 'foreign_keys' => [ + 'chat_id>chat(id) ON DELETE RESTRICT ON UPDATE RESTRICT', + 'user_id>user(id) ON DELETE RESTRICT ON UPDATE RESTRICT', + ], + ], + ]; + } +} diff --git a/utils/SchemaDiff.php b/utils/SchemaDiff.php new file mode 100644 index 00000000..0bf89e57 --- /dev/null +++ b/utils/SchemaDiff.php @@ -0,0 +1,275 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Longman\TelegramBot\Utils; + +use InvalidArgumentException; + +/** + * Compare two database schema snapshots, a fresh one and a migrated one. + * + * A snapshot maps each table name to its options, columns, indexes and foreign keys: + * + * 'user_chat' => [ + * 'options' => 'InnoDB|utf8mb4_unicode_520_ci', + * 'columns' => ['user_id' => 'bigint|NO|NULL|||'], + * 'indexes' => ['p:user_id,chat_id', '0:chat_id'], + * 'foreign_keys' => ['chat_id>chat(id) ON DELETE CASCADE ON UPDATE CASCADE'], + * ] + * + * The options are "|" of the table. A column is + * "|||||", where extra holds attributes + * such as auto_increment. An index is ":", the kind "p" for the primary key, + * "1" for a unique and "0" for a non-unique index. A foreign key is + * ">() ON DELETE ON UPDATE ". + * Index and foreign key names are not part of a snapshot, so generated names never differ. + * + * Each difference is keyed "table ", "column .", "index ()" or + * "fk ()", the keys listed in the accepted differences file. A table present on + * both sides with other options is reported under its "table" key. + */ +class SchemaDiff +{ + /** + * Compare two snapshots and return every difference, sorted by key. + * + * A table present on one side only yields its "table" key and nothing for its columns. + * Indexes and foreign keys are grouped by their columns: two indexes over the same + * columns are compared as a list with repeats, and a change of index kind or a changed + * reference or rule is reported under the key of those columns. + * + * @param array, indexes: array, foreign_keys: array}> $fresh + * @param array, indexes: array, foreign_keys: array}> $migrated + * + * @return array Difference key to human-readable detail + * @throws InvalidArgumentException When either snapshot has no tables + */ + public static function compare(array $fresh, array $migrated): array + { + if ($fresh === []) { + throw new InvalidArgumentException('The fresh snapshot has no tables.'); + } + + if ($migrated === []) { + throw new InvalidArgumentException('The migrated snapshot has no tables.'); + } + + $differences = []; + + foreach (array_diff_key($fresh, $migrated) as $table => $definition) { + $differences['table ' . $table] = 'fresh only'; + } + + foreach (array_diff_key($migrated, $fresh) as $table => $definition) { + $differences['table ' . $table] = 'migrated only'; + } + + foreach (array_intersect_key($fresh, $migrated) as $table => $definition) { + if ($definition['options'] !== $migrated[$table]['options']) { + $differences['table ' . $table] = self::describe([$definition['options']], [$migrated[$table]['options']]); + } + + $differences += self::compareColumns($table, $definition['columns'], $migrated[$table]['columns']); + $differences += self::compareGroups( + 'index ' . $table, + self::groupIndexes($definition['indexes']), + self::groupIndexes($migrated[$table]['indexes']) + ); + $differences += self::compareGroups( + 'fk ' . $table, + self::groupForeignKeys($definition['foreign_keys']), + self::groupForeignKeys($migrated[$table]['foreign_keys']) + ); + } + + ksort($differences, SORT_STRING); + + return $differences; + } + + /** + * Read the difference keys from the contents of the accepted differences file. + * + * Blank lines and lines starting with "#" are skipped; surrounding whitespace is trimmed. + * + * @param string $contents + * + * @return array + */ + public static function parseAccepted(string $contents): array + { + $keys = []; + + foreach (preg_split('/\R/', $contents) as $line) { + $line = trim($line); + + if ($line === '' || $line[0] === '#') { + continue; + } + + $keys[] = $line; + } + + return $keys; + } + + /** + * Split differences into the ones not accepted and the accepted keys that match no difference. + * + * @param array $differences + * @param array $accepted + * + * @return array{unexpected: array, stale: array} + */ + public static function filter(array $differences, array $accepted): array + { + $stale = array_filter($accepted, static function (string $key) use ($differences): bool { + return !array_key_exists($key, $differences); + }); + + return [ + 'unexpected' => array_diff_key($differences, array_flip($accepted)), + 'stale' => array_values($stale), + ]; + } + + /** + * Compare the columns of one table present on both sides. + * + * @param string $table + * @param array $fresh + * @param array $migrated + * + * @return array + */ + private static function compareColumns(string $table, array $fresh, array $migrated): array + { + $differences = []; + + foreach (array_keys($fresh + $migrated) as $column) { + $fresh_definition = $fresh[$column] ?? null; + $migrated_definition = $migrated[$column] ?? null; + + if ($fresh_definition === $migrated_definition) { + continue; + } + + $differences['column ' . $table . '.' . $column] = self::describe( + $fresh_definition === null ? [] : [$fresh_definition], + $migrated_definition === null ? [] : [$migrated_definition] + ); + } + + return $differences; + } + + /** + * Compare two groupings (columns to sorted list of values) and key each mismatch by its columns. + * + * @param string $prefix "index " or "fk " + * @param array> $fresh + * @param array> $migrated + * + * @return array + */ + private static function compareGroups(string $prefix, array $fresh, array $migrated): array + { + $differences = []; + + foreach (array_keys($fresh + $migrated) as $columns) { + $fresh_values = $fresh[$columns] ?? []; + $migrated_values = $migrated[$columns] ?? []; + + if ($fresh_values === $migrated_values) { + continue; + } + + $differences[$prefix . '(' . $columns . ')'] = self::describe($fresh_values, $migrated_values); + } + + return $differences; + } + + /** + * Group index entries by their columns, each group a sorted list of "primary", "unique" and "non-unique". + * + * @param array $indexes + * + * @return array> + */ + private static function groupIndexes(array $indexes): array + { + $kinds = ['p' => 'primary', '1' => 'unique', '0' => 'non-unique']; + $groups = []; + + foreach ($indexes as $index) { + [$kind, $columns] = explode(':', $index, 2); + + $groups[$columns][] = $kinds[$kind] ?? $kind; + } + + return self::sortGroups($groups); + } + + /** + * Group foreign key entries by their columns, each group a sorted list of references. + * + * @param array $foreign_keys + * + * @return array> + */ + private static function groupForeignKeys(array $foreign_keys): array + { + $groups = []; + + foreach ($foreign_keys as $foreign_key) { + [$columns, $reference] = explode('>', $foreign_key, 2); + + $groups[$columns][] = $reference; + } + + return self::sortGroups($groups); + } + + /** + * Sort the values inside each group, so the order the server listed them in does not matter. + * + * @param array> $groups + * + * @return array> + */ + private static function sortGroups(array $groups): array + { + foreach ($groups as $columns => $values) { + sort($values, SORT_STRING); + + $groups[$columns] = $values; + } + + return $groups; + } + + /** + * Describe both sides of a difference, "absent" for a side that has nothing. + * + * @param array $fresh + * @param array $migrated + * + * @return string + */ + private static function describe(array $fresh, array $migrated): string + { + $fresh_text = $fresh === [] ? 'absent' : implode(' + ', $fresh); + $migrated_text = $migrated === [] ? 'absent' : implode(' + ', $migrated); + + return 'fresh ' . $fresh_text . '; migrated ' . $migrated_text; + } +} diff --git a/utils/db-prepare.sh b/utils/db-prepare.sh new file mode 100755 index 00000000..29fbb17c --- /dev/null +++ b/utils/db-prepare.sh @@ -0,0 +1,206 @@ +#!/usr/bin/env bash +# +# This file is part of the TelegramBot package. +# +# (c) Avtandil Kikabidze aka LONGMAN +# +# For the full copyright and license information, please view the LICENSE +# file that was distributed with this source code. +# +# Create the two databases the schema diff compares, on one server: +# telegrambot from the current structure.sql; +# telegrambot_migrations from the 0.44.1 structure.sql, then every file in +# utils/db-schema-update in ls order. +# Both are dropped and created again, so the script can run repeatedly on one +# server. The 0.44.1 schema is read through git, fetching the tag from origin +# when it is missing; the working tree is never touched. +# +# Before dropping anything, it reads every base table of both databases and +# stops with exit 1 when one holds a row, naming the database, because the +# defaults point at a local server where telegrambot may hold real data. +# DB_PREPARE_FORCE=1 skips that check and drops them anyway. +# +# Connection over TCP from DB_HOST (default 127.0.0.1), DB_PORT (3306), +# DB_USER (root) and DB_PASSWORD; the client is DB_CLIENT (mysql). DB_PASSWORD +# cannot contain a double quote or a newline. Waits up to 120 s for the server, +# each attempt with a 5 s connect timeout, and stops at once when the server +# refuses the login (ERROR 1045 or 1044). Stops at the first failing file and +# names it on standard error. + +set -euo pipefail + +# Sort the migration files byte by byte, whatever the caller's locale. +export LC_ALL=C + +DB_HOST="${DB_HOST:-127.0.0.1}" +DB_PORT="${DB_PORT:-3306}" +DB_USER="${DB_USER:-root}" +DB_PASSWORD="${DB_PASSWORD:-}" +DB_CLIENT="${DB_CLIENT:-mysql}" +DB_PREPARE_FORCE="${DB_PREPARE_FORCE:-}" + +baseline_tag=0.44.1 +root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +work="$(mktemp -d)" +trap 'rm -rf "$work"' EXIT + +# Progress goes to standard error, redrawn in place, and only when it is a terminal. +progress() { + if [ -t 2 ]; then + printf '\r\033[K%s' "$1" >&2 + fi +} + +end_progress() { + if [ -t 2 ]; then + printf '\r\033[K' >&2 + fi +} + +fail() { + end_progress + echo "db-prepare: $1" >&2 + exit 1 +} + +# The option file holds the password between double quotes, which cannot carry +# a double quote or a newline. The message does not repeat the password. +case "$DB_PASSWORD" in + *'"'* | *$'\n'*) + fail "DB_PASSWORD contains a double quote or a newline, which the client option file cannot hold." + ;; +esac + +# The password goes through an option file, so it shows neither in the process +# list nor in a client warning. --defaults-file keeps other option files out. +( + umask 077 + printf '[client]\npassword="%s"\n' "${DB_PASSWORD//\\/\\\\}" > "$work/client.cnf" +) + +db() { + "$DB_CLIENT" --defaults-file="$work/client.cnf" --protocol=TCP --host="$DB_HOST" --port="$DB_PORT" \ + --user="$DB_USER" --default-character-set=utf8mb4 "$@" +} + +# run_sql