Convert enum-like classes to enums

UPGRADE.md

@@ -8,6 +8,18 @@ awareness about deprecated code.
 
 # Upgrade to 4.0
 
+## BC BREAK: converted enum-like classes to enums
+
+The following classes have been converted to enums:
+
+1. `Doctrine\DBAL\ColumnCase`,
+2. `Doctrine\DBAL\LockMode`,
+3. `Doctrine\DBAL\TransactionIsolationLevel`,
+4. `Doctrine\DBAL\Platforms\DateIntervalUnit`,
+5. `Doctrine\DBAL\Platforms\TrimMode`.
+
+The corresponding class constants are now instances of their enum type.
+
 ## BC BREAK: renamed SQLite platform classes
 
 1. `SqlitePlatform` => `SQLitePlatform`

src/ColumnCase.php

@@ -7,24 +7,15 @@
 /**
  * Contains portable column case conversions.
  */
-final class ColumnCase
+enum ColumnCase
 {
     /**
      * Convert column names to upper case.
      */
-    public const UPPER = 1;
+    case UPPER;
 
     /**
      * Convert column names to lower case.
      */
-    public const LOWER = 2;
-
-    /**
-     * This class cannot be instantiated.
-     *
-     * @codeCoverageIgnore
-     */
-    private function __construct()
-    {
-    }
+    case LOWER;
 }

src/Connection.php

@@ -96,10 +96,8 @@ class Connection implements ServerVersionProvider
 
     /**
      * The currently active transaction isolation level or NULL before it has been determined.
-     *
-     * @var TransactionIsolationLevel::*|null
      */
-    private ?int $transactionIsolationLevel = null;
+    private ?TransactionIsolationLevel $transactionIsolationLevel = null;
 
     /**
      * The parameters used during creation of the Connection instance.
@@ -501,11 +499,11 @@ public function close(): void
     /**
      * Sets the transaction isolation level.
      *
-     * @param TransactionIsolationLevel::* $level The level to set.
+     * @param TransactionIsolationLevel $level The level to set.
      *
      * @throws Exception
      */
-    public function setTransactionIsolation(int $level): void
+    public function setTransactionIsolation(TransactionIsolationLevel $level): void
     {
         $this->transactionIsolationLevel = $level;
 
@@ -515,11 +513,11 @@ public function setTransactionIsolation(int $level): void
     /**
      * Gets the currently active transaction isolation level.
      *
-     * @return TransactionIsolationLevel::* The current transaction isolation level.
+     * @return TransactionIsolationLevel The current transaction isolation level.
      *
      * @throws Exception
      */
-    public function getTransactionIsolation(): int
+    public function getTransactionIsolation(): TransactionIsolationLevel
     {
         return $this->transactionIsolationLevel ??= $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();
     }

src/LockMode.php

@@ -5,21 +5,12 @@
 namespace Doctrine\DBAL;
 
 /**
- * Contains all DBAL LockModes.
+ * Contains all supported lock modes.
  */
-class LockMode
+enum LockMode
 {
-    final public const NONE              = 0;
-    final public const OPTIMISTIC        = 1;
-    final public const PESSIMISTIC_READ  = 2;
-    final public const PESSIMISTIC_WRITE = 4;
-
-    /**
-     * Private constructor. This class cannot be instantiated.
-     *
-     * @codeCoverageIgnore
-     */
-    final private function __construct()
-    {
-    }
+    case NONE;
+    case OPTIMISTIC;
+    case PESSIMISTIC_READ;
+    case PESSIMISTIC_WRITE;
 }

src/Platforms/AbstractMySQLPlatform.php

@@ -85,11 +85,11 @@ protected function getDateArithmeticIntervalExpression(
         string $date,
         string $operator,
         string $interval,
-        string $unit
+        DateIntervalUnit $unit
     ): string {
         $function = $operator === '+' ? 'DATE_ADD' : 'DATE_SUB';
 
-        return $function . '(' . $date . ', INTERVAL ' . $interval . ' ' . $unit . ')';
+        return $function . '(' . $date . ', INTERVAL ' . $interval . ' ' . $unit->value . ')';
     }
 
     public function getDateDiffExpression(string $date1, string $date2): string
@@ -677,7 +677,7 @@ public function getDropUniqueConstraintSQL(string $name, string $tableName): str
         return $this->getDropIndexSQL($name, $tableName);
     }
 
