Important

You are browsing the documentation for version 4.2 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Code Style¶

Code style is a set of conventions about how to write code. It is introduced for easier understanding of the large codebase by the wide-spread Oro community.

The following code styles are used in OroCommerce, OroCRM, OroPlatform and other Oro products.

PHP Code Style¶

Standard

PSR-2 is used as a base coding standard of the PHP code style in Oro.

Default line break separator

Default line break separator is LF (\n) - Unix and OS X style. We recommend to configure IDE and always use appropriate line break separator.

DocBlock

Use PHPDoc approach to commenting your code.

Class DocBlock

It is required to add or update a DocBlock for every class you modify or produce. Include any information that helps clarify non-obvious behavior or conditions.

Method DocBlock

It is required to add or update a DocBlock for any method you modify or produce if the method name does not fully reflect its purpose and responsibility, or the parameter or return types cannot not be defined in the PHP code. Include the following information:

Any information that helps clarify non-obvious behavior or conditions. Description should briefly reflect the purpose and responsibility of a method. Avoid description that just duplicates the method name.

The list of parameters (use @param notation), their types, and descriptions, and, if the method returns a value, the type and description (use @return annotation).

For example:

/**
 * Returns the products associated with the provided line item.
 *
 * @param int|LineItemInterface Integer ID of the line item or a line item object.
 * @return null|Product[] The array of associated products or null.
 */
public function getProductsForLineItem($lineItem): ?array;

Property DocBlock

It is required to add or update a DocBlock for every property where the data type cannot be specified in the PHP code, or if the purpose, conditions of use or possible values are not clear. Description should briefly reflect the property purpose and data type. Avoid description that just duplicates the property name.

DocBlock Sample

An example of correct DocBlock usage:

namespace Oro\Bundle\DataGridBundle\Datasource;

use Doctrine\Common\Inflector\Inflector;

use Symfony\Component\PropertyAccess\PropertyAccess;

class ResultRecord implements ResultRecordInterface
{
    /**
     * List of DTOs to hold original, non-validated user input.
     *
     * @var ValueContainer[]
     */
    private array $valueContainers = [];

    private string $value = "";

    public function __construct(array $containers)
    {
        // ...
    }

    /**
     * Get property value by name. The value will be sanitized and properly escaped.
     */
    public function getValue(string $name): string
    {
        // ...
        return $value;
    }

    /**
     * @return object|string
     */
    public function getRawValue()
    {
        // ...
        return $value;
    }
}

Marking deprecations

@deprecated annotations can be used in the maintenance branches in order to mark the elements that will be removed in an upcoming LTS version of the product.

Such deprecation notices are allowed only if the referenced changes have already been merged to the master branch, or will be merged to the master branch within the same task. Comment specifying the LTS version number in which the deprecated code will be removed is required.

Describe alternative methods or approaches if possible. The following is an example of @deprecated usage:

class ResultRecord
{
    /**
    * @deprecated Will be removed in version 4.2, use getSanitizedValues() instead.
    */
    public function getValueContainers(): array

    //....
}


/**
 * @deprecated Will be removed in version 4.2. The result records are no longer stored or processed
    by the application. You may create your own handler to capture the record submission requests.
 */
class ResultRecord
{
    //....
{

TODO usage

@todo, //TODO or any similar annotations or comments bearing the same meaning are not allowed. You may explain the rationale behind the current solution and possible alternatives in a comment. Do not make any forward looking statements or promises, you can create an issue in appropriate issue tracker instead.

Do not import classes from root namespace

Classes and functions from the root namespace should not be imported.

Import internal PHP classes example:

// incorrect
use DateTime;
use date;
$date = new DateTime();
$day = date('l');

// correct
$date = new \DateTime();
$day = \date('l');

PHP code style continuous control

PHP code style is controlled by the PHP CodeSniffer tool according to the rules defined in the phpcs.xml file.

We highly recommended developers to configure appropriate code style inspections in the IDE or run these inspections manually before merging changes to the master branch. It prevents failures of the build that checks code standards.

Note

Information on how to enable PHP CodeSniffer inspection with the custom set of rules in the PHPStorm can be found in PHPStorm documentation.

PHP mess detector

PHP code quality is also checked by the PHP Mess Detector (PHPMD) for potential problems according to the rules defined in the phpmd.xml file. It can detect possible bugs, suboptimal code, unused parameters, and helps to follow SOLID principles. In addition to these, PHPMD contains several rules that check for code complexity and can tell if the code could be refactored to improve future maintenance efforts.

@SuppressWarnings

Generally, suppression of PHPMD warnings should be used with caution. Consider refactoring to reduce the code complexity instead. It is allowed to use suppress warnings annotations in the cases where appropriate, for example:

@SuppressWarnings(PHPMD) in the code that was automatically generated by a third-party tool or library.
@SuppressWarnings(PHPMD.ExcessiveMethodLength) for the dataProvider in the PHPUnit tests in the install schema or data migrations.
@SuppressWarnings(PHPMD.TooManyMethods) for the PHPUnit test case classes, entity classes, in the install schema or data migrations.
@SuppressWarnings(PHPMD.CouplingBetweenObjects) in the install schema or data migrations.
@SuppressWarnings(PHPMD.CyclomaticComplexity) for methods consisting of single multi-way decision (“switch” or “case”) statements, when the explanation on why the limit was exceeded is provided in the nearby comment.

php-cs-fixer usage

In order to reduce time spent on the code style fixes PHP-CS-Fixer can be used to fix most code style issues in the code.

JavaScript Code Style¶

Standard

Google JavaScript Style Guide is considered as a code standard of the JavaScript code style.

JavaScript code style continuous control

JavaScript code style is controlled by the ESLint tool installed on the continuous integration server according to the rules defined in the development repository in the root folder (example: .eslintrc.yml).

It is highly recommended to configure appropriate code style inspections in the IDE or run these inspections manually before committing the changes and merging it to the project repository.

Important

To enable the JavaScript code style checker in PHPStorm, navigate to “Languages & Frameworks > JavaScript > Code Quality Tools > ESLint” and select to use the configuration from .eslintrc.yml.

To run the check manually from the command line:

First, you need to install the required js-modules in the application directory
npm install

Then, run ESLint to check JS files for code-style

npm run eslint file.js [file.js] [dir] -- [options]

.NET Code Style¶

.NET code MUST follow the Microsoft Managed Recommended Rules. This code style is controlled on the continuous integration with StyleCop.

HTML Code Style¶

There are no defined code styles for the HTML.

CSS(SCSS) Code Style¶

SCSS code style is controlled by the Stylelint tool installed on the continuous integration server according to the rules defined in the development repository in the root folder (example: .stylelintrc.yml).

We highly recommended developers to configure appropriate code style inspections in the IDE or run these inspections manually before merging changes to the target branches.

Important

To enable the CSS(SCSS) code style checker in PHPStorm, navigate to “Languages & Frameworks > Style Sheets > Stylelint”, enable it, and chose configuration file .stylelintrc.yml, .stylelintignore from the root repository.

To run the check manually from the command line:

First, install the required js-modules in the application directory:
```
npm install
```
Then, run Stylelint to check SCSS files for the code-style:
```
npm run stylelint "./src/**/*.scss" -- [options]
```

See Also