Writing clean code with PHP MD and PHP CS

Maintaining clean code is much more efficient than maintaining spaghetti code, but writing clean code is not as easy as it sounds. These days there are some tools that help you with writing clean code, such as PHPMD and PHP_CodeSniffer.

PHPMD stands for PHP Mess Detector; this tool will check your code on complexity and how variables are used and will detect some possible bugs. It goes a bit further than the syntax check in your IDE.

PHP_CodeSniffer or PHPCS checks your code on coding standards such as PSR-1 and PSR-2.

Getting ready

We will install PHPMD and PHP_CodeSniffer in our development environment. Make sure you have command-line access to your development environment.

How to do it...

1. Before installing PHPMD and PHP_CodeSniffer, we have to make sure that PHP is installed on our development machine. Especially if you are developing on a remote server, it could be that PHP is not installed.
2. Download and install PHPMD. Depending on your OS, the protocol could be different. You can find instructions at:

   http://phpmd.org/download/index.html

3. Download and install PHP_CodeSniffer. You can find the installation instructions at:

   https://github.com/squizlabs/PHP_CodeSniffer

4. Everything is installed, so we can run a test for PHPMD. For the PHPMD command, these are the required options:
   • Filename or directory
   • The format of the report
   • The ruleset
5. Let's run the following command to check the file on clean code and output text:

   phpmd app/code/Magento/Cms/Model/Observer.php text cleancode
   

6. It gives us the following output:

   /var/www/magento2/app/code/Magento/Cms/Model/Observer.php:70    Avoid using static access to class '\Magento\Cms\Helper\Page' in method 'noCookies'
   /var/www/magento2/app/code/Magento/Cms/Model/Observer.php:71    Avoid using static access to class '\Magento\Store\Model\ScopeInterface' in method 'noCookies'.
   /var/www/magento2/app/code/Magento/Cms/Model/Observer.php:77    The method noCookies uses an else expression. Else is never necessary and you can simplify the code to work without else.
   

7. There are a lot of errors, but Magento 2 defines its own rules for PHPMD. To run a test with these rules, we can run the following command:

   phpmd app/code/Magento/Cms/Model/Observer.php text dev/tests/static/testsuite/Magento/Test/Php/_files/phpmd/ruleset.xml
   

8. This command gives empty output, which means that this file is valid.
9. We will now run a test on the same file with PHP_CodeSniffer. With the next command, we will run a test on the same file we used for PHPMD.

   phpcs app/code/Magento/Cms/Model/Observer.php
   

10. This test gives us the following output:

    FILE: /var/www/magento2/app/code/Magento/Cms/Model/Observer.php
    ----------------------------------------------------------------------
    FOUND 22 ERRORS AND 2 WARNINGS AFFECTING 12 LINES
    ----------------------------------------------------------------------
      5 | WARNING | [ ] PHP version not specified
      5 | ERROR   | [ ] Missing @category tag in file comment
      5 | ERROR   | [ ] Missing @package tag in file comment
      5 | ERROR   | [ ] Missing @author tag in file comment
      5 | ERROR   | [ ] Missing @license tag in file comment
      5 | ERROR   | [ ] Missing @link tag in file comment
     10 | ERROR   | [ ] Missing @category tag in class comment
     10 | ERROR   | [ ] Missing @package tag in class comment
     10 | ERROR   | [ ] Missing @author tag in class comment
     10 | ERROR   | [ ] Missing @license tag in class comment
     10 | ERROR   | [ ] Missing @link tag in class comment
     18 | ERROR   | [ ] Protected member variable "_cmsPage" must not be
        |         |     prefixed with an underscore
     25 | ERROR   | [ ] Protected member variable "_scopeConfig" must not
        |         |     be prefixed with an underscore
     27 | ERROR   | [ ] Missing short description in doc comment
     28 | ERROR   | [ ] Missing parameter comment
     28 | ERROR   | [x] Expected 27 spaces after parameter type; 1 found
     29 | ERROR   | [ ] Missing parameter comment
     42 | ERROR   | [ ] Missing parameter comment
     42 | ERROR   | [x] Tag value indented incorrectly; expected 2 spaces
        |         |     but found 1
     43 | ERROR   | [ ] Tag cannot be grouped with parameter tags in a
        |         |     doc comment
     62 | ERROR   | [ ] Missing parameter comment
     62 | ERROR   | [x] Tag value indented incorrectly; expected 2 spaces
        |         |     but found 1
     63 | ERROR   | [ ] Tag cannot be grouped with parameter tags in a
        |         |     doc comment
     78 | WARNING | [ ] Line exceeds 85 characters; contains 94
        |         |     characters
    ----------------------------------------------------------------------
    PHPCBF CAN FIX THE 3 MARKED SNIFF VIOLATIONS AUTOMATICALLY
    ----------------------------------------------------------------------
    
    Time: 28ms; Memory: 3.75Mb
    

    Note

    If the phpmd command is not working, you have to find the path to the phpmd executable and run it from there.

11. When we specify the ruleset of Magento 2, we have the following command:

    phpcs app/code/Magento/Cms/Model/Observer.php --standard=dev/tests/static/testsuite/Magento/Test/Php/_files/phpcs/ruleset.xml
    

12. This command gives us the following output:

    FILE: /var/www/magento2/app/code/Magento/Cms/Model/Observer.php
    ----------------------------------------------------------------------
    FOUND 5 ERRORS AFFECTING 5 LINES
    ----------------------------------------------------------------------
     18 | ERROR | Missing variable doc comment
     25 | ERROR | Missing variable doc comment
     31 | ERROR | Missing function doc comment
     45 | ERROR | Missing function doc comment
     65 | ERROR | Missing function doc comment
    ----------------------------------------------------------------------
    
    Time: 35ms; Memory: 3.75Mb
    

How it works...

PHPMD and PHP_CodeSniffer are tools that checks PHP files on code style. These tools have defined their default rulesets for common usage.

Magento has created its own rulesets; they can be found in the directory dev/tests/static/testsuite/Magento/Test/Php/_files/phpcs/ruleset.xml.

When developing custom code in Magento 2, it is recommended that you configure these rulesets when working with PHPMD and PHP_CodeSniffer.

There's more...

Some IDE's have built-in support for PHPMD and PHP_CodeSniffer. These plugins will run a test when saving a file.

In NetBeans, you have the phpcsmd plugin that allows you to integrate these tools in your IDE. For more details visit the following URL:

http://plugins.netbeans.org/plugin/40282/phpmd-php-codesniffer-plugin

In PHPStorm, there is built-in support for PHPMD and PHP_CodeSniffer. If it is configured, there is a color indicator that says how clean your code is. More information can be found at https://www.jetbrains.com/phpstorm/help/using-php-mess-detector.html.

Tip

When configuring PHPMD and PHP_CodeSniffer in an IDE, these tools and PHP need to be installed on the machine on which the IDE is running.