Skip to content

Coding Standards

Magento Coding Standard

Hyvä strives to follow the Hyvä 2 coding standard, which means,

  • the PHP CodeSniffer phpcs Hyvä ruleset (based on the default Magento2 coding standard with some modifications).
  • the PHP Mess Detector phpmd rules in the magento/magento2-base package dev/tests/static/testsuite/Magento/Test/Php/_files/phpmd/ruleset.xml.

All contributions and compatibility modules should do the same.

Disabling rules

We aren't super dogmatic though, and if a given rule doesn't make sense in a specific circumstance, it is okay to disable it using the appropriate annotation.

For example, the rules say a line may not exceed 120 characters. However, if a line is only a few characters longer and can't cleanly be split into two lines, adding the annotation to disable the sniff to the file is okay.

// phpcs:disable Generic.Files.LineLength.TooLong

Coding standard related annotations are placed after the block of use statements in a PHP file, but before the variable annotations.

For example:

<?php

declare(strict_types=1;

use Hyva\Theme\Model\ViewModelRegistry;
use Magento\Catalog\Helper\Output as CatalogOutputHelper;
use Magento\Framework\Escaper;
use Magento\Framework\View\Element\Template;

// phpcs:disable Magento2.Templates.ThisInTemplate.FoundHelper
// phpcs:disable Generic.Files.LineLength.TooLong
/** @SuppressWarnings(PHPMD.TooManyPublicMethods) */

/** @var Template $block */
/** @var Escaper $escaper */
/** @var ViewModelRegistry $viewModels */

When disabling a rule, always be as specific as possible.

// instead of
// phpcs:disable Magento2.Templates.ThisInTemplate

// use the more specific rule name
// phpcs:disable Magento2.Templates.ThisInTemplate.FoundHelper

Disabling phpmd rules in *.php files is done in the class annotation.

For example:

<?php

declare(strict_types=1);

namespace Hyva\Theme\Model\Modal;

use Magento\Framework\View\Element\Block\Interface;
use Magento\Framework\View\Element\Template as TemplateBlock;
use Magento\Framework\View\LayoutInterface;

// phpcs:disable Generic.Files.LineLength.TooLong

/**
 * @SuppressWarnings(PHPMD.TooManyPublicMethods)
 * @SuppressWarnings(PHPMD.UnusedFormalParameter)
 */
class ModalBuilder implements ModalBuilderInterface, ModalInterface
{

Running PHP Code Sniffer and Mess Detector on the command line

To run the PHP Code Sniffer phpcs on the command line with the Magento coding standard, use the following command, replacing the directory with the file or directory containing your contributions:

vendor/bin/phpcs --standard=vendor/magento/magento-coding-standard/Magento2 vendor/hyva-themes/magento2-default-theme/

To run the PHP Mess Detector on the command line with the Magento coding standard, use the following command, replacing the directory with the file or directory containing your contributions:

vendor/bin/phpmd vendor/hyva-themes/magento2-default-theme/ text dev/tests/static/testsuite/Magento/Test/Php/_files/phpmd/ruleset.xml

Setting up PHPStorm inspections

The configuration required to get Magento inspections running in PHPStorm can be quite different, depending on the development environment, that is, if a local or a container based installation is used.

There also are some differences depending on the PHPStorm version. The following description is based on release 2021.2.3.

Configure the PHP interpreter

First, a local or remote PHP interpreter needs to be configured in the "PHP" tab in the settings.

This depends on your development environment, which is why the details of how to do this are out of scope for this document.

Configure the path to phpcs and phpmd

Once the PHP interpreter is configured, in the PHPStorm settings select the "PHP > Quality Tools" tab.

There, open the "PHP_CodeSniffer" accordion, select the PHP interpreter, and click the "..." button to specify the complete path to phpcs.

If you are running a remote PHP interpreter, this needs to be the path in the container (for example /var/www/html/vendor/bin/phpcs in warden).

Use the "validate" button to check if the values are correct.

You can also specify the path to the "Code Beautifier and Fixer" which is always installed in the same directory as phpcs (with warden it is /var/www/html/vendor/bin/phpcbf).

Then open the "Mess Detector" accordion and follow the same steps.

Configure the inspections

Finally, in the PHPStorm settings, open the "Editor > Inspections" tab.

There, select "PHP > Quality Tools > PHP_CodeSniffer validation" and enable it by checking the checkbox.

Ensure the file extensions is set to php,phtml,js,css.

Check the "Installed standards path" checkbox and in the field, specify the absolute path to the Magento2 coding standard vendor/magento/magento-coding-standard/Magento2.

If you are using a remote PHP interpreter, this has to be the path in the container (with warden that is /var/www/html/vendor/magento/magento-coding-standard/Magento2).

Then, in the "Coding standard" dropdown, select Magento2.

It is also helpful to check the other checkboxes.

Now select and enable "PHP > Quality Tools > PHP Mess Detector validation". Check all checkboxes and hit "+" to specify the path to the dev/tests/static/testsuite/Magento/Test/Php/_files/phpmd/ruleset.xml ruleset.

This has to be the local path, even if a remote PHP interpreter is being used. (I don't know why this is different from phpcs, all I know that it works that way)

To complete the setup, apply and close the settings dialog.

Be aware that inspections do not show up instantly, but it takes a few seconds depending on how long the tools require to execute in your environment.

Template PHPDoc Variable Annotations

All values that are assigned to a template block should be annotated, if they are used in the template.

Usually those are $block, $escaper and $viewModels, but could be more.

We believe importing class names makes the code easier to understand. If necessary, declare class aliases.

use Hyva\Theme\Model\ViewModelRegistry;
use Magento\Framework\Escaper;
use Magento\Framework\View\Element\Template;
use Magento\Framework\View\TemplateEngine\Php as PhpTemplateEngine;

/** @var PhpTemplateEngine $this */
/** @var Template $block */
/** @var Escaper $escaper */
/** @var ViewModelRegistry $viewModels */

Only variables that are used in the template need to be annotated.