Tighten up coding standards

In this change I have tightened the phpcs.xml, ran phpcbf and started processing the remaining feedback by hand. Especially the tightening of type checks is causing issues when running the application and tests. This will potentially resolve a fair number of bugs or unintended effects
phpDocumentor · Dec 2, 2019 · 562d605 · 562d605
1 parent de84eb8
commit 562d605
Show file tree

Hide file tree

Showing 320 changed files with 3,754 additions and 4,260 deletions.
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -18,7 +18,7 @@ services:
     command: ["./tools/behat"]
 
   phpcs:
-    image: oskarstark/phpcs-ga
+    image: phpdoc/phpcs-ga:master
     volumes: [".:/opt/phpdoc"]
     working_dir: "/opt/phpdoc"
     command: ["-d memory_limit=1024M"]

diff --git a/phpcs.xml.dist b/phpcs.xml.dist
@@ -6,10 +6,47 @@
     <file>tests/unit</file>
     <exclude-pattern>*\.(css|js)$</exclude-pattern>
     <arg value="p"/>
-     <rule ref="PSR2">
-         <include-pattern>*\.php</include-pattern>
-     </rule>
-      <rule ref="PSR1.Methods.CamelCapsMethodName.NotCamelCaps">
+    <rule ref="PSR2">
+        <include-pattern>*\.php</include-pattern>
+    </rule>
+
+    <rule ref="Doctrine">
+        <exclude name="Generic.Formatting.MultipleStatementAlignment.NotSame" />
+        <exclude name="SlevomatCodingStandard.TypeHints.UselessConstantTypeHint.UselessDocComment" />
+
+        <!-- Should be removed/fixed again once we pass the round of checks -->
+        <exclude name="SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingTraversableParameterTypeHintSpecification" />
+        <exclude name="SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingTraversablePropertyTypeHintSpecification" />
+        <exclude name="SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingTraversableReturnTypeHintSpecification" />
+    </rule>
+
+    <rule ref="Squiz.Classes.ValidClassName.NotCamelCaps">
+        <exclude-pattern>*/src/*_.php</exclude-pattern>
+    </rule>
+
+    <rule ref="SlevomatCodingStandard.Classes.SuperfluousExceptionNaming.SuperfluousSuffix">
+        <exclude-pattern>*/src/*/*Exception.php</exclude-pattern>
+    </rule>
+
+    <rule ref="SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming">
+        <exclude-pattern>*/src/*/*Interface.php</exclude-pattern>
+    </rule>
+
+    <rule ref="SlevomatCodingStandard.Classes.SuperfluousAbstractClassNaming.SuperfluousPrefix">
+        <exclude-pattern>*/src/*/Abstract*.php</exclude-pattern>
+    </rule>
+
+    <rule ref="SlevomatCodingStandard.Classes.SuperfluousAbstractClassNaming.SuperfluousSuffix">
+        <exclude-pattern>*/src/*/*Abstract.php</exclude-pattern>
+    </rule>
+
+    <rule ref="PSR1.Methods.CamelCapsMethodName.NotCamelCaps">
          <exclude-pattern>*/tests/unit/*.php</exclude-pattern>
      </rule>
+
+    <rule ref="Generic.Formatting.SpaceAfterNot">
+        <properties>
+            <property name="spacing" value="0" />
+        </properties>
+    </rule>
 </ruleset>
diff --git a/src/phpDocumentor/Application.php b/src/phpDocumentor/Application.php
@@ -1,4 +1,5 @@
 <?php
+
 declare(strict_types=1);
 
 /**
@@ -7,20 +8,19 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  *
- * @author    Mike van Riel <mike.vanriel@naenius.com>
- * @copyright 2010-2018 Mike van Riel / Naenius (http://www.naenius.com)
- * @license   http://www.opensource.org/licenses/mit-license.php MIT
- * @link      http://phpdoc.org
+ * @link http://phpdoc.org
  */
 
 namespace phpDocumentor;
 
-use phpDocumentor\Event\Dispatcher;
-use phpDocumentor\Parser\Event\PreFileEvent;
-use Psr\Log\LoggerInterface;
-use Psr\Log\LogLevel;
 use RuntimeException;
