PHPORM-220 Deprecate using the $collection property to customize the name (#3064)

Co-authored-by: rustagir <rea.rustagi@mongodb.com>

Author: GromNaN

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

@@ -111,7 +111,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::
@@ -127,7 +127,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