[12.x] Allow enums on model connection property and methods (#56896)

jnoordsij · taylorotwell · web-flow · commit 5680b61706c4 · 2025-09-03T11:43:20.000-05:00
* Allow setting connection by enum value in Model

* Add basic tests for connection enums in models

* formatting

---------

Co-authored-by: Taylor Otwell &lt;taylor@laravel.com&gt;
diff --git a/src/Illuminate/Database/Eloquent/Factories/Factory.php b/src/Illuminate/Database/Eloquent/Factories/Factory.php
@@ -16,6 +16,9 @@
 use Illuminate\Support\Traits\ForwardsCalls;
 use Illuminate\Support\Traits\Macroable;
 use Throwable;
+use UnitEnum;
+
+use function Illuminate\Support\enum_value;
 
 /**
  * @template TModel of \Illuminate\Database\Eloquent\Model
@@ -101,7 +104,7 @@ abstract class Factory
     /**
      * The name of the database connection that will be used to create the models.
      *
-     * @var string|null
+     * @var \UnitEnum|string|null
      */
     protected $connection;
 
@@ -156,7 +159,7 @@ abstract class Factory
      * @param  \Illuminate\Support\Collection|null  $for
      * @param  \Illuminate\Support\Collection|null  $afterMaking
      * @param  \Illuminate\Support\Collection|null  $afterCreating
-     * @param  string|null  $connection
+     * @param  \UnitEnum|string|null  $connection
      * @param  \Illuminate\Support\Collection|null  $recycle
      * @param  bool|null  $expandRelationships
      * @param  array  $excludeRelationships
@@ -802,16 +805,16 @@ public function withoutParents($parents = [])
      */
     public function getConnectionName()
     {
-        return $this->connection;
+        return enum_value($this->connection);
     }
 
     /**
      * Specify the database connection that should be used to generate models.
      *
-     * @param  string  $connection
+     * @param  \UnitEnum|string  $connection
      * @return static
      */
-    public function connection(string $connection)
+    public function connection(UnitEnum|string $connection)
     {
         return $this->newInstance(['connection' => $connection]);
     }
diff --git a/src/Illuminate/Database/Eloquent/Model.php b/src/Illuminate/Database/Eloquent/Model.php
@@ -33,6 +33,8 @@
 use ReflectionMethod;
 use Stringable;
 
+use function Illuminate\Support\enum_value;
+
 abstract class Model implements Arrayable, ArrayAccess, CanBeEscapedWhenCastToString, HasBroadcastChannel, Jsonable, JsonSerializable, QueueableEntity, Stringable, UrlRoutable
 {
     use Concerns\HasAttributes,
@@ -52,7 +54,7 @@ abstract class Model implements Arrayable, ArrayAccess, CanBeEscapedWhenCastToSt
     /**
      * The connection name for the model.
      *
-     * @var string|null
+     * @var \UnitEnum|string|null
      */
     protected $connection;
 
@@ -717,7 +719,7 @@ public function newInstance($attributes = [], $exists = false)
      * Create a new model instance that is existing.
      *
      * @param  array<string, mixed>  $attributes
-     * @param  string|null  $connection
+     * @param  \UnitEnum|string|null  $connection
      * @return static
      */
     public function newFromBuilder($attributes = [], $connection = null)
@@ -726,7 +728,7 @@ public function newFromBuilder($attributes = [], $connection = null)
 
         $model->setRawAttributes((array) $attributes, true);
 
-        $model->setConnection($connection ?: $this->getConnectionName());
+        $model->setConnection($connection ?? $this->getConnectionName());
 
         $model->fireModelEvent('retrieved', false);
 
@@ -736,7 +738,7 @@ public function newFromBuilder($attributes = [], $connection = null)
     /**
      * Begin querying the model on a given connection.
      *
-     * @param  string|null  $connection
+     * @param  \UnitEnum|string|null  $connection
      * @return \Illuminate\Database\Eloquent\Builder<static>
      */
     public static function on($connection = null)
@@ -1951,13 +1953,13 @@ public function getConnection()
      */
     public function getConnectionName()
     {
-        return $this->connection;
+        return enum_value($this->connection);
     }
 
     /**
      * Set the connection associated with the model.
      *
-     * @param  string|null  $name
+     * @param  \UnitEnum|string|null  $name
      * @return $this
      */
     public function setConnection($name)
@@ -1970,7 +1972,7 @@ public function setConnection($name)
     /**
      * Resolve a connection instance.
      *
-     * @param  string|null  $connection
+     * @param  \UnitEnum|string|null  $connection
      * @return \Illuminate\Database\Connection
      */
     public static function resolveConnection($connection = null)
diff --git a/tests/Database/DatabaseEloquentModelTest.php b/tests/Database/DatabaseEloquentModelTest.php
@@ -56,6 +56,7 @@
 use InvalidArgumentException;
 use LogicException;
 use Mockery as m;
+use PHPUnit\Framework\Attributes\TestWith;
 use PHPUnit\Framework\TestCase;
 use ReflectionClass;
 use stdClass;
@@ -1317,6 +1318,23 @@ public function testConnectionManagement()
         $this->assertSame('bar', $model->getConnection());
     }
 
+    #[TestWith(['Foo'])]
+    #[TestWith([ConnectionName::Foo])]
+    #[TestWith([ConnectionNameBacked::Foo])]
+    public function testConnectionEnums(string|\UnitEnum $connectionName)
+    {
+        EloquentModelStub::setConnectionResolver($resolver = m::mock(ConnectionResolverInterface::class));
+        $model = new EloquentModelStub;
+
+        $retval = $model->setConnection($connectionName);
+        $this->assertEquals($retval, $model);
+        $this->assertSame('Foo', $model->getConnectionName());
+
+        $resolver->shouldReceive('connection')->once()->with('Foo')->andReturn('bar');
+
+        $this->assertSame('bar', $model->getConnection());
+    }
+
     public function testToArray()
     {
         $model = new EloquentModelStub;
@@ -4432,3 +4450,15 @@ public function __toString()
         return $this->cast;
     }
 }
+
+enum ConnectionName
+{
+    case Foo;
+    case Bar;
+}
+
+enum ConnectionNameBacked: string
+{
+    case Foo = 'Foo';
+    case Bar = 'Bar';
+}
