PHPLIB-330: Implement checks for coding standard

.gitignore

@@ -7,3 +7,7 @@ vendor/
 phpunit.phar
 phpunit.xml
 .phpunit.result.cache
+
+# phpcs
+.phpcs-cache
+phpcs.xml

.phpcs/autoload.php

@@ -0,0 +1,15 @@
+<?php
+
+// Since doctrine/coding-standard requires PHP 7, we can't add it as a dependency
+// yet. This autoload file adds more information to the phpcs error message,
+// telling the user how they can fix the error presented to them by phpcs.
+if (! file_exists(__DIR__ . '/../vendor/doctrine/coding-standard')) {
+    echo <<<ERRORMESSAGE
+==============================================================================
+ERROR: Doctrine coding standard is not installed. To rectify this, please run:
+composer require --dev doctrine/coding-standard=^6.0
+==============================================================================
+
+
+ERRORMESSAGE;
+}

.travis.yml

@@ -25,6 +25,20 @@ jobs:
 
     - stage: Smoke Testing
       php: "7.3"
+      env:
+        - CHECKS=phpunit
+    - stage: Smoke Testing
+      php: "7.1"
+      before_install: []
+      before_script:
+        - pecl install -f mongodb-${DRIVER_VERSION}
+        - composer require --no-update doctrine/coding-standard=^6.0
+        - composer install --no-interaction --no-progress --no-suggest ${COMPOSER_OPTIONS}
+      script: vendor/bin/phpcs
+      after_script: []
+      after_failure: []
+      env:
+        - CHECKS=phpcs
 
     # Test remaining supported PHP versions
     - stage: Test

CONTRIBUTING.md

@@ -35,6 +35,31 @@ test suite. In addition to various PHPUnit options, it defines required
 this configuration by creating your own `phpunit.xml` file based on the
 `phpunit.xml.dist` file we provide.
 
+## Checking coding standards
+
+The library's code is checked using [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer),
+which is installed as a development dependency by Composer. Due to the PHP
+requirement, the base version of the coding standard is not installed and needs
+to be added manually if you plan to contributing code:
+
+```
+$ composer require --dev doctrine/coding-standard=^6.0
+```
+
+Once the coding standard has been installed, you can check the code for style
+errors:
+
+
+```
+$ vendor/bin/phpcs
+```
+
+To automatically fix all fixable errors, use the `phpcbf` binary:
+
+```
+$ vendor/bin/phpcbf
+```
+
 ## Documentation
 
 Documentation for the library lives in the `docs/` directory and is built with

composer.json

