PHPORM-220 Deprecate using the $collection property to customize the name

CHANGELOG.md

@@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file.
 
 * Add `Query\Builder::incrementEach()` and `decrementEach()` methods by @SmallRuralDog in [#2550](https://github.com/mongodb/laravel-mongodb/pull/2550)
 * Deprecate `Connection::collection()` and `Schema\Builder::collection()` methods by @GromNaN in [#3062](https://github.com/mongodb/laravel-mongodb/pull/3062)
+* Deprecate `Model::$collection` property to customize collection name. Use `$table` instead by @GromNaN in [#3064](https://github.com/mongodb/laravel-mongodb/pull/3064)
 
 ## [4.7.0] - 2024-07-19
 

docs/eloquent-models/model-class.txt

@@ -108,7 +108,7 @@ Change the Model Collection Name
 
 By default, the model uses the snake case plural form of your model
 class name. To change the name of the collection the model uses to retrieve
-and save data in MongoDB, override the ``$collection`` property of the model
+and save data in MongoDB, override the ``$table`` property of the model
 class.
 
 .. note::
@@ -124,7 +124,7 @@ The following example specifies the custom MongoDB collection name,
    :emphasize-lines: 9
    :dedent:
 
-Without overriding the ``$collection`` property, this model maps to the
+Without overriding the ``$table`` property, this model maps to the
 ``planets`` collection. With the overridden property, the example class stores
 the model in the ``celestial_body`` collection.
 

docs/includes/auth/AuthUser.php

@@ -7,7 +7,7 @@
 class User extends Authenticatable
 {
     protected $connection = 'mongodb';
-    protected $collection = 'users';
+    protected $table = 'users';
 
     protected $fillable = [
         'name',

docs/includes/auth/PersonalAccessToken.php

@@ -10,7 +10,7 @@ class PersonalAccessToken extends SanctumToken
     use DocumentModel;
 
     protected $connection = 'mongodb';
-    protected $collection = 'personal_access_tokens';
+    protected $table = 'personal_access_tokens';
     protected $primaryKey = '_id';
     protected $keyType = 'string';
 }

docs/includes/eloquent-models/PlanetCollection.php

@@ -6,5 +6,5 @@
 
 class Planet extends Model
 {
-    protected $collection = 'celestial_body';
+    protected $table = 'celestial_body';
 }

docs/includes/fundamentals/read-operations/Movie.php

@@ -7,6 +7,6 @@
 class Movie extends Model
 {
     protected $connection = 'mongodb';
-    protected $collection = 'movies';
+    protected $table = 'movies';
     protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot'];
 }

docs/includes/usage-examples/Movie.php

@@ -7,6 +7,6 @@
 class Movie extends Model
 {
     protected $connection = 'mongodb';
-    protected $collection = 'movies';
+    protected $table = 'movies';
     protected $fillable = ['title', 'year', 'runtime', 'imdb', 'plot'];
 }

src/Eloquent/DocumentModel.php

@@ -46,8 +46,11 @@
 use function str_contains;
 use function str_starts_with;
 use function strcmp;
+use function trigger_error;
 use function var_export;
 
+use const E_USER_DEPRECATED;
+
 trait DocumentModel
 {
     use HybridRelations;
@@ -141,7 +144,13 @@ public function freshTimestamp()
     /** @inheritdoc */
     public function getTable()
     {
-        return $this->collection ?? parent::getTable();
+        if (isset($this->collection)) {
+            trigger_error('Since mongodb/laravel-mongodb 4.8: Using "$collection" property is deprecated. Use "$table" instead.', E_USER_DEPRECATED);
+
+            return $this->collection;
+        }
+
+        return parent::getTable();
     }
 
     /** @inheritdoc */

tests/Models/Birthday.php

@@ -19,7 +19,7 @@ class Birthday extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'birthday';
+    protected $table = 'birthday';
     protected $fillable   = ['name', 'birthday'];
 
     protected $casts = ['birthday' => 'datetime'];

tests/Models/Book.php

@@ -20,7 +20,7 @@ class Book extends Model
     protected $primaryKey = 'title';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'books';
+    protected $table = 'books';
     protected static $unguarded = true;
 
     public function author(): BelongsTo

tests/Models/Casting.php

@@ -10,7 +10,7 @@
 class Casting extends Model
 {
     protected $connection = 'mongodb';
-    protected string $collection = 'casting';
+    protected $table = 'casting';
 
     protected $fillable = [
         'uuid',

tests/Models/Client.php

@@ -17,7 +17,7 @@ class Client extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'clients';
+    protected $table = 'clients';
     protected static $unguarded = true;
 
     public function users(): BelongsToMany

tests/Models/Experience.php

@@ -15,7 +15,7 @@ class Experience extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'experiences';
+    protected $table = 'experiences';
     protected static $unguarded = true;
 
     protected $casts = ['years' => 'int'];

tests/Models/Group.php

@@ -15,7 +15,7 @@ class Group extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'groups';
+    protected $table = 'groups';
     protected static $unguarded = true;
 
     public function users(): BelongsToMany

tests/Models/Guarded.php

@@ -14,6 +14,6 @@ class Guarded extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'guarded';
+    protected $table = 'guarded';
     protected $guarded = ['foobar', 'level1->level2'];
 }

tests/Models/Item.php

@@ -18,7 +18,7 @@ class Item extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'items';
+    protected $table = 'items';
     protected static $unguarded = true;
 
     public function user(): BelongsTo

tests/Models/Label.php

@@ -20,7 +20,7 @@ class Label extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'labels';
+    protected $table = 'labels';
     protected static $unguarded = true;
 
     protected $fillable = [

tests/Models/Location.php

@@ -14,6 +14,6 @@ class Location extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'locations';
+    protected $table = 'locations';
     protected static $unguarded = true;
 }

tests/Models/Photo.php

@@ -15,7 +15,7 @@ class Photo extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'photos';
+    protected $table = 'photos';
     protected static $unguarded = true;
 
     public function hasImage(): MorphTo

tests/Models/Role.php

@@ -15,7 +15,7 @@ class Role extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'roles';
+    protected $table = 'roles';
     protected static $unguarded = true;
 
     public function user(): BelongsTo

tests/Models/SchemaVersion.php

@@ -14,7 +14,7 @@ class SchemaVersion extends Eloquent
     public const SCHEMA_VERSION = 2;
 
     protected $connection       = 'mongodb';
-    protected $collection       = 'documentVersion';
+    protected $table            = 'documentVersion';
     protected static $unguarded = true;
 
     public function migrateSchema(int $fromVersion): void

tests/Models/Scoped.php

@@ -15,7 +15,7 @@ class Scoped extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'scoped';
+    protected $table = 'scoped';
     protected $fillable = ['name', 'favorite'];
 
     protected static function boot()

tests/Models/Skill.php

@@ -15,7 +15,7 @@ class Skill extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'skills';
+    protected $table = 'skills';
     protected static $unguarded = true;
 
     public function sqlUsers(): BelongsToMany

tests/Models/Soft.php

@@ -21,7 +21,7 @@ class Soft extends Model
     protected $primaryKey = '_id';
     protected $keyType = 'string';
     protected $connection = 'mongodb';
-    protected string $collection = 'soft';
+    protected $table = 'soft';
     protected static $unguarded = true;
     protected $casts = ['deleted_at' => 'datetime'];