-use Symfony\Component\DependencyInjection\ContainerInterface;
+use function date_default_timezone_set;
+use function extension_loaded;
+use function file_exists;
+use function file_get_contents;
+use function ini_get;
+use function ini_set;
+use function trim;
 
 /**
  * Application class for phpDocumentor.
@@ -31,12 +31,12 @@
  */
 class Application
 {
-    public static function VERSION(): string
+    public static function VERSION() : string
     {
         return trim(file_get_contents(__DIR__ . '/../../VERSION'));
     }
 
-    public static function templateDirectory(): string
+    public static function templateDirectory() : string
     {
         $templateDir = __DIR__ . '/../../data/templates';
 
@@ -62,7 +62,7 @@ public function __construct()
      *
      * @throws RuntimeException
      */
-    protected function defineIniSettings(): void
+    protected function defineIniSettings() : void
     {
         $this->setTimezone();
         ini_set('memory_limit', '-1');
@@ -75,7 +75,7 @@ protected function defineIniSettings(): void
             }
         }
 
-        if (extension_loaded('Zend Optimizer+') && ini_get('zend_optimizerplus.save_comments') === "0") {
+        if (extension_loaded('Zend Optimizer+') && ini_get('zend_optimizerplus.save_comments') === '0') {
             throw new RuntimeException('Please enable zend_optimizerplus.save_comments in php.ini.');
         }
     }
@@ -89,10 +89,12 @@ protected function defineIniSettings(): void
      * @link http://php.net/manual/en/function.date-default-timezone-get.php for more information how PHP determines the
      *     default timezone.
      */
-    protected function setTimezone(): void
+    protected function setTimezone() : void
     {
-        if (false === ini_get('date.timezone')) {
-            date_default_timezone_set('UTC');
+        if (ini_get('date.timezone') !== false) {
+            return;
         }
+
+        date_default_timezone_set('UTC');
     }
 }
diff --git a/src/phpDocumentor/Application/PipelineFactory.php b/src/phpDocumentor/Application/PipelineFactory.php
@@ -1,4 +1,5 @@
 <?php
+
 declare(strict_types=1);
 
 /**
@@ -7,9 +8,6 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  *
- * @author    Mike van Riel <mike.vanriel@naenius.com>
- * @copyright 2010-2018 Mike van Riel / Naenius (http://www.naenius.com)
- * @license   http://www.opensource.org/licenses/mit-license.php MIT
  * @link      http://phpdoc.org
  */
 
@@ -20,7 +18,7 @@
 
 final class PipelineFactory
 {
-    public static function create(iterable $stages): PipelineInterface
+    public static function create(iterable $stages) : PipelineInterface
     {
         $builder = new PipelineBuilder();
         foreach ($stages as $stage) {

diff --git a/src/phpDocumentor/Application/Stage/Cache/GarbageCollectCache.php b/src/phpDocumentor/Application/Stage/Cache/GarbageCollectCache.php
@@ -8,22 +8,17 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  *
- * @author    Mike van Riel <mike.vanriel@naenius.com>
- * @copyright 2010-2018 Mike van Riel / Naenius (http://www.naenius.com)
- * @license   http://www.opensource.org/licenses/mit-license.php MIT
  * @link      http://phpdoc.org
  */
 
 namespace phpDocumentor\Application\Stage\Cache;
 
-use phpDocumentor\Descriptor\Cache\ProjectDescriptorMapper;
 use phpDocumentor\Application\Stage\Parser\Payload;
+use phpDocumentor\Descriptor\Cache\ProjectDescriptorMapper;
 
 final class GarbageCollectCache
 {
-    /**
-     * @var ProjectDescriptorMapper
-     */
+    /** @var ProjectDescriptorMapper */
     private $descriptorMapper;
 
     public function __construct(ProjectDescriptorMapper $descriptorMapper)

diff --git a/src/phpDocumentor/Application/Stage/Cache/LoadProjectDescriptorFromCache.php b/src/phpDocumentor/Application/Stage/Cache/LoadProjectDescriptorFromCache.php
@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace phpDocumentor\Application\Stage\Cache;
 
 use phpDocumentor\Application\Stage\Parser\Payload;
@@ -9,20 +11,16 @@
 
 final class LoadProjectDescriptorFromCache
 {
-    /**
-     * @var ProjectDescriptorMapper
-     */
+    /** @var ProjectDescriptorMapper */
     private $descriptorMapper;
 
-    /**
-     * @var LoggerInterface
-     */
+    /** @var LoggerInterface */
     private $logger;
 
     public function __construct(ProjectDescriptorMapper $descriptorMapper, LoggerInterface $logger)
     {
         $this->descriptorMapper = $descriptorMapper;
-        $this->logger = $logger;
+        $this->logger           = $logger;
     }
 
     public function __invoke(Payload $payload)
@@ -39,10 +37,10 @@ public function __invoke(Payload $payload)
     /**
      * Dispatches a logging request.
      *
-     * @param string   $priority The logging priority as declared in the LogLevel PSR-3 class.
+     * @param string   $priority   The logging priority as declared in the LogLevel PSR-3 class.
      * @param string[] $parameters
      */
-    private function log(string $message, string $priority = LogLevel::INFO, array $parameters = []): void
+    private function log(string $message, string $priority = LogLevel::INFO, array $parameters = []) : void
     {
         $this->logger->log($priority, $message, $parameters);
     }

diff --git a/src/phpDocumentor/Application/Stage/Cache/PurgeCachesWhenForced.php b/src/phpDocumentor/Application/Stage/Cache/PurgeCachesWhenForced.php
@@ -8,9 +8,6 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  *
- * @author    Mike van Riel <mike.vanriel@naenius.com>
- * @copyright 2010-2018 Mike van Riel / Naenius (http://www.naenius.com)
- * @license   http://www.opensource.org/licenses/mit-license.php MIT
  * @link      http://phpdoc.org
  */
 
@@ -31,15 +28,15 @@ public function __construct(
         AdapterInterface $descriptorsCache,
         LoggerInterface $logger
     ) {
-        $this->filesCache = $filesCache;
+        $this->filesCache       = $filesCache;
         $this->descriptorsCache = $descriptorsCache;
-        $this->logger = $logger;
+        $this->logger           = $logger;
     }
 
     public function __invoke(Payload $payload)
     {
         $this->logger->info('Checking whether to purge cache');
-        if (! $payload->getConfig()['phpdocumentor']['use-cache']) {
+        if (!$payload->getConfig()['phpdocumentor']['use-cache']) {
             $this->logger->info('Purging cache');
             $this->filesCache->clear();
             $this->descriptorsCache->clear();

diff --git a/src/phpDocumentor/Application/Stage/Cache/StoreProjectDescriptorToCache.php b/src/phpDocumentor/Application/Stage/Cache/StoreProjectDescriptorToCache.php
@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace phpDocumentor\Application\Stage\Cache;
 
 use phpDocumentor\Application\Stage\Parser\Payload;
@@ -9,19 +11,15 @@
 
 final class StoreProjectDescriptorToCache
 {
-    /**
-     * @var ProjectDescriptorMapper
-     */
+    /** @var ProjectDescriptorMapper */
     private $descriptorMapper;
-    /**
-     * @var LoggerInterface
-     */
+    /** @var LoggerInterface */
     private $logger;
 
     public function __construct(ProjectDescriptorMapper $descriptorMapper, LoggerInterface $logger)
     {
         $this->descriptorMapper = $descriptorMapper;
-        $this->logger = $logger;
+        $this->logger           = $logger;
     }
 
     public function __invoke(Payload $payload)
@@ -38,10 +36,10 @@ public function __invoke(Payload $payload)
     /**
      * Dispatches a logging request.
      *
-     * @param string   $priority The logging priority as declared in the LogLevel PSR-3 class.
+     * @param string   $priority   The logging priority as declared in the LogLevel PSR-3 class.
      * @param string[] $parameters
      */
-    private function log(string $message, string $priority = LogLevel::INFO, array $parameters = []): void
+    private function log(string $message, string $priority = LogLevel::INFO, array $parameters = []) : void
     {
         $this->logger->log($priority, $message, $parameters);
     }

diff --git a/src/phpDocumentor/Application/Stage/Configure.php b/src/phpDocumentor/Application/Stage/Configure.php
@@ -1,4 +1,5 @@
 <?php
+
 declare(strict_types=1);
 
 /**
@@ -7,43 +8,40 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  *
- * @author    Mike van Riel <mike.vanriel@naenius.com>
- * @copyright 2010-2018 Mike van Riel / Naenius (http://www.naenius.com)
- * @license   http://www.opensource.org/licenses/mit-license.php MIT
  * @link      http://phpdoc.org
  */
 
 namespace phpDocumentor\Application\Stage;
 
+use InvalidArgumentException;
 use phpDocumentor\Configuration\CommandlineOptionsMiddleware;
 use phpDocumentor\Configuration\Configuration;
 use phpDocumentor\Configuration\ConfigurationFactory;
 use phpDocumentor\Uri;
 use Psr\Log\LoggerInterface;
+use function realpath;
+use function sprintf;
 
 final class Configure
 {
     private $configFactory;
     private $configuration;
     private $logger;
 
-    /**
-     * Configure constructor.
-     */
     public function __construct(
         ConfigurationFactory $configFactory,
         Configuration $configuration,
         LoggerInterface $logger
     ) {
         $this->configFactory = $configFactory;
         $this->configuration = $configuration;
-        $this->logger = $logger;
+        $this->logger        = $logger;
     }
 
     /**
      * @return string[]
      */
-    public function __invoke(array $options): array
+    public function __invoke(array $options) : array
     {
         $this->configFactory->addMiddleware(
             new CommandlineOptionsMiddleware($options)
@@ -56,7 +54,7 @@ public function __invoke(array $options): array
             if ($path !== 'none') {
                 $uri = realpath($path);
                 if ($uri === false) {
-                    throw new \InvalidArgumentException(
+                    throw new InvalidArgumentException(
                         sprintf(
                             'The configuration file in path "%s" can not be '
                             . 'found or read',

diff --git a/src/phpDocumentor/Application/Stage/InitializeBuilderFromConfig.php b/src/phpDocumentor/Application/Stage/InitializeBuilderFromConfig.php
@@ -8,15 +8,11 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  *
- * @author    Mike van Riel <mike.vanriel@naenius.com>
- * @copyright 2010-2018 Mike van Riel / Naenius (http://www.naenius.com)
- * @license   http://www.opensource.org/licenses/mit-license.php MIT
  * @link      http://phpdoc.org
  */
 
 namespace phpDocumentor\Application\Stage;
 
-use phpDocumentor\Application\Stage\Payload;
 use phpDocumentor\Descriptor\Collection as PartialsCollection;
 
 final class InitializeBuilderFromConfig