Deprecate Stage::search() because the $search stage must be the first of the pipeline (#2823)

Author: GromNaN

lib/Doctrine/ODM/MongoDB/Aggregation/Stage.php

@@ -368,10 +368,14 @@ public function sample(int $size): Stage\Sample
      * The $search stage performs a full-text search on the specified field or
      * fields which must be covered by an Atlas Search index.
      *
+     * @deprecated Since doctrine/mongodb-odm 2.13. This $search stage must be the first of the pipeline, use Builder::search() instead.
+     *
      * @see https://www.mongodb.com/docs/atlas/atlas-search/query-syntax/#mongodb-pipeline-pipe.-search
      */
     public function search(): Stage\Search
     {
+        trigger_deprecation('doctrine/mongodb-odm', '2.13', 'Using "%s" is deprecated because the $search stage must be the first of the pipeline, use "%s::search()" instead.', __METHOD__, Builder::class);
+
         return $this->builder->search();
     }