@@ -18,6 +18,7 @@
     "require-dev": {
         "phpunit/phpunit": "^5.7.27 || ^6.4 || ^8.3",
         "sebastian/comparator": "^1.0 || ^2.0 || ^3.0",
+        "squizlabs/php_codesniffer": "^3.4",
         "symfony/phpunit-bridge": "^4.4@dev"
     },
     "autoload": {

phpcs.xml.dist

@@ -0,0 +1,101 @@
+<?xml version="1.0"?>
+<ruleset>
+    <arg name="basepath" value="."/>
+    <arg name="extensions" value="php"/>
+    <arg name="parallel" value="80"/>
+    <arg name="cache" value=".phpcs-cache"/>
+    <arg name="colors" />
+
+    <!-- Ignore warnings, show progress of the run, and show sniff names -->
+    <arg value="nps"/>
+
+    <autoload>.phpcs/autoload.php</autoload>
+
+    <file>.phpcs</file>
+    <file>src</file>
+    <file>tests</file>
+
+    <rule ref="Doctrine">
+        <!-- Exclude sniffs that require newer PHP versions -->
+        <!-- Available with PHP 7.0 -->
+        <exclude name="SlevomatCodingStandard.TypeHints.DeclareStrictTypes" />
+        <!-- In addition to requiring PHP 7.0, this sniff will cause a significant amount of BC breaks. Proceed with caution! -->
+        <exclude name="SlevomatCodingStandard.TypeHints.TypeHintDeclaration" />
+        <exclude name="SlevomatCodingStandard.Exceptions.ReferenceThrowableOnly" />
+        <exclude name="SlevomatCodingStandard.ControlStructures.RequireNullCoalesceOperator" />
+
+        <!-- Available with PHP 7.1 -->
+        <exclude name="SlevomatCodingStandard.Classes.ClassConstantVisibility" />
+        <exclude name="SlevomatCodingStandard.PHP.ShortList.LongListUsed" />
+        <exclude name="SlevomatCodingStandard.TypeHints.NullableTypeForNullDefaultValue" />
+
+        <!-- No statement alignment so far -->
+        <exclude name="Generic.Formatting.MultipleStatementAlignment" />
+
+        <!-- Class naming sniffs are excluded to preserve BC -->
+        <exclude name="SlevomatCodingStandard.Classes.SuperfluousAbstractClassNaming" />
+        <exclude name="SlevomatCodingStandard.Classes.SuperfluousExceptionNaming" />
+        <exclude name="SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming" />
+        <exclude name="SlevomatCodingStandard.Classes.SuperfluousTraitNaming" />
+
+        <!-- Forbid useless annotations - Git and LICENCE file provide more accurate information -->
+        <!-- Disable forbidden annotation sniff as excluding @api from the list doesn't work -->
+        <exclude name="SlevomatCodingStandard.Commenting.ForbiddenAnnotations.AnnotationForbidden" />
+
+        <!-- Keep long typehints (for now) -->
+        <exclude name="SlevomatCodingStandard.PHP.TypeCast.InvalidCastUsed" />
+        <exclude name="SlevomatCodingStandard.TypeHints.LongTypeHints" />
+
+        <!-- Don't require a full stop after @throws tags -->
+        <exclude name="Squiz.Commenting.FunctionComment.ThrowsNoFullStop" />
+
+        <!-- Disable some sniffs as they can cause functional changes. These will be enabled later -->
+        <exclude name="Generic.PHP.ForbiddenFunctions.FoundWithAlternative" />
+        <exclude name="SlevomatCodingStandard.Classes.UnusedPrivateElements" />
+        <exclude name="SlevomatCodingStandard.ControlStructures.DisallowYodaComparison" />
+        <exclude name="SlevomatCodingStandard.ControlStructures.EarlyExit" />
+        <exclude name="SlevomatCodingStandard.ControlStructures.UselessIfConditionWithReturn" />
+        <exclude name="SlevomatCodingStandard.Functions.StaticClosure" />
+        <exclude name="SlevomatCodingStandard.Functions.UnusedInheritedVariablePassedToClosure" />
+        <exclude name="SlevomatCodingStandard.Operators.DisallowEqualOperators" />
+
+        <!-- These sniffs cause a large diff, so enable them in separate steps -->
+        <exclude name="SlevomatCodingStandard.Commenting.DocCommentSpacing.IncorrectAnnotationsGroup" />
+        <exclude name="SlevomatCodingStandard.Commenting.RequireOneLinePropertyDocComment" />
+        <exclude name="Squiz.Strings.DoubleQuoteUsage" />
+
+        <!-- Sniff currently breaks, see https://github.com/slevomat/coding-standard/issues/727 -->
+        <exclude name="SlevomatCodingStandard.Namespaces.NamespaceSpacing" />
+    </rule>
+
+    <!-- Change use statement sorting to be compatible with PSR-12 -->
+    <rule ref="SlevomatCodingStandard.Namespaces.AlphabeticallySortedUses">
+        <properties>
+            <property name="psr12Compatible" value="true"/>
+        </properties>
+    </rule>
+
+    <!-- Forbid fully qualified names even for colliding names -->
+    <rule ref="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly">
+        <properties>
+            <property name="allowFallbackGlobalConstants" value="false"/>
+            <property name="allowFallbackGlobalFunctions" value="false"/>
+            <property name="allowFullyQualifiedGlobalClasses" value="false"/>
+            <property name="allowFullyQualifiedGlobalConstants" value="false"/>
+            <property name="allowFullyQualifiedGlobalFunctions" value="false"/>
+            <property phpcs-only="true" name="allowFullyQualifiedNameForCollidingClasses" value="false"/>
+            <property phpcs-only="true" name="allowFullyQualifiedNameForCollidingConstants" value="false"/>
+            <property phpcs-only="true" name="allowFullyQualifiedNameForCollidingFunctions" value="false"/>
+            <property name="searchAnnotations" value="true"/>
+        </properties>
+    </rule>
+
+    <rule ref="PSR1.Methods.CamelCapsMethodName.NotCamelCaps">
+        <exclude-pattern>/src/GridFS/StreamWrapper</exclude-pattern>
+        <exclude-pattern>/tests/DocumentationExamplesTest.php</exclude-pattern>
+    </rule>
+
+    <rule ref="PSR1.Classes.ClassDeclaration.MultipleClasses">
+        <exclude-pattern>/tests/Compat/PolyfillAssertTrait.php</exclude-pattern>
+    </rule>
+</ruleset>

src/BulkWriteResult.php

@@ -30,8 +30,6 @@ class BulkWriteResult
     private $isAcknowledged;
 
     /**
-     * Constructor.
-     *
      * @param WriteResult $writeResult
      * @param mixed[]     $insertedIds
      */

src/ChangeStream.php

@@ -17,13 +17,15 @@
 
 namespace MongoDB;
 
+use Iterator;
 use MongoDB\Driver\CursorId;
 use MongoDB\Driver\Exception\ConnectionException;
 use MongoDB\Driver\Exception\RuntimeException;
 use MongoDB\Driver\Exception\ServerException;
 use MongoDB\Exception\ResumeTokenException;
 use MongoDB\Model\ChangeStreamIterator;
-use Iterator;
+use function call_user_func;
+use function in_array;
 
 /**
  * Iterator for a change stream.
@@ -57,8 +59,6 @@ class ChangeStream implements Iterator
     private $hasAdvanced = false;
 
     /**
-     * Constructor.
-     *
      * @internal
      * @param ChangeStreamIterator $iterator
      * @param callable             $resumeCallable
@@ -109,6 +109,7 @@ public function key()
         if ($this->valid()) {
             return $this->key;
         }
+
         return null;
     }
 
@@ -167,7 +168,7 @@ private function isResumableError(RuntimeException $exception)
             return true;
         }
 
-        if ( ! $exception instanceof ServerException) {
+        if (! $exception instanceof ServerException) {
             return false;
         }
 
@@ -202,7 +203,7 @@ private function onIteration($incrementKey)
 
         /* Return early if there is not a current result. Avoid any attempt to
          * increment the iterator's key. */
-        if (!$this->valid()) {
+        if (! $this->valid()) {
             return;
         }
 
@@ -236,6 +237,7 @@ private function resumeOrThrow(RuntimeException $exception)
     {
         if ($this->isResumableError($exception)) {
             $this->resume();
+
             return;
         }
 

src/Client.php

@@ -17,27 +17,30 @@
 
 namespace MongoDB;
 
+use MongoDB\Driver\Exception\InvalidArgumentException as DriverInvalidArgumentException;
+use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
 use MongoDB\Driver\Manager;
 use MongoDB\Driver\ReadConcern;
 use MongoDB\Driver\ReadPreference;
 use MongoDB\Driver\Session;
 use MongoDB\Driver\WriteConcern;
-use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
-use MongoDB\Driver\Exception\InvalidArgumentException as DriverInvalidArgumentException;
 use MongoDB\Exception\InvalidArgumentException;
 use MongoDB\Exception\UnexpectedValueException;
 use MongoDB\Exception\UnsupportedException;
+use MongoDB\Model\BSONArray;
+use MongoDB\Model\BSONDocument;
 use MongoDB\Model\DatabaseInfoIterator;
 use MongoDB\Operation\DropDatabase;
 use MongoDB\Operation\ListDatabases;
 use MongoDB\Operation\Watch;
+use function is_array;
 
 class Client
 {
     private static $defaultTypeMap = [
-        'array' => \MongoDB\Model\BSONArray::class,
-        'document' => \MongoDB\Model\BSONDocument::class,
-        'root' => \MongoDB\Model\BSONDocument::class,
+        'array' => BSONArray::class,
+        'document' => BSONDocument::class,
+        'root' => BSONDocument::class,
     ];
     private static $wireVersionForReadConcern = 4;
     private static $wireVersionForWritableCommandWriteConcern = 5;
@@ -147,13 +150,13 @@ public function __toString()
      */
     public function dropDatabase($databaseName, array $options = [])
     {
-        if ( ! isset($options['typeMap'])) {
+        if (! isset($options['typeMap'])) {
             $options['typeMap'] = $this->typeMap;
         }
 
         $server = $this->manager->selectServer(new ReadPreference(ReadPreference::RP_PRIMARY));
 
-        if ( ! isset($options['writeConcern']) && \MongoDB\server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern)) {
+        if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern)) {
             $options['writeConcern'] = $this->writeConcern;
         }
 
@@ -269,7 +272,7 @@ public function selectDatabase($databaseName, array $options = [])
      * Start a new client session.
      *
      * @see http://php.net/manual/en/mongodb-driver-manager.startsession.php
-     * @param array  $options      Session options
+     * @param array $options Session options
      * @return Session
      */
     public function startSession(array $options = [])
@@ -288,17 +291,17 @@ public function startSession(array $options = [])
      */
     public function watch(array $pipeline = [], array $options = [])
     {
-        if ( ! isset($options['readPreference'])) {
+        if (! isset($options['readPreference'])) {
             $options['readPreference'] = $this->readPreference;
         }
 
         $server = $this->manager->selectServer($options['readPreference']);
 
-        if ( ! isset($options['readConcern']) && \MongoDB\server_supports_feature($server, self::$wireVersionForReadConcern)) {
+        if (! isset($options['readConcern']) && server_supports_feature($server, self::$wireVersionForReadConcern)) {
             $options['readConcern'] = $this->readConcern;
         }
 
-        if ( ! isset($options['typeMap'])) {
+        if (! isset($options['typeMap'])) {
             $options['typeMap'] = $this->typeMap;
         }