PHPLIB-1117: Remove @api annotation (#1087)

GromNaN · web-flow · commit b4909e8a69c6 · 2023-06-01T11:54:00.000+02:00
* Setup rector
* Remove api annotation, all classes are public by default unless marked with internal
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -151,6 +151,17 @@ possible it can be added to the baseline using `set-baseline`:
 $ vendor/bin/psalm --set-baseline=psalm-baseline.xml
 ```
 
+## Automatic code refactoring
+
+The library uses [rector](https://getrector.com/) to refactor the code for new features.
+To run automatic refactoring, use the `rector` command:
+
+```
+$ vendor/bin/rector
+```
+
+New rules can be added to the `rector.php` configuration file.
+
 ## Documentation
 
 Documentation for the library lives in the `docs/` directory and is built with
diff --git a/composer.json b/composer.json
@@ -18,8 +18,9 @@
         "symfony/polyfill-php80": "^1.27"
     },
     "require-dev": {
-        "squizlabs/php_codesniffer": "^3.7",
         "doctrine/coding-standard": "^11.1",
+        "rector/rector": "^0.16.0",
+        "squizlabs/php_codesniffer": "^3.7",
         "symfony/phpunit-bridge": "^5.2",
         "vimeo/psalm": "^4.28"
     },
@@ -39,6 +40,7 @@
     "config": {
         "allow-plugins": {
             "dealerdirect/phpcodesniffer-composer-installer": true
-        }
+        },
+        "sort-packages": true
     }
 }
diff --git a/rector.php b/rector.php
@@ -0,0 +1,23 @@
+<?php
+
+use Rector\Config\RectorConfig;
+use Rector\DeadCode\Rector\ClassLike\RemoveAnnotationRector;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->paths([
+        __DIR__ . '/examples',
+        __DIR__ . '/src',
+        __DIR__ . '/tests',
+        __DIR__ . '/tools',
+    ]);
+
+    /**
+     * All classes are public API by default, unless marked with @internal.
+     */
+    $rectorConfig->ruleWithConfiguration(RemoveAnnotationRector::class, ['api']);
+
+    // define sets of rules
+    //    $rectorConfig->sets([
+    //        LevelSetList::UP_TO_PHP_72
+    //    ]);
+};
diff --git a/src/ChangeStream.php b/src/ChangeStream.php
@@ -33,11 +33,10 @@
 /**
  * Iterator for a change stream.
  *
- * @psalm-type ResumeCallable = callable(array|object|null, bool): ChangeStreamIterator
- *
- * @api
  * @see \MongoDB\Collection::watch()
  * @see https://mongodb.com/docs/manual/reference/method/db.watch/#mongodb-method-db.watch
+ *
+ * @psalm-type ResumeCallable = callable(array|object|null, bool): ChangeStreamIterator
  */
 class ChangeStream implements Iterator
 {
diff --git a/src/GridFS/Bucket.php b/src/GridFS/Bucket.php
@@ -59,8 +59,6 @@
 /**
  * Bucket provides a public API for interacting with the GridFS files and chunks
  * collections.
- *
- * @api
  */
 class Bucket
 {
diff --git a/src/MapReduceResult.php b/src/MapReduceResult.php
@@ -31,7 +31,6 @@
  * output method (e.g. inline, collection) via the IteratorAggregate interface.
  * It also provides access to command statistics.
  *
- * @api
  * @see \MongoDB\Collection::mapReduce()
  * @see https://mongodb.com/docs/manual/reference/command/mapReduce/
  */
diff --git a/src/Model/BSONArray.php b/src/Model/BSONArray.php
@@ -31,8 +31,6 @@
  *
  * The internal data will be filtered through array_values() during BSON
  * serialization to ensure that it becomes a BSON array.
- *
- * @api
  */
 class BSONArray extends ArrayObject implements JsonSerializable, Serializable, Unserializable
 {
diff --git a/src/Model/BSONDocument.php b/src/Model/BSONDocument.php
@@ -30,8 +30,6 @@
  *
  * The internal data will be cast to an object during BSON serialization to
  * ensure that it becomes a BSON document.
- *
- * @api
  */
 class BSONDocument extends ArrayObject implements JsonSerializable, Serializable, Unserializable
 {
diff --git a/src/Model/CollectionInfo.php b/src/Model/CollectionInfo.php
@@ -30,7 +30,6 @@
  * command or, for legacy servers, queries on the "system.namespaces"
  * collection. It provides methods to access options for the collection.
  *
- * @api
  * @see \MongoDB\Database::listCollections()
  * @see https://github.com/mongodb/specifications/blob/master/source/enumerate-collections.rst
  */
diff --git a/src/Model/CollectionInfoIterator.php b/src/Model/CollectionInfoIterator.php
@@ -25,7 +25,6 @@
  *
  * This iterator is used for enumerating collections in a database.
  *
- * @api
  * @see \MongoDB\Database::listCollections()
  */
 interface CollectionInfoIterator extends Iterator
diff --git a/src/Model/DatabaseInfo.php b/src/Model/DatabaseInfo.php
@@ -29,7 +29,6 @@
  * This class models the database information returned by the listDatabases
  * command. It provides methods to access common database properties.
  *
- * @api
  * @see \MongoDB\Client::listDatabases()
  * @see https://mongodb.com/docs/manual/reference/command/listDatabases/
  */
diff --git a/src/Model/DatabaseInfoIterator.php b/src/Model/DatabaseInfoIterator.php
@@ -25,7 +25,6 @@
  *
  * This iterator is used for enumerating databases on a server.
  *
- * @api
  * @see \MongoDB\Client::listDatabases()
  */
 interface DatabaseInfoIterator extends Iterator
diff --git a/src/Model/IndexInfo.php b/src/Model/IndexInfo.php
@@ -34,7 +34,6 @@
  * For information on keys and index options, see the referenced
  * db.collection.createIndex() documentation.
  *
- * @api
  * @see \MongoDB\Collection::listIndexes()
  * @see https://github.com/mongodb/specifications/blob/master/source/enumerate-indexes.rst
  * @see https://mongodb.com/docs/manual/reference/method/db.collection.createIndex/
diff --git a/src/Model/IndexInfoIterator.php b/src/Model/IndexInfoIterator.php
@@ -25,7 +25,6 @@
  *
  * This iterator is used for enumerating indexes in a collection.
  *
- * @api
  * @see \MongoDB\Collection::listIndexes()
  */
 interface IndexInfoIterator extends Iterator
diff --git a/src/Operation/Aggregate.php b/src/Operation/Aggregate.php
@@ -44,7 +44,6 @@
 /**
  * Operation for the aggregate command.
  *
- * @api
  * @see \MongoDB\Collection::aggregate()
  * @see https://mongodb.com/docs/manual/reference/command/aggregate/
  */
diff --git a/src/Operation/BulkWrite.php b/src/Operation/BulkWrite.php
@@ -40,7 +40,6 @@
 /**
  * Operation for executing multiple write operations.
  *
- * @api
  * @see \MongoDB\Collection::bulkWrite()
  */
 class BulkWrite implements Executable
diff --git a/src/Operation/Count.php b/src/Operation/Count.php
@@ -37,7 +37,6 @@
 /**
  * Operation for the count command.
  *
- * @api
  * @see \MongoDB\Collection::count()
  * @see https://mongodb.com/docs/manual/reference/command/count/
  */
diff --git a/src/Operation/CountDocuments.php b/src/Operation/CountDocuments.php
@@ -36,7 +36,6 @@
 /**
  * Operation for obtaining an exact count of documents in a collection
  *
- * @api
  * @see \MongoDB\Collection::countDocuments()
  * @see https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst#countdocuments
  */
diff --git a/src/Operation/CreateCollection.php b/src/Operation/CreateCollection.php
@@ -38,7 +38,6 @@
 /**
  * Operation for the create command.
  *
- * @api
  * @see \MongoDB\Database::createCollection()
  * @see https://mongodb.com/docs/manual/reference/command/create/
  */
diff --git a/src/Operation/CreateIndexes.php b/src/Operation/CreateIndexes.php
@@ -36,7 +36,6 @@
 /**
  * Operation for the createIndexes command.
  *
- * @api
  * @see \MongoDB\Collection::createIndex()
  * @see \MongoDB\Collection::createIndexes()
  * @see https://mongodb.com/docs/manual/reference/command/createIndexes/
diff --git a/src/Operation/DatabaseCommand.php b/src/Operation/DatabaseCommand.php
@@ -30,7 +30,6 @@
 /**
  * Operation for executing a database command.
  *
- * @api
  * @see \MongoDB\Database::command()
  */
 class DatabaseCommand implements Executable
diff --git a/src/Operation/DeleteMany.php b/src/Operation/DeleteMany.php
@@ -26,7 +26,6 @@
 /**
  * Operation for deleting multiple document with the delete command.
  *
- * @api
  * @see \MongoDB\Collection::deleteOne()
  * @see https://mongodb.com/docs/manual/reference/command/delete/
  */
diff --git a/src/Operation/DeleteOne.php b/src/Operation/DeleteOne.php
@@ -26,7 +26,6 @@
 /**
  * Operation for deleting a single document with the delete command.
  *
- * @api
  * @see \MongoDB\Collection::deleteOne()
  * @see https://mongodb.com/docs/manual/reference/command/delete/
  */
diff --git a/src/Operation/Distinct.php b/src/Operation/Distinct.php
@@ -36,7 +36,6 @@
 /**
  * Operation for the distinct command.
  *
- * @api
  * @see \MongoDB\Collection::distinct()
  * @see https://mongodb.com/docs/manual/reference/command/distinct/
  */
diff --git a/src/Operation/DropCollection.php b/src/Operation/DropCollection.php
@@ -32,7 +32,6 @@
 /**
  * Operation for the drop command.
  *
- * @api
  * @see \MongoDB\Collection::drop()
  * @see \MongoDB\Database::dropCollection()
  * @see https://mongodb.com/docs/manual/reference/command/drop/
diff --git a/src/Operation/DropDatabase.php b/src/Operation/DropDatabase.php
@@ -30,7 +30,6 @@
 /**
  * Operation for the dropDatabase command.
  *
- * @api
  * @see \MongoDB\Client::dropDatabase()
  * @see \MongoDB\Database::drop()
  * @see https://mongodb.com/docs/manual/reference/command/dropDatabase/
diff --git a/src/Operation/DropIndexes.php b/src/Operation/DropIndexes.php
@@ -32,7 +32,6 @@
 /**
  * Operation for the dropIndexes command.
  *
- * @api
  * @see \MongoDB\Collection::dropIndexes()
  * @see https://mongodb.com/docs/manual/reference/command/dropIndexes/
  */
diff --git a/src/Operation/EstimatedDocumentCount.php b/src/Operation/EstimatedDocumentCount.php
@@ -32,7 +32,6 @@
 /**
  * Operation for obtaining an estimated count of documents in a collection
  *
- * @api
  * @see \MongoDB\Collection::estimatedDocumentCount()
  * @see https://mongodb.com/docs/manual/reference/command/count/
  */
diff --git a/src/Operation/Explain.php b/src/Operation/Explain.php
@@ -33,7 +33,6 @@
 /**
  * Operation for the explain command.
  *
- * @api
  * @see \MongoDB\Collection::explain()
  * @see https://mongodb.com/docs/manual/reference/command/explain/
  */
diff --git a/src/Operation/Find.php b/src/Operation/Find.php
@@ -40,7 +40,6 @@
 /**
  * Operation for the find command.
  *
- * @api
  * @see \MongoDB\Collection::find()
  * @see https://mongodb.com/docs/manual/tutorial/query-documents/
  * @see https://mongodb.com/docs/manual/reference/operator/query-modifier/
diff --git a/src/Operation/FindOne.php b/src/Operation/FindOne.php
@@ -27,7 +27,6 @@
 /**
  * Operation for finding a single document with the find command.
  *
- * @api
  * @see \MongoDB\Collection::findOne()
  * @see https://mongodb.com/docs/manual/tutorial/query-documents/
  * @see https://mongodb.com/docs/manual/reference/operator/query-modifier/
diff --git a/src/Operation/FindOneAndDelete.php b/src/Operation/FindOneAndDelete.php
@@ -28,7 +28,6 @@
 /**
  * Operation for deleting a document with the findAndModify command.
  *
- * @api
  * @see \MongoDB\Collection::findOneAndDelete()
  * @see https://mongodb.com/docs/manual/reference/command/findAndModify/
  */
diff --git a/src/Operation/FindOneAndReplace.php b/src/Operation/FindOneAndReplace.php
@@ -31,7 +31,6 @@
 /**
  * Operation for replacing a document with the findAndModify command.
  *
- * @api
  * @see \MongoDB\Collection::findOneAndReplace()
  * @see https://mongodb.com/docs/manual/reference/command/findAndModify/
  */
diff --git a/src/Operation/FindOneAndUpdate.php b/src/Operation/FindOneAndUpdate.php
@@ -32,7 +32,6 @@
 /**
  * Operation for updating a document with the findAndModify command.
  *
- * @api
  * @see \MongoDB\Collection::findOneAndUpdate()
  * @see https://mongodb.com/docs/manual/reference/command/findAndModify/
  */
diff --git a/src/Operation/InsertMany.php b/src/Operation/InsertMany.php
@@ -34,7 +34,6 @@
 /**
  * Operation for inserting multiple documents with the insert command.
  *
- * @api
  * @see \MongoDB\Collection::insertMany()
  * @see https://mongodb.com/docs/manual/reference/command/insert/
  */
diff --git a/src/Operation/InsertOne.php b/src/Operation/InsertOne.php
@@ -33,7 +33,6 @@
 /**
  * Operation for inserting a single document with the insert command.
  *
- * @api
  * @see \MongoDB\Collection::insertOne()
  * @see https://mongodb.com/docs/manual/reference/command/insert/
  */
diff --git a/src/Operation/ListCollectionNames.php b/src/Operation/ListCollectionNames.php
@@ -27,7 +27,6 @@
 /**
  * Operation for the listCollectionNames helper.
  *
- * @api
  * @see \MongoDB\Database::listCollectionNames()
  * @see https://mongodb.com/docs/manual/reference/command/listCollections/
  */
diff --git a/src/Operation/ListCollections.php b/src/Operation/ListCollections.php
@@ -27,7 +27,6 @@
 /**
  * Operation for the listCollections command.
  *
- * @api
  * @see \MongoDB\Database::listCollections()
  * @see https://mongodb.com/docs/manual/reference/command/listCollections/
  */
diff --git a/src/Operation/ListDatabaseNames.php b/src/Operation/ListDatabaseNames.php
@@ -30,7 +30,6 @@
 /**
  * Operation for the ListDatabases command, returning only database names.
  *
- * @api
  * @see \MongoDB\Client::listDatabaseNames()
  * @see https://mongodb.com/docs/manual/reference/command/listDatabases/#mongodb-dbcommand-dbcmd.listDatabases
  */
diff --git a/src/Operation/ListDatabases.php b/src/Operation/ListDatabases.php
@@ -28,7 +28,6 @@
 /**
  * Operation for the ListDatabases command.
  *
- * @api
  * @see \MongoDB\Client::listDatabases()
  * @see https://mongodb.com/docs/manual/reference/command/listDatabases/#mongodb-dbcommand-dbcmd.listDatabases`
  */
diff --git a/src/Operation/ListIndexes.php b/src/Operation/ListIndexes.php
@@ -33,7 +33,6 @@
 /**
  * Operation for the listIndexes command.
  *
- * @api
  * @see \MongoDB\Collection::listIndexes()
  * @see https://mongodb.com/docs/manual/reference/command/listIndexes/
  */
diff --git a/src/Operation/MapReduce.php b/src/Operation/MapReduce.php
@@ -48,7 +48,6 @@
 /**
  * Operation for the mapReduce command.
  *
- * @api
  * @see \MongoDB\Collection::mapReduce()
  * @see https://mongodb.com/docs/manual/reference/command/mapReduce/
  */
diff --git a/src/Operation/ModifyCollection.php b/src/Operation/ModifyCollection.php
@@ -30,7 +30,6 @@
 /**
  * Operation for the collMod command.
  *
- * @api
  * @see \MongoDB\Database::modifyCollection()
  * @see https://mongodb.com/docs/manual/reference/command/collMod/
  */
diff --git a/src/Operation/RenameCollection.php b/src/Operation/RenameCollection.php
@@ -32,7 +32,6 @@
 /**
  * Operation for the renameCollection command.
  *
- * @api
  * @see \MongoDB\Collection::rename()
  * @see \MongoDB\Database::renameCollection()
  * @see https://mongodb.com/docs/manual/reference/command/renameCollection/
diff --git a/src/Operation/ReplaceOne.php b/src/Operation/ReplaceOne.php
diff --git a/src/Operation/UpdateMany.php b/src/Operation/UpdateMany.php
diff --git a/src/Operation/UpdateOne.php b/src/Operation/UpdateOne.php
diff --git a/src/Operation/Watch.php b/src/Operation/Watch.php

Original file line number	Diff line number	Diff line change
`@@ -33,11 +33,10 @@`
`33`	`33`	`/**`
`34`	`34`	`* Iterator for a change stream.`
`35`	`35`	`*`
`36`		`- * @psalm-type ResumeCallable = callable(array\|object\|null, bool): ChangeStreamIterator`
`37`		`- *`
`38`		`- * @api`
`39`	`36`	`* @see \MongoDB\Collection::watch()`
`40`	`37`	`* @see https://mongodb.com/docs/manual/reference/method/db.watch/#mongodb-method-db.watch`
	`38`	`+ *`
	`39`	`+ * @psalm-type ResumeCallable = callable(array\|object\|null, bool): ChangeStreamIterator`
`41`	`40`	`*/`
`42`	`41`	`class ChangeStream implements Iterator`
`43`	`42`	`{`
Original file line number	Diff line number	Diff line change
`@@ -59,8 +59,6 @@`
`59`	`59`	`/**`
`60`	`60`	`* Bucket provides a public API for interacting with the GridFS files and chunks`
`61`	`61`	`* collections.`
`62`		`- *`
`63`		`- * @api`
`64`	`62`	`*/`
`65`	`63`	`class Bucket`
`66`	`64`	`{`
Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,6 @@`
`31`	`31`	`* output method (e.g. inline, collection) via the IteratorAggregate interface.`
`32`	`32`	`* It also provides access to command statistics.`
`33`	`33`	`*`
`34`		`- * @api`
`35`	`34`	`* @see \MongoDB\Collection::mapReduce()`
`36`	`35`	`* @see https://mongodb.com/docs/manual/reference/command/mapReduce/`
`37`	`36`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -31,8 +31,6 @@`
`31`	`31`	`*`
`32`	`32`	`* The internal data will be filtered through array_values() during BSON`
`33`	`33`	`* serialization to ensure that it becomes a BSON array.`
`34`		`- *`
`35`		`- * @api`
`36`	`34`	`*/`
`37`	`35`	`class BSONArray extends ArrayObject implements JsonSerializable, Serializable, Unserializable`
`38`	`36`	`{`
Original file line number	Diff line number	Diff line change
`@@ -30,8 +30,6 @@`
`30`	`30`	`*`
`31`	`31`	`* The internal data will be cast to an object during BSON serialization to`
`32`	`32`	`* ensure that it becomes a BSON document.`
`33`		`- *`
`34`		`- * @api`
`35`	`33`	`*/`
`36`	`34`	`class BSONDocument extends ArrayObject implements JsonSerializable, Serializable, Unserializable`
`37`	`35`	`{`
Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,6 @@`
`30`	`30`	`* command or, for legacy servers, queries on the "system.namespaces"`
`31`	`31`	`* collection. It provides methods to access options for the collection.`
`32`	`32`	`*`
`33`		`- * @api`
`34`	`33`	`* @see \MongoDB\Database::listCollections()`
`35`	`34`	`* @see https://github.com/mongodb/specifications/blob/master/source/enumerate-collections.rst`
`36`	`35`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,6 @@`
`25`	`25`	`*`
`26`	`26`	`* This iterator is used for enumerating collections in a database.`
`27`	`27`	`*`
`28`		`- * @api`
`29`	`28`	`* @see \MongoDB\Database::listCollections()`
`30`	`29`	`*/`
`31`	`30`	`interface CollectionInfoIterator extends Iterator`