refactor: improve IDE autocompletion for schema() method in migrations

- Remove unnecessary @mixin and @method annotations from class PHPDoc
- Enhance schema() method PHPDoc with detailed description of available methods
- Add example with addForeignKey() method
- @return DdlQueryBuilder annotation ensures IDE autocompletion works correctly

Author: tommyknocker

src/migrations/Migration.php

@@ -14,59 +14,6 @@
  *
  * This class provides common methods for migrations, similar to Yii2's Migration class.
  * All migrations should extend this class and implement up() and down() methods.
- *
- * @mixin DdlQueryBuilder
- *
- * @method DdlQueryBuilder createTable(string $table, array $columns, array $options = [])
- * @method DdlQueryBuilder createTableIfNotExists(string $table, array $columns, array $options = [])
- * @method DdlQueryBuilder dropTable(string $table)
- * @method DdlQueryBuilder dropTableIfExists(string $table)
- * @method DdlQueryBuilder renameTable(string $table, string $newName)
- * @method DdlQueryBuilder truncateTable(string $table)
- * @method DdlQueryBuilder addColumn(string $table, string $column, \tommyknocker\pdodb\query\schema\ColumnSchema|array|string $type)
- * @method DdlQueryBuilder dropColumn(string $table, string $column)
- * @method DdlQueryBuilder alterColumn(string $table, string $column, \tommyknocker\pdodb\query\schema\ColumnSchema|array|string $type)
- * @method DdlQueryBuilder renameColumn(string $table, string $oldName, string $newName)
- * @method DdlQueryBuilder createIndex(string $name, string $table, string|array $columns, bool $unique = false, ?string $where = null, ?array $includeColumns = null, array $options = [])
- * @method DdlQueryBuilder dropIndex(string $name, string $table)
- * @method DdlQueryBuilder createFulltextIndex(string $name, string $table, string|array $columns, ?string $parser = null)
- * @method DdlQueryBuilder createSpatialIndex(string $name, string $table, string|array $columns)
- * @method DdlQueryBuilder renameIndex(string $oldName, string $table, string $newName)
- * @method DdlQueryBuilder renameForeignKey(string $oldName, string $table, string $newName)
- * @method DdlQueryBuilder addForeignKey(string $name, string $table, string|array $columns, string $refTable, string|array $refColumns, ?string $delete = null, ?string $update = null)
- * @method DdlQueryBuilder dropForeignKey(string $name, string $table)
- * @method DdlQueryBuilder addPrimaryKey(string $name, string $table, string|array $columns)
- * @method DdlQueryBuilder dropPrimaryKey(string $name, string $table)
- * @method DdlQueryBuilder addUnique(string $name, string $table, string|array $columns)
- * @method DdlQueryBuilder dropUnique(string $name, string $table)
- * @method DdlQueryBuilder addCheck(string $name, string $table, string $expression)
- * @method DdlQueryBuilder dropCheck(string $name, string $table)
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema primaryKey(?int $length = null)
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema bigPrimaryKey()
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema string(?int $length = null)
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema text()
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema char(?int $length = null)
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema integer(?int $length = null)
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema bigInteger()
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema smallInteger(?int $length = null)
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema boolean()
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema float(?int $precision = null, ?int $scale = null)
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema decimal(int $precision = 10, int $scale = 2)
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema date()
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema time()
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema datetime()
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema timestamp()
- * @method \tommyknocker\pdodb\query\schema\ColumnSchema json()
- * @method bool tableExists(string $table)
- * @method bool indexExists(string $name, string $table)
- * @method bool foreignKeyExists(string $name, string $table)
- * @method bool checkExists(string $name, string $table)
- * @method bool uniqueExists(string $name, string $table)
- * @method array getIndexes(string $table)
- * @method array getForeignKeys(string $table)
- * @method array getCheckConstraints(string $table)
- * @method array getUniqueConstraints(string $table)
- * @method \tommyknocker\pdodb\dialects\DialectInterface getDialect()
  */
 abstract class Migration implements MigrationInterface
 {
@@ -99,7 +46,13 @@ abstract public function down(): void;
      * Provides IDE autocompletion for schema operations.
      * All methods from DdlQueryBuilder are available through this method.
      *
-     * @return DdlQueryBuilder
+     * @return DdlQueryBuilder Returns DdlQueryBuilder instance with all schema methods available.
+     *                        IDE will provide autocompletion for methods like:
+     *                        - createTable(), dropTable(), renameTable()
+     *                        - addColumn(), dropColumn(), alterColumn()
+     *                        - createIndex(), dropIndex(), createFulltextIndex()
+     *                        - addForeignKey(), dropForeignKey()
+     *                        - primaryKey(), string(), integer(), text(), etc.
      *
      * @example
      * // Create a table
@@ -116,6 +69,10 @@ abstract public function down(): void;
      * @example
      * // Create an index
      * $this->schema()->createIndex('idx_email', 'users', 'email');
+     *
+     * @example
+     * // Add foreign key
+     * $this->schema()->addForeignKey('fk_user_profile', 'profiles', 'user_id', 'users', 'id', 'CASCADE', 'CASCADE');
      */
     protected function schema(): DdlQueryBuilder
     {