-    public function getSetTransactionIsolationSQL(int $level): string
+    public function getSetTransactionIsolationSQL(TransactionIsolationLevel $level): string
     {
         return 'SET SESSION TRANSACTION ISOLATION LEVEL ' . $this->_getTransactionIsolationLevelSQL($level);
     }
@@ -778,7 +778,7 @@ public function quoteStringLiteral(string $str): string
         return parent::quoteStringLiteral($str);
     }
 
-    public function getDefaultTransactionIsolationLevel(): int
+    public function getDefaultTransactionIsolationLevel(): TransactionIsolationLevel
     {
         return TransactionIsolationLevel::REPEATABLE_READ;
     }

src/Platforms/AbstractPlatform.php

@@ -17,7 +17,6 @@
 use Doctrine\DBAL\Events;
 use Doctrine\DBAL\Exception;
 use Doctrine\DBAL\Exception\ColumnLengthRequired;
-use Doctrine\DBAL\Exception\InvalidLockMode;
 use Doctrine\DBAL\LockMode;
 use Doctrine\DBAL\Platforms\Exception\NoColumnsSpecifiedForTable;
 use Doctrine\DBAL\Platforms\Exception\NotSupported;
@@ -418,12 +417,10 @@ public function getModExpression(string $dividend, string $divisor): string
      * Returns the SQL snippet to trim a string.
      *
      * @param string      $str  The expression to apply the trim to.
-     * @param int         $mode The position of the trim (leading/trailing/both).
+     * @param TrimMode    $mode The position of the trim.
      * @param string|null $char The char to trim, has to be quoted already. Defaults to space.
-     *
-     * @throws InvalidArgumentException
      */
