Fix various issues for 5.x release (#998)

- Fix README coverage badge pointing to 3.x instead of 5.x
- Update MigrationHelper comments (remove outdated phinx TODOs)
- Add database-specific limitations documentation
- Fix PHPStan issues by adding proper type hints for Bake event subjects
- Update PHPStan baseline to remove fixed errors

Author: dereuromark

README.md

@@ -1,7 +1,7 @@
 # Migrations plugin for CakePHP
 
 [![CI](https://github.com/cakephp/migrations/actions/workflows/ci.yml/badge.svg)](https://github.com/cakephp/migrations/actions/workflows/ci.yml)
-[![Coverage Status](https://img.shields.io/codecov/c/github/cakephp/migrations/3.x.svg?style=flat-square)](https://app.codecov.io/github/cakephp/migrations/tree/3.x)
+[![Coverage Status](https://img.shields.io/codecov/c/github/cakephp/migrations/5.x.svg?style=flat-square)](https://app.codecov.io/github/cakephp/migrations/tree/5.x)
 [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.txt)
 [![Total Downloads](https://img.shields.io/packagist/dt/cakephp/migrations.svg?style=flat-square)](https://packagist.org/packages/cakephp/migrations)
 

docs/en/writing-migrations.rst

@@ -2315,3 +2315,76 @@ Changing templates
 
 See :ref:`custom-seed-migration-templates` for how to customize the templates
 used to generate migrations.
+
+Database-Specific Limitations
+=============================
+
+While Migrations aims to provide a database-agnostic API, some features have
+database-specific limitations or are not available on all platforms.
+
+SQL Server
+----------
+
+The following features are not supported on SQL Server:
+
+**Check Constraints**
+
+Check constraints are not currently implemented for SQL Server. Attempting to
+use ``addCheckConstraint()`` or ``dropCheckConstraint()`` will throw a
+``BadMethodCallException``.
+
+**Table Comments**
+
+SQL Server does not support table comments. Attempting to use ``changeComment()``
+will throw a ``BadMethodCallException``.
+
+**INSERT IGNORE / insertOrSkip()**
+
+SQL Server does not support the ``INSERT IGNORE`` syntax used by ``insertOrSkip()``.
+This method will throw a ``RuntimeException`` on SQL Server. Use ``insertOrUpdate()``
+instead for upsert operations, which uses ``MERGE`` statements on SQL Server.
+
+SQLite
+------
+
+**Foreign Key Names**
+
+SQLite does not support named foreign keys. The foreign key constraint name option
+is ignored when creating foreign keys on SQLite.
+
+**Table Comments**
+
+SQLite does not support table comments directly. Comments are stored as metadata
+but not in the database itself.
+
+**Check Constraint Modifications**
+
+SQLite does not support ``ALTER TABLE`` operations for check constraints. Adding or
+dropping check constraints requires recreating the entire table, which is handled
+automatically by the adapter.
+
+**Table Partitioning**
+
+SQLite does not support table partitioning.
+
+PostgreSQL
+----------
+
+**KEY Partitioning**
+
+PostgreSQL does not support MySQL's ``KEY`` partitioning type. Use ``HASH``
+partitioning instead for similar distribution behavior.
+
+MySQL/MariaDB
+-------------
+
+**insertOrUpdate() Conflict Columns**
+
+For MySQL, the ``$conflictColumns`` parameter in ``insertOrUpdate()`` is ignored
+because MySQL's ``ON DUPLICATE KEY UPDATE`` automatically applies to all unique
+constraints. PostgreSQL and SQLite require this parameter to be specified.
+
+**MariaDB GIS/Geometry**
+
+Some geometry column features may not work correctly on MariaDB due to differences
+in GIS implementation compared to MySQL.

phpstan-baseline.neon

@@ -1,23 +1,5 @@
 parameters:
 	ignoreErrors:
-		-
-			message: '#^Call to an undefined method object\:\:loadHelper\(\)\.$#'
-			identifier: method.notFound
-			count: 1
-			path: src/Command/BakeMigrationCommand.php
-
-		-
-			message: '#^Call to an undefined method object\:\:loadHelper\(\)\.$#'
-			identifier: method.notFound
-			count: 1
-			path: src/Command/BakeMigrationDiffCommand.php
-
-		-
-			message: '#^Call to an undefined method object\:\:loadHelper\(\)\.$#'
-			identifier: method.notFound
-			count: 1
-			path: src/Command/BakeMigrationSnapshotCommand.php
-
 		-
 			message: '#^PHPDoc tag @var with type string is not subtype of native type non\-falsy\-string\|true\.$#'
 			identifier: varTag.nativeType

src/Command/BakeMigrationCommand.php

@@ -48,7 +48,9 @@ public static function defaultName(): string
     public function bake(string $name, Arguments $args, ConsoleIo $io): void
     {
         EventManager::instance()->on('Bake.initialize', function (Event $event): void {
-            $event->getSubject()->loadHelper('Migrations.Migration');
+            /** @var \Bake\View\BakeView $view */
+            $view = $event->getSubject();
+            $view->loadHelper('Migrations.Migration');
         });
         $this->_name = $name;
 

src/Command/BakeMigrationDiffCommand.php

@@ -128,7 +128,9 @@ public function bake(string $name, Arguments $args, ConsoleIo $io): void
         assert($connection instanceof Connection);
 
         EventManager::instance()->on('Bake.initialize', function (Event $event) use ($collection, $connection): void {
-            $event->getSubject()->loadHelper('Migrations.Migration', [
+            /** @var \Bake\View\BakeView $view */
+            $view = $event->getSubject();
+            $view->loadHelper('Migrations.Migration', [
                 'collection' => $collection,
                 'connection' => $connection,
             ]);

src/Command/BakeMigrationSnapshotCommand.php

@@ -59,7 +59,9 @@ public function bake(string $name, Arguments $args, ConsoleIo $io): void
         assert($connection instanceof Connection);
 
         EventManager::instance()->on('Bake.initialize', function (Event $event) use ($collection, $connection): void {
-            $event->getSubject()->loadHelper('Migrations.Migration', [
+            /** @var \Bake\View\BakeView $view */
+            $view = $event->getSubject();
+            $view->loadHelper('Migrations.Migration', [
                 'collection' => $collection,
                 'connection' => $connection,
             ]);

src/View/Helper/MigrationHelper.php

@@ -418,13 +418,14 @@ public function getColumnOption(array $options): array
             unset($columnOptions['collate']);
         }
 
-        // TODO deprecate precision/scale and align with cakephp/database in 5.x
-        // TODO this can be cleaned up when we stop using phinx data structures for column definitions
+        // Handle precision/scale conversion between CakePHP's TableSchema format and SQL standard format.
+        // TableSchema uses: length=total digits, precision=decimal places
+        // Migrations uses SQL standard: precision=total digits, scale=decimal places
         if (!isset($columnOptions['precision']) || $columnOptions['precision'] == null) {
             unset($columnOptions['precision']);
         } else {
-            // due to Phinx using different naming for the precision and scale to CakePHP
-            // Only convert precision to scale if scale is not already set (for decimal columns from diff)
+            // Convert CakePHP's precision (decimal places) to Migrations' scale
+            // Only convert if scale is not already set (for decimal columns from diff)
             if (!isset($columnOptions['scale'])) {
                 $columnOptions['scale'] = $columnOptions['precision'];
             }