Merge pull request #7094 from morozov/deprecate-get-name

Deprecate AbstractAsset::getName()

Author: morozov

UPGRADE.md

@@ -8,6 +8,13 @@ awareness about deprecated code.
 
 # Upgrade to 4.4
 
+## Deprecated `AbstractAsset::getName()`
+
+The `AbstractAsset::getName()` method has been deprecated. Instead, use `NamedObject::getObjectName()` or 
+`OptionallyQualifiedName::getObjectName()` to get the object representation of the name. SQL context, convert the
+resulting `Name` to SQL using `Name::toSQL()`. In other contexts, convert the resulting name to string using
+`Name::toString()`.
+
 ## Deprecated `AbstractAsset::isQuoted()`
 
 The `AbstractAsset::isQuoted()` method has been deprecated. The recommended approach depends on the object class:
@@ -326,7 +333,7 @@ The `Table::__construct()` method has been marked as internal. Use `Table::edito
 
 ## Deprecated `AbstractAsset::getShortestName()`
 
-The `AbstractAsset::getShortestName()` method has been deprecated. Use `AbstractAsset::getName()` instead.
+The `AbstractAsset::getShortestName()` method has been deprecated. Use `NamedObject::getObjectName()` instead.
 
 ## Deprecated `Sequence::isAutoIncrementsFor()`
 

docs/en/reference/schema-manager.rst

@@ -59,7 +59,7 @@ Now you can loop over the array inspecting each sequence object:
 
     <?php
     foreach ($sequences as $sequence) {
-        echo $sequence->getName() . "\n";
+        echo $sequence->getObjectName()->toString() . PHP_EOL;
     }
 
 listTableColumns()
@@ -79,7 +79,7 @@ Now you can loop over the array inspecting each column object:
 
     <?php
     foreach ($columns as $column) {
-        echo $column->getName() . ': ' . $column->getType() . "\n";
+        echo $column->getObjectName()->toString() . ': ' . $column->getType() . PHP_EOL;
     }
 
 introspectTable()
@@ -119,7 +119,7 @@ object:
 
     <?php
     foreach ($foreignKeys as $foreignKey) {
-        echo $foreignKey->getName() ."\n";
+        echo $foreignKey->getObjectName()->toString() . PHP_EOL;
     }
 
 listTableIndexes()
@@ -139,7 +139,12 @@ Now you can loop over the array inspecting each index object:
 
     <?php
     foreach ($indexes as $index) {
-        echo $index->getName() . ': ' . ($index->isUnique() ? 'unique' : 'not unique') . "\n";
+        echo $index->getObjectName()->toString() . ': ' . match($index->getType()) {
+            IndexType::REGULAR  => 'regular',
+            IndexType::UNIQUE   => 'unique',
+            IndexType::FULLTEXT => 'fulltext',
+            IndexType::SPATIAL  => 'spatial',
+        } . PHP_EOL;
     }
 
 listTables()
@@ -162,9 +167,9 @@ retrieved with the ``getColumns()`` method:
 
     <?php
     foreach ($tables as $table) {
-        echo $table->getName() . " columns:\n\n";
+        echo $table->getObjectName()->toString() . " columns:" . PHP_EOL;
         foreach ($table->getColumns() as $column) {
-            echo ' - ' . $column->getName() . "\n";
+            echo ' - ' . $column->getObjectName()->toString() . PHP_EOL;
         }
     }
 
@@ -185,7 +190,7 @@ Now you can loop over the array inspecting each view object:
 
     <?php
     foreach ($views as $view) {
-        echo $view->getName() . ': ' . $view->getSql() . "\n";
+        echo $view->getObjectName()->toString() . ': ' . $view->getSql() . PHP_EOL;
     }
 
 introspectSchema()

src/Schema/AbstractAsset.php

@@ -272,7 +272,7 @@ public function getNamespaceName(): ?string
      * The shortest name is stripped of the default namespace. All other
      * namespaced elements are returned as full-qualified names.
      *
-     * @deprecated Use {@link getName()} instead.
+     * @deprecated Use {@see NamedObject::getObjectName()} instead.
      */
     public function getShortestName(?string $defaultNamespaceName): string
     {
@@ -340,9 +340,20 @@ protected function trimQuotes(string $identifier): string
 
     /**
      * Returns the name of this schema asset.
+     *
+     * @deprecated Use {@see NamedObject::getObjectName()} or {@see OptionallyQualifiedName::getObjectName()} instead.
+     *             In SQL context, convert the resulting {@see Name} to SQL using {@see Name::toSQL()}. In other
+     *             contexts, convert the resulting name to string using {@see Name::toString()}.
      */
     public function getName(): string
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/7094',
+            '%s is deprecated and will be removed in 5.0.',
+            __METHOD__,
+        );
+
         if ($this->_namespace !== null) {
             return $this->_namespace . '.' . $this->_name;
         }

src/Schema/AbstractSchemaManager.php

@@ -88,7 +88,7 @@ public function listSchemaNames(): array
     /**
      * Lists the available sequences for this connection.
      *
-     * @return array<int, Sequence>
+     * @return list<Sequence>
      *
      * @throws Exception
      */
@@ -177,7 +177,7 @@ public function tableExists(string $tableName): bool
     /**
      * Returns a list of all tables in the current database.
      *
-     * @return array<int, non-empty-string>
+     * @return list<non-empty-string>
      *
      * @throws Exception
      */
@@ -196,9 +196,11 @@ public function listTableNames(): array
      * Filters asset names if they are configured to return only a subset of all
      * the found elements.
      *
-     * @param array<int, mixed> $assetNames
+     * @param list<N> $assetNames
      *
-     * @return array<int, mixed>
+     * @return list<N>
+     *
+     * @template N
      */
     private function filterAssetNames(array $assetNames): array
     {

src/Schema/Table.php

@@ -412,7 +412,7 @@ final public function renameColumn(string $oldName, string $newName): Column
         if ($oldName === $newName) {
             throw new LogicException(sprintf(
                 'Attempt to rename column "%s.%s" to the same name.',
-                $this->getName(),
+                $this->name->toString(),
                 $oldName,
             ));
         }
@@ -643,10 +643,11 @@ public function dropUniqueConstraint(string $name): void
     /**
      * Returns the list of table columns.
      *
-     * @return list<Column>
+     * @return non-empty-list<Column>
      */
     public function getColumns(): array
     {
+        /** @phpstan-ignore return.type */
         return array_values($this->_columns);
     }
 

tests/Functional/Driver/DBAL6024Test.php

@@ -54,7 +54,7 @@ public function testDropPrimaryKey(): void
         }
 
         $validationSchema = $schemaManager->introspectSchema();
-        $validationTable  = $validationSchema->getTable($table->getName());
+        $validationTable  = $validationSchema->getTable($table->getObjectName()->toString());
 
         self::assertNull($validationTable->getPrimaryKey());
     }

tests/Functional/Driver/DBAL6044Test.php

@@ -53,19 +53,19 @@ public function testUnloggedTables(): void
         $schemaManager = $this->connection->createSchemaManager();
 
         $validationSchema        = $schemaManager->introspectSchema();
-        $validationUnloggedTable = $validationSchema->getTable($unloggedTable->getName());
+        $validationUnloggedTable = $validationSchema->getTable($unloggedTable->getObjectName()->toString());
         self::assertTrue($validationUnloggedTable->getOption('unlogged'));
-        $validationLoggedTable = $validationSchema->getTable($loggedTable->getName());
+        $validationLoggedTable = $validationSchema->getTable($loggedTable->getObjectName()->toString());
         self::assertFalse($validationLoggedTable->getOption('unlogged'));
 
         $sql  = 'SELECT relpersistence FROM pg_class WHERE relname = ?';
         $stmt = $this->connection->prepare($sql);
 
-        $stmt->bindValue(1, $unloggedTable->getName());
+        $stmt->bindValue(1, $unloggedTable->getObjectName()->toString());
         $unloggedTablePersistenceType = $stmt->executeQuery()->fetchOne();
         self::assertEquals('u', $unloggedTablePersistenceType);
 
-        $stmt->bindValue(1, $loggedTable->getName());
+        $stmt->bindValue(1, $loggedTable->getObjectName()->toString());
         $loggedTablePersistenceType = $stmt->executeQuery()->fetchOne();
         self::assertEquals('p', $loggedTablePersistenceType);
     }

tests/Functional/Platform/AlterColumnTest.php

@@ -7,10 +7,13 @@
 use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
 use Doctrine\DBAL\Schema\Column;
 use Doctrine\DBAL\Schema\ColumnEditor;
+use Doctrine\DBAL\Schema\Name\UnqualifiedName;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Tests\FunctionalTestCase;
 use Doctrine\DBAL\Types\Types;
 
+use function array_map;
+
 class AlterColumnTest extends FunctionalTestCase
 {
     public function testColumnPositionRetainedAfterAltering(): void
@@ -45,12 +48,15 @@ public function testColumnPositionRetainedAfterAltering(): void
 
         $sm->alterTable($diff);
 
-        $table   = $sm->introspectTable('test_alter');
-        $columns = $table->getColumns();
+        $table = $sm->introspectTable('test_alter');
 
-        self::assertCount(2, $columns);
-        self::assertEqualsIgnoringCase('c1', $columns[0]->getName());
-        self::assertEqualsIgnoringCase('c2', $columns[1]->getName());
+        $this->assertUnqualifiedNameListEquals([
+            UnqualifiedName::unquoted('c1'),
+            UnqualifiedName::unquoted('c2'),
+        ], array_map(
+            static fn (Column $column): UnqualifiedName => $column->getObjectName(),
+            $table->getColumns(),
+        ));
     }
 
     public function testSupportsCollations(): void

tests/Functional/Platform/RenameColumnTest.php

@@ -6,13 +6,16 @@
 
 use Doctrine\DBAL\Exception;
 use Doctrine\DBAL\Schema\Column;
+use Doctrine\DBAL\Schema\Name\UnqualifiedName;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Schema\TableDiff;
 use Doctrine\DBAL\Tests\FunctionalTestCase;
 use Doctrine\DBAL\Types\Type;
 use Doctrine\DBAL\Types\Types;
 use PHPUnit\Framework\Attributes\DataProvider;
 
+use function array_map;
+
 class RenameColumnTest extends FunctionalTestCase
 {
     /**
@@ -56,12 +59,16 @@ public function testColumnPositionRetainedAfterImplicitRenaming(string $oldColum
 
         $sm->alterTable($diff);
 
-        $table   = $sm->introspectTable('test_rename');
-        $columns = $table->getColumns();
+        $table = $sm->introspectTable('test_rename');
+
+        $this->assertUnqualifiedNameListEquals([
+            UnqualifiedName::unquoted($newColumnName),
+            UnqualifiedName::unquoted('c2'),
+        ], array_map(
+            static fn (Column $column): UnqualifiedName => $column->getObjectName(),
+            $table->getColumns(),
+        ));
 
-        self::assertCount(2, $columns);
-        self::assertEqualsIgnoringCase($newColumnName, $columns[0]->getName());
-        self::assertEqualsIgnoringCase('c2', $columns[1]->getName());
         self::assertCount(1, self::getRenamedColumns($diff));
         self::assertCount(1, $diff->getRenamedColumns());
     }
@@ -75,7 +82,10 @@ public static function getRenamedColumns(TableDiff $tableDiff): array
                 continue;
             }
 
-            $oldColumnName           = $diff->getOldColumn()->getName();
+            $oldColumnName = $diff->getOldColumn()
+                ->getObjectName()
+                ->toString();
+
             $renamed[$oldColumnName] = $diff->getNewColumn();
         }
 
@@ -117,23 +127,27 @@ public function testColumnPositionRetainedAfterExplicitRenaming(string $oldColum
 
         $sm->alterTable($diff);
 
-        $table   = $sm->introspectTable('test_rename');
-        $columns = $table->getColumns();
+        $table = $sm->introspectTable('test_rename');
 
         self::assertCount(1, $diff->getChangedColumns());
         self::assertCount(1, $diff->getRenamedColumns());
         self::assertCount(1, $diff->getModifiedColumns());
-        self::assertCount(2, $columns);
-        self::assertEqualsIgnoringCase($newColumnName, $columns[0]->getName());
-        self::assertEqualsIgnoringCase('c2', $columns[1]->getName());
+
+        $this->assertUnqualifiedNameListEquals([
+            UnqualifiedName::unquoted($newColumnName),
+            UnqualifiedName::unquoted('c2'),
+        ], array_map(
+            static fn (Column $column): UnqualifiedName => $column->getObjectName(),
+            $table->getColumns(),
+        ));
     }
 
     /** @return iterable<array{non-empty-string,non-empty-string}> */
     public static function columnNameProvider(): iterable
     {
         yield ['c1', 'c1_x'];
         yield ['C1', 'c1_x'];
-        yield ['importantColumn', 'veryImportantColumn'];
+        yield ['importantColumn', 'very_important_column'];
     }
 
     /** @throws Exception */

tests/Functional/Schema/AlterTableTest.php

@@ -413,7 +413,10 @@ private function testMigration(Table $oldTable, callable $migration, ?Comparator
 
         $schemaManager->alterTable($diff);
 
-        $introspectedTable = $schemaManager->introspectTable($newTable->getName());
+        $introspectedTable = $schemaManager->introspectTable(
+            $newTable->getObjectName()
+                ->toString(),
+        );
 
         $diff = $schemaManager->createComparator()
             ->compareTables($newTable, $introspectedTable);