Merge pull request #183 from magento-commerce/develop

Version 23

Magento2/Helpers/Commenting/PHPDocFormattingValidator.php

@@ -121,15 +121,11 @@ public function hasDeprecatedWellFormatted($commentStartPtr, $tokens)
         if ($deprecatedPtr === -1) {
             return true;
         }
-
-        $seeTagRequired = false;
-        if ($tokens[$deprecatedPtr + 2]['code'] !== T_DOC_COMMENT_STRING) {
-            $seeTagRequired = true;
-        }
         $seePtr = $this->getTagPosition('@see', $commentStartPtr, $tokens);
         if ($seePtr === -1) {
-            return !$seeTagRequired;
+            return false;
         }
+
         return $tokens[$seePtr + 2]['code'] === T_DOC_COMMENT_STRING;
     }
 

Magento2/Sniffs/Annotation/MethodAnnotationStructureSniff.php

@@ -7,6 +7,7 @@
 
 namespace Magento2\Sniffs\Annotation;
 
+use Magento2\Helpers\Commenting\PHPDocFormattingValidator;
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Sniffs\Sniff;
 
@@ -20,12 +21,18 @@ class MethodAnnotationStructureSniff implements Sniff
      */
     private $annotationFormatValidator;
 
+    /**
+     * @var PHPDocFormattingValidator
+     */
+    private $PHPDocFormattingValidator;
+
     /**
      * AnnotationStructureSniff constructor.
      */
     public function __construct()
     {
         $this->annotationFormatValidator = new AnnotationFormatValidator();
+        $this->PHPDocFormattingValidator = new PHPDocFormattingValidator();
     }
 
     /**
@@ -45,6 +52,16 @@ public function process(File $phpcsFile, $stackPtr)
     {
         $tokens = $phpcsFile->getTokens();
         $commentStartPtr = $phpcsFile->findPrevious(T_DOC_COMMENT_OPEN_TAG, ($stackPtr), 0);
+
+        if ($this->PHPDocFormattingValidator->hasDeprecatedWellFormatted($commentStartPtr, $tokens) !== true) {
+            $phpcsFile->addWarning(
+                'Motivation behind the added @deprecated tag MUST be explained. '
+                . '@see tag MUST be used with reference to new implementation when code is deprecated '
+                . 'and there is a new alternative.',
+                $stackPtr,
+                'InvalidDeprecatedTagUsage'
+            );
+        }
         $commentEndPtr = $phpcsFile->findPrevious(T_DOC_COMMENT_CLOSE_TAG, ($stackPtr), 0);
         if (!$commentStartPtr) {
             $phpcsFile->addError('Comment block is missing', $stackPtr, 'MethodArguments');

Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php

@@ -67,6 +67,15 @@ public function processMemberVar(File $phpcsFile, $stackPtr)
         }
 
         $commentStart = $tokens[$commentEnd]['comment_opener'];
+        if ($this->PHPDocFormattingValidator->hasDeprecatedWellFormatted($commentStart, $tokens) !== true) {
+            $phpcsFile->addWarning(
+                'Motivation behind the added @deprecated tag MUST be explained. '
+                . '@see tag MUST be used with reference to new implementation when code is deprecated '
+                . 'and there is a new alternative.',
+                $stackPtr,
+                'InvalidDeprecatedTagUsage'
+            );
+        }
         $varAnnotationPosition = null;
         foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
             if ($tokens[$tag]['content'] === '@var') {

Magento2/Sniffs/Functions/DiscouragedFunctionSniff.php

@@ -40,11 +40,11 @@ class DiscouragedFunctionSniff extends ForbiddenFunctionsSniff
         '^chdir$' => null,
         '^chgrp$' => null,
         '^chmod$' => 'Magento\Framework\Filesystem\DriverInterface::changePermissions() 
-        or Magento\Framework\Filesystem\DriverInterface::changePermissionsRecursively()',
+        or Magento\Framework\Filesystem\DriverInterface::changePermissionsRecursively',
         '^chown$' => null,
         '^chroot$' => null,
         '^com_load_typelib$' => null,
-        '^copy$' => 'Magento\Framework\Filesystem\DriverInterface::copy()',
+        '^copy$' => 'Magento\Framework\Filesystem\DriverInterface::copy',
         '^curl_.*$' => null,
         '^cyrus_connect$' => null,
         '^dba_.*$' => null,
@@ -54,21 +54,21 @@ class DiscouragedFunctionSniff extends ForbiddenFunctionsSniff
         '^dcngettext$' => null,
         '^dgettext$' => null,
         '^dio_.*$' => null,
-        '^dirname$' => 'Magento\Framework\Filesystem\DriverInterface::getParentDirectory()',
+        '^dirname$' => 'Magento\Framework\Filesystem\DriverInterface::getParentDirectory',
         '^dngettext$' => null,
         '^domxml_.*$' => null,
         '^fbsql_.*$' => null,
         '^fbsql$' => null,
         '^fdf_add_doc_javascript$' => null,
         '^fdf_open$' => null,
-        '^fopen$' => 'Magento\Framework\Filesystem\DriverInterface::fileOpen()',
-        '^fclose$' => 'Magento\Framework\Filesystem\DriverInterface::fileClose()',
-        '^fsockopen$' => 'Magento\Framework\Filesystem\Driver\Http::open()',
+        '^fopen$' => 'Magento\Framework\Filesystem\DriverInterface::fileOpen',
+        '^fclose$' => 'Magento\Framework\Filesystem\DriverInterface::fileClose',
+        '^fsockopen$' => 'Magento\Framework\Filesystem\Driver\Http::open',
         '^ftp_.*$' => null,
-        '^fwrite$' => 'Magento\Framework\Filesystem\DriverInterface::fileWrite()',
-        '^fputs$' => 'Magento\Framework\Filesystem\DriverInterface::fileWrite()',
-        '^gettext$' => 'Magento\Framework\Translate\AdapterInterface::translate()',
-        '^_$' => 'Magento\Framework\Translate\AdapterInterface::translate()',
+        '^fwrite$' => 'Magento\Framework\Filesystem\DriverInterface::fileWrite',
+        '^fputs$' => 'Magento\Framework\Filesystem\DriverInterface::fileWrite',
+        '^gettext$' => 'Magento\Framework\Translate\AdapterInterface::translate',
+        '^_$' => 'Magento\Framework\Translate\AdapterInterface::translate',
         '^gz.*$' => null,
         '^header$' => null,
         '^highlight_file$' => null,
@@ -84,7 +84,7 @@ class DiscouragedFunctionSniff extends ForbiddenFunctionsSniff
         '^link$' => null,
         '^mail$' => null,
         '^mb_send_mail$' => null,
-        '^mkdir$' => 'Magento\Framework\Filesystem\DriverInterface::createDirectory()',
+        '^mkdir$' => 'Magento\Framework\Filesystem\DriverInterface::createDirectory',
         '^move_uploaded_file$' => null,
         '^msession_.*$' => null,
         '^msg_send$' => null,
@@ -102,7 +102,7 @@ class DiscouragedFunctionSniff extends ForbiddenFunctionsSniff
         '^parse_str$' => null,
         '^parse_url$' => null,
         '^parsekit_compile_string$' => null,
-        '^pathinfo$' => 'Magento\Framework\Filesystem\Io\File::getPathInfo()',
+        '^pathinfo$' => 'Magento\Framework\Filesystem\Io\File::getPathInfo',
         '^pcntl_.*$' => null,
         '^posix_.*$' => null,
         '^pfpro_.*$' => null,
@@ -112,30 +112,30 @@ class DiscouragedFunctionSniff extends ForbiddenFunctionsSniff
         '^print_r$' => null,
         '^printf$' => null,
         '^putenv$' => null,
-        '^readfile$' => 'Magento\Framework\Filesystem\DriverInterface::fileRead()',
+        '^readfile$' => 'Magento\Framework\Filesystem\DriverInterface::fileRead',
         '^readgzfile$' => null,
-        '^readline$' => 'Magento\Framework\Filesystem\DriverInterface::fileReadLine()',
+        '^readline$' => 'Magento\Framework\Filesystem\DriverInterface::fileReadLine',
         '^readlink$' => null,
         '^register_shutdown_function$' => null,
         '^register_tick_function$' => null,
-        '^rename$' => 'Magento\Framework\Filesystem\DriverInterface::rename()',
-        '^rmdir$' => 'Magento\Framework\Filesystem\DriverInterface::deleteDirectory()',
+        '^rename$' => 'Magento\Framework\Filesystem\DriverInterface::rename',
+        '^rmdir$' => 'Magento\Framework\Filesystem\DriverInterface::deleteDirectory',
         '^scandir$' => null,
         '^session_.*$' => null,
         '^set_include_path$' => null,
         '^ini_set$' => null,
         '^ini_alter$' => null,
         '^set_time_limit$' => null,
         '^setcookie$' => null,
-        '^setlocale$' => 'Magento\Framework\Translate\AdapterInterface::setlocale()',
+        '^setlocale$' => 'Magento\Framework\Translate\AdapterInterface::setLocale',
         '^setrawcookie$' => null,
         '^sleep$' => null,
         '^socket_.*$' => null,
         '^stream_.*$' => null,
         '^sybase_.*$' => null,
-        '^symlink$' => 'Magento\Framework\Filesystem\DriverInterface::symlink()',
+        '^symlink$' => 'Magento\Framework\Filesystem\DriverInterface::symlink',
         '^syslog$' => null,
-        '^touch$' => 'Magento\Framework\Filesystem\DriverInterface::touch()',
+        '^touch$' => 'Magento\Framework\Filesystem\DriverInterface::touch',
         '^trigger_error$' => null,
         '^unlink$' => null,
         '^vprintf$' => null,
@@ -158,7 +158,7 @@ class DiscouragedFunctionSniff extends ForbiddenFunctionsSniff
         '^fdf_.*$' => null,
         '^fget.*$' => null,
         '^fread$' => null,
-        '^fflush$' => 'Magento\Framework\Filesystem\DriverInterface::fileFlush()',
+        '^fflush$' => 'Magento\Framework\Filesystem\DriverInterface::fileFlush',
         '^get_browser$' => null,
         '^get_headers$' => null,
         '^get_meta_tags$' => null,
@@ -204,23 +204,23 @@ class DiscouragedFunctionSniff extends ForbiddenFunctionsSniff
         '^gettype$' => null,
         '^var_dump$' => null,
         '^tempnam$' => null,
-        '^realpath$' => 'Magento\Framework\Filesystem\DriverInterface::getRealPath()',
+        '^realpath$' => 'Magento\Framework\Filesystem\DriverInterface::getRealPath',
         '^linkinfo$' => null,
-        '^lstat$' => 'Magento\Framework\Filesystem\DriverInterface::stat()',
+        '^lstat$' => 'Magento\Framework\Filesystem\DriverInterface::stat',
         '^stat$' => null,
         '^lchgrp$' => null,
         '^lchown$' => null,
-        '^is_dir$' => 'Magento\Framework\Filesystem\DriverInterface::isDirectory()',
+        '^is_dir$' => 'Magento\Framework\Filesystem\DriverInterface::isDirectory',
         '^is_executable$' => null,
-        '^is_file$' => 'Magento\Framework\Filesystem\DriverInterface::isFile()',
+        '^is_file$' => 'Magento\Framework\Filesystem\DriverInterface::isFile',
         '^is_link$' => null,
-        '^is_readable$' => 'Magento\Framework\Filesystem\DriverInterface::isReadable()',
-        '^is_writable$' => 'Magento\Framework\Filesystem\DriverInterface::isWritable()',
-        '^is_writeable$' => 'Magento\Framework\Filesystem\DriverInterface::isWritable()',
+        '^is_readable$' => 'Magento\Framework\Filesystem\DriverInterface::isReadable',
+        '^is_writable$' => 'Magento\Framework\Filesystem\DriverInterface::isWritable',
+        '^is_writeable$' => 'Magento\Framework\Filesystem\DriverInterface::isWritable',
         '^is_uploaded_file$' => null,
-        '^glob$' => 'Magento\Framework\Filesystem\Glob::glob()',
+        '^glob$' => 'Magento\Framework\Filesystem\Glob::glob',
         '^ssh2_.*$' => null,
-        '^delete$' => 'Magento\Framework\Filesystem\DriverInterface::deleteFile()',
+        '^delete$' => 'Magento\Framework\Filesystem\DriverInterface::deleteFile',
         '^file.*$' => null,
         '^chop$' => 'rtrim()',
         '^sizeof$' => 'count()',
@@ -229,15 +229,15 @@ class DiscouragedFunctionSniff extends ForbiddenFunctionsSniff
         '^strval$' => '(string) construction',
         '^htmlspecialchars$' => '\Magento\Framework\Escaper->escapeHtml',
         '^getimagesize$' => 'getimagesizefromstring',
-        '^file_exists$' => 'Magento\Framework\Filesystem\DriverInterface::isExists()',
-        '^file_get_contents$' => 'Magento\Framework\Filesystem\DriverInterface::fileGetContents()',
-        '^file_put_contents$' => 'Magento\Framework\Filesystem\DriverInterface::filePutContents()',
-        '^fgetcsv$' => 'Magento\Framework\Filesystem\DriverInterface::fileGetCsv()',
-        '^fputcsv$' => 'Magento\Framework\Filesystem\DriverInterface::filePutCsv()',
-        '^ftell$' => 'Magento\Framework\Filesystem\DriverInterface::fileTell()',
-        '^fseek$' => 'Magento\Framework\Filesystem\DriverInterface::fileSeek()',
-        '^feof$' => 'Magento\Framework\Filesystem\DriverInterface::endOfFile()',
-        '^flock$' => 'Magento\Framework\Filesystem\DriverInterface::fileLock()',
+        '^file_exists$' => 'Magento\Framework\Filesystem\DriverInterface::isExists',
+        '^file_get_contents$' => 'Magento\Framework\Filesystem\DriverInterface::fileGetContents',
+        '^file_put_contents$' => 'Magento\Framework\Filesystem\DriverInterface::filePutContents',
+        '^fgetcsv$' => 'Magento\Framework\Filesystem\DriverInterface::fileGetCsv',
+        '^fputcsv$' => 'Magento\Framework\Filesystem\DriverInterface::filePutCsv',
+        '^ftell$' => 'Magento\Framework\Filesystem\DriverInterface::fileTell',
+        '^fseek$' => 'Magento\Framework\Filesystem\DriverInterface::fileSeek',
+        '^feof$' => 'Magento\Framework\Filesystem\DriverInterface::endOfFile',
+        '^flock$' => 'Magento\Framework\Filesystem\DriverInterface::fileLock',
         '^date_sunrise$' => 'date_sun_info',
         '^date_sunset$' => 'date_sun_info',
         '^strptime$' => 'date_parse_from_format',

Magento2/Sniffs/NamingConvention/ReservedWordsSniff.php

@@ -34,6 +34,7 @@ class ReservedWordsSniff implements Sniff
         'object' => '7',
         'mixed' => '7',
         'numeric' => '7',
+        'match' => '8'
     ];
 
     private const CLASS_ERROR_CODE = 'ForbiddenAsClassName';

Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc

@@ -306,4 +306,67 @@ class MethodAnnotationFixture
     {
         return $start === $length;
     }
+
+    /**
+     * This is a well-formed deprecated function
+     *
+     * @deprecated can be used in this context
+     * @see is ok here
+     */
+    public function deprecated(): bool
+    {
+        return true;
+    }
+
+    /**
+     * This deprecated function is incorrect since it only contains the @deprecated tag
+     *
+     * @deprecated
+     */
+    public function incorrectlyDeprecated()
+    {
+        return false;
+    }
+
+    /**
+     * This deprecated function is incorrect since it only contains the @deprecated tag
+     *
+     * @deprecated Should not be used
+     */
+    public function incorrectAsWell()
+    {
+        return false;
+    }
+
+    /**
+     * This deprecated function is incorrect since the @see tag does not have extra info
+     *
+     * @deprecated
+     * @see
+     */
+    public function anotherOne()
+    {
+        return false;
+    }
+
+    /**
+     * This deprecated function is incorrect since the @see tag does not have extra info
+     *
+     * @deprecated Should not be used
+     * @see
+     */
+    public function yetAnotherOne()
+    {
+        return false;
+    }
+
+    /**
+     * This function is correct since the @see tag can be used without the @deprecated tag
+     *
+     * @see Magento\Framework\NewHandler
+     */
+    public function correctUseOfSee()
+    {
+        return true;
+    }
 }

Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.php

@@ -46,6 +46,11 @@ public function getErrorList()
      */
     public function getWarningList()
     {
-        return [];
+        return [
+            326 => 1,
+            336 => 1,
+            347 => 1,
+            358 => 1
+        ];
     }
 }

Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.php

@@ -33,8 +33,9 @@ public function getWarningList($testFile = '')
             65 => 1,
             66 => 1,
             101 => 1,
+            109 => 1,
             118 => 1,
-            127 => 1,
+            127 => 1
         ];
     }
 }