-    public function getTrimExpression(string $str, int $mode = TrimMode::UNSPECIFIED, ?string $char = null): string
+    public function getTrimExpression(string $str, TrimMode $mode = TrimMode::UNSPECIFIED, ?string $char = null): string
     {
         $tokens = [];
 
@@ -442,14 +439,6 @@ public function getTrimExpression(string $str, int $mode = TrimMode::UNSPECIFIED
             case TrimMode::BOTH:
                 $tokens[] = 'BOTH';
                 break;
-
-            default:
-                throw new InvalidArgumentException(
-                    sprintf(
-                        'The value of $mode is expected to be one of the TrimMode constants, %d given.',
-                        $mode
-                    )
-                );
         }
 
         if ($char !== null) {
@@ -688,18 +677,18 @@ public function getDateSubYearsExpression(string $date, string $years): string
     /**
      * Returns the SQL for a date arithmetic expression.
      *
-     * @param string $date     SQL expression representing a date to perform the arithmetic operation on.
-     * @param string $operator The arithmetic operator (+ or -).
-     * @param string $interval SQL expression representing the value of the interval that shall be calculated
-     *                         into the date.
-     * @param string $unit     The unit of the interval that shall be calculated into the date.
+     * @param string           $date     SQL expression representing a date to perform the arithmetic operation on.
+     * @param string           $operator The arithmetic operator (+ or -).
+     * @param string           $interval SQL expression representing the value of the interval that shall be calculated
+     *                                   into the date.
+     * @param DateIntervalUnit $unit     The unit of the interval that shall be calculated into the date.
      *                         One of the DATE_INTERVAL_UNIT_* constants.
      */
     abstract protected function getDateArithmeticIntervalExpression(
         string $date,
         string $operator,
         string $interval,
-        string $unit
+        DateIntervalUnit $unit
     ): string;
 
     /**
@@ -753,18 +742,10 @@ public function getForUpdateSQL(): string
      * ANSI SQL FOR UPDATE specification.
      *
      * @param string $fromClause The FROM clause to append the hint for the given lock mode to
-     * @param int    $lockMode   One of the Doctrine\DBAL\LockMode::* constants
-     * @psalm-param LockMode::* $lockMode
      */
-    public function appendLockHint(string $fromClause, int $lockMode): string
+    public function appendLockHint(string $fromClause, LockMode $lockMode): string
     {
-        return match ($lockMode) {
-            LockMode::NONE,
-            LockMode::OPTIMISTIC,
-            LockMode::PESSIMISTIC_READ,
-            LockMode::PESSIMISTIC_WRITE => $fromClause,
-            default => throw InvalidLockMode::fromLockMode($lockMode),
-        };
+        return $fromClause;
     }
 
     /**
@@ -1992,17 +1973,14 @@ public function getCurrentTimestampSQL(): string
 
     /**
      * Returns the SQL for a given transaction isolation level Connection constant.
-     *
-     * @throws InvalidArgumentException
      */
-    protected function _getTransactionIsolationLevelSQL(int $level): string
+    protected function _getTransactionIsolationLevelSQL(TransactionIsolationLevel $level): string
     {
         return match ($level) {
             TransactionIsolationLevel::READ_UNCOMMITTED => 'READ UNCOMMITTED',
             TransactionIsolationLevel::READ_COMMITTED => 'READ COMMITTED',
             TransactionIsolationLevel::REPEATABLE_READ => 'REPEATABLE READ',
             TransactionIsolationLevel::SERIALIZABLE => 'SERIALIZABLE',
-            default => throw new InvalidArgumentException(sprintf('Invalid isolation level "%s".', $level)),
         };
     }
 
@@ -2068,7 +2046,7 @@ public function getDropDatabaseSQL(string $name): string
     /**
      * Returns the SQL to set the transaction isolation level.
      */
-    abstract public function getSetTransactionIsolationSQL(int $level): string;
+    abstract public function getSetTransactionIsolationSQL(TransactionIsolationLevel $level): string;
 
     /**
      * Obtains DBMS specific SQL to be used to create datetime columns in
@@ -2115,11 +2093,9 @@ public function getFloatDeclarationSQL(array $column): string
     /**
      * Gets the default transaction isolation level of the platform.
      *
-     * @see TransactionIsolationLevel
-     *
-     * @return TransactionIsolationLevel::* The default isolation level.
+     * @return TransactionIsolationLevel The default isolation level.
      */
-    public function getDefaultTransactionIsolationLevel(): int
+    public function getDefaultTransactionIsolationLevel(): TransactionIsolationLevel
     {
         return TransactionIsolationLevel::READ_COMMITTED;
     }

src/Platforms/DB2Platform.php

@@ -14,6 +14,7 @@
 use Doctrine\DBAL\Schema\Identifier;
 use Doctrine\DBAL\Schema\Index;
 use Doctrine\DBAL\Schema\TableDiff;
+use Doctrine\DBAL\TransactionIsolationLevel;
 
 use function array_merge;
 use function count;
@@ -133,7 +134,7 @@ protected function getDateArithmeticIntervalExpression(
         string $date,
         string $operator,
         string $interval,
-        string $unit
+        DateIntervalUnit $unit
     ): string {
         switch ($unit) {
             case DateIntervalUnit::WEEK:
@@ -147,7 +148,7 @@ protected function getDateArithmeticIntervalExpression(
                 break;
         }
 
-        return $date . ' ' . $operator . ' ' . $interval . ' ' . $unit;
+        return $date . ' ' . $operator . ' ' . $interval . ' ' . $unit->value;
     }
 
     public function getDateDiffExpression(string $date1, string $date2): string
@@ -195,7 +196,7 @@ public function getTruncateTableSQL(string $tableName, bool $cascade = false): s
      *
      * @throws Exception
      */
-    public function getSetTransactionIsolationSQL(int $level): string
+    public function getSetTransactionIsolationSQL(TransactionIsolationLevel $level): string
     {
         throw NotSupported::new(__METHOD__);
     }

src/Platforms/DateIntervalUnit.php

@@ -4,28 +4,14 @@
 
 namespace Doctrine\DBAL\Platforms;
 
-final class DateIntervalUnit
+enum DateIntervalUnit: string
 {
-    public const SECOND = 'SECOND';
-
-    public const MINUTE = 'MINUTE';
-
-    public const HOUR = 'HOUR';
-
-    public const DAY = 'DAY';
-
-    public const WEEK = 'WEEK';
-
-    public const MONTH = 'MONTH';
-
-    public const QUARTER = 'QUARTER';
-
-    public const YEAR = 'YEAR';
-
-    /**
-     * @codeCoverageIgnore
-     */
-    private function __construct()
-    {
-    }
+    case SECOND  = 'SECOND';
+    case MINUTE  = 'MINUTE';
+    case HOUR    = 'HOUR';
+    case DAY     = 'DAY';
+    case WEEK    = 'WEEK';
+    case MONTH   = 'MONTH';
+    case QUARTER = 'QUARTER';
+    case YEAR    = 'YEAR';
 }