Automating code quality check using GrumPHP in Magento 2

TLDR; this article is a tutorial setting up GrumPHP task runner for quality checks in Magento 2. An earlier video tutorial and presentation by me is already there.
Check out: https://youtu.be/tq-DPi9wMss and the presentation https://slides.com/milindsingh/virtual-magento-meetup/

1. why automate?

   1. developers are (a little) lazy
      • running 6-7 tools manually is what I will try to skip few times ( and expect it would pass in deployment pipelines )
      • we are overburdened (most of the times)
   2. development pipelines will fail
      • suppose we miss a space at the end of the file, and phpcs fails while running the automated pipelines on pull request merge.
      • fix the change and again push just to add a simple line at the end of the file (time taking)
   3. automation can be enforced
      • grumphp can be configured to listen to git commit commands and will not allow until all quality checks passed.

2. what to automate?

   1. PHP Code Sniffer
      • https://github.com/squizlabs/PHP_CodeSniffer
      • https://github.com/magento/magento-coding-standard
      • tokenizes PHP, JavaScript and CSS files to detect violations of a defined coding standard
   2. PHP Code Beautifier
      • automatically correct coding standard violations
   3. PHP Coding Standards Fixer
      • https://github.com/FriendsOfPHP/PHP-CS-Fixer
      • automatically correct coding standard violations (more rules available, not needed to validate)
   4. PHP Mess Detector
      • https://phpmd.org/
      • auto-detects cyclomatic complex in the code
   5. PHP Stan
      • https://github.com/phpstan/phpstan
      • https://devdocs.magento.com/guides/v2.4/test/testing.html
   6. Keywords
      • print_r("test")
      • die("hi")
      • ObjectManager::getInstance()
   7. Custom
      • Create your own automation!
      • You can check out a small task created by me to validate swagger documentation before every commit. https://github.com/milindsingh/grumphp-swagger

3. 
   
   
   how to automate?
   

- ### GrumPHP

    GrumPHP has a set of common tasks built-in.

    GrumPHP will run some tests on the committed code. If the tests fail, you won't be able to commit your changes.

    This handy tool will not only improve your codebase, it will also teach your co-workers to write better code following the best practices you've determined as a team.

- ### Installation
    Install GrumPHP by running
    + `composer require --dev phpro/grumphp` (in current project only) or,
    + `composer global require --dev phpro/grumphp` (globally recommended)

• Dependencies

  + #### PHPCS: 
  
      - Install PHP CodeSniffer (skip if already installed) : 
  
          + `composer global require --dev "squizlabs/php_codesniffer=*"` (globally recommended)
          +  `composer require --dev "squizlabs/php_codesniffer=*"` (at project level, need to add `project-root/vendor/bin` to PATH for direct cli use)
  
     - Goto Magento2 root run following commands to install Magento2 coding standard :
  
         `composer require --dev magento/magento-coding-standard`
  
     - Set Magento2 Standard in PHP CodeSniffer available standards:
  
         `phpcs --config-set installed_paths ../../magento/magento-coding-standard/`
  

  • PHPCS Fixer 2

    Install PHP Coding Standards Fixer (skip if already installed) :

    • composer global require --dev friendsofphp/php-cs-fixer (globally recommended)
    • composer require --dev friendsofphp/php-cs-fixer (at project level, need to add project-root/vendor/bin to PATH for direct cli use)
      • #### PHPStan
      • composer global require --dev phpstan/phpstan (globally recommended)
      • composer require --dev phpstan/phpstan (at project level, need to add project-root/vendor/bin to PATH for direct cli use)
      • #### PHPMD
      • composer global require --dev phpmd/phpmd (globally recommended)
      • composer require --dev phpmd/phpmd (at project level, need to add project-root/vendor/bin to PATH for direct cli use)
      • #### PHPLint
      • composer global require --dev php-parallel-lint/php-parallel-lint (globally recommended)
      • composer require --dev php-parallel-lint/php-parallel-lint (at project level, need to add project-root/vendor/bin to PATH for direct cli use)
      • ### Setup

    GrumPHP can monitor each git repository push action by initializing it in the repository. GrumPHP can be configured at 2 levels:

    • Project Level Setup

      • Goto the magento-2-root and run:
        • php vendor/bin/grumphp git:init or grumphp git:init (recommended)
      • Create a grumphp.yml file in magento-2-root and copy all content as below code.
      • Though GrumPHP auto detect git commit command but you can manually test by running php vendor/bin/grumphp run or grumphp run inside in magento-2-root.

    @external:code:github

    • Module Level Setup

      • Goto the module directory i.e. magento-2-root/app/code/MyVendor/MyModule and run:

        • php vendor/bin/grumphp git:init or grumphp git:init (recommended)

      • Create a grumphp.yml file in magento-2-root/app/code/MyVendor/MyModule and copy all content as below code.

      • Add bin path magento2-root/vendor/bin to your module composer.json. Refer to composer.json.sample.
        
        

      {
          "config": {
                  "bin-dir": "../../../../vendor/bin"
              }
      }
      

      • Same as project level setup, GrumPHP auto detect git commit command but you can manually test by running php ../../../../vendor/bin/grumphp run or grumphp run inside module.

    @external:code:github

    • ### References
    • https://www.integer-net.com/magento-2-automatic-code-quality-check-with-grumphp/
    • https://github.com/phpro/grumphp/blob/master/doc/tasks.md
    • https://devdocs.magento.com/guides/v2.4/test/testing.html
    • https://github.com/milindsingh/magento2-grumphp
    • https://github.com/milindsingh/grumphp-swagger