Coding Standards

When contributing code to Openjet, you must follow its coding standards.

Openjet follows the standards defined in the PSR-0, PSR-1 and PSR-2 documents.

Here is a short example containing most features described below:

<?php

/*
 * This file is part of the Openjet package.
 *
 * (c) Openjet SA
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

declare(strict_types=1);

namespace Acme;

/**
 * Coding standards demonstration.
 */
final class FooBar
{
    const SOME_CONST = 42;

    private $fooBar;

    /**
     * @param string $dummy Some argument description
     */
    public function __construct(string $dummy)
    {
        $this->fooBar = $this->transformText($dummy);
    }

    /**
     * Some function description
     *
     * @param string $dummy Some argument description
     * @param array  $options
     *
     * @return string|null Transformed input
     *
     * @throws \RuntimeException
     */
    private function transformText(string $dummy, array $options = []): ?string
    {
        $mergedOptions = array_merge([
            'some_default'    => 'values',
            'another_default' => 'more values',
        ], $options);

        if (true === $dummy) {
            return;
        }

        if ('string' === $dummy) {
            if ('values' === $mergedOptions['some_default']) {
                return substr($dummy, 0, 5);
            }

            return ucwords($dummy);
        }

        throw new \RuntimeException(sprintf('Unrecognized dummy option "%s"', $dummy));
    }
}

Structure

• Add a single space after each comma delimiter.
• Add a single space around operators (===, &&, ...).
• Add a comma after each array item in a multi-line array, even after the last one.
• Add a blank line before return statements, unless the return is alone inside a statement-group (like an if statement).
• Use braces to indicate control structure body regardless of the number of statements it contains.
• Define one class per file - this does not apply to private helper classes that are not intended to be instantiated from the outside and thus are not concerned by the PSR-0 standard.
• Declare class properties before methods;
• Declare public methods first, then protected ones and finally private ones.
• Use parentheses when instantiating classes regardless of the number of arguments the constructor has.
• Exception message strings should be concatenated using sprintf.

Naming Conventions

• Use camelCase, not underscores, for variable, function and method names, arguments;
• Use underscores for option names and parameter names;
• Use namespaces for all classes;
• Prefix abstract classes with Abstract.
• Suffix interfaces with Interface;
• Suffix traits with Trait;
• Suffix exceptions with Exception;
• Use alphanumeric characters and underscores for file names;
• Don’t forget to look at the more verbose Conventions document for more subjective naming considerations.

Service Naming Conventions

• A service name contains groups, separated by dots;
• All Openjet services use openjet as first group;
• Use lowercase letters for service and parameter names;
• A group name uses the underscore notation;
• Each service has a corresponding parameter containing the class name, following the service_name.class convention.

Automated Coding Standard Enforcement

You can check your code for Openjet coding standard by running the following command:

$ vendor/bin/ecs check src tests

Some of the violations can be automatically fixed by running the same command with --fix suffix like:

$ vendor/bin/ecs check src tests --fix

Note

Most of Openjet coding standard checks are extracted to SyliusLabs/CodingStandard package so that reusing them in your own projects is effortless. Too learn about details, take a look at its readme.

Documentation

• Add PHPDoc blocks for all classes, methods, and functions;
• Omit the @return tag if the method does not return anything;
• The @package and @subpackage annotations are not used.

License

• Openjet is released under the proprietary license, and the license block has to be present at the top of every PHP file, before the namespace.