Coding Standard

Set of PHP_CodeSniffer Sniffs and PHP-CS-Fixer Fixers used by Symplify projects.

They run best with EasyCodingStandard.

Install

composer require symplify/coding-standard --dev

Rules Overview

Rules with 🔧 are configurable.

Make sure That `@param`, `@var`, `@return` and `@throw` Types Exist

class: Symplify\CodingStandard\Sniffs\Commenting\AnnotationTypeExistsSniff

services:
    Symplify\CodingStandard\Sniffs\Commenting\AnnotationTypeExistsSniff: ~

❌

<?php

class SomeClass
{
    /**
     * @var NonExistingClass
     */
    private $property;
}

👍

<?php

class SomeClass
{
    /**
     * @var ExistingClass
     */
    private $property;
}

Make `@param`, `@return` and `@var` Format United

class: Symplify\CodingStandard\Fixer\Commenting\ParamReturnAndVarTagMalformsFixer

services:
    Symplify\CodingStandard\Fixer\Commenting\ParamReturnAndVarTagMalformsFixer: ~

 <?php

 /**
- * @param $name string
+ * @param string $name
- * @return int $value
+ * @return int
  */
 function someFunction($name)
 {
 }

 class SomeClass
 {
     /**
-     * @var int $property
+     * @var int
      */
     private $property;
 }

-/* @var int $value */
+/** @var int $value */
 $value = 5;

-/** @var $value int */
+/** @var int $value */
 $value = 5;

Remove // end of ... Legacy Comments

class: \Symplify\CodingStandard\Fixer\Commenting\RemoveEndOfFunctionCommentFixer

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\Commenting\RemoveEndOfFunctionCommentFixer: ~

 <?php

 function someFunction()
 {

-} // end of someFunction
+}

Order Private Methods by Their Use Order

class: Symplify\CodingStandard\Fixer\Order\PrivateMethodOrderByUseFixer

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\Order\PrivateMethodOrderByUseFixer: ~

❌

<?php

class SomeClass
{
    public function run()
    {
        $this->call1();
        $this->call2();
    }

    private function call2()
    {
    }

    private function call1()
    {
    }
}

👍

<?php

class SomeClass
{
    public function run()
    {
        $this->call1();
        $this->call2();
    }

    private function call1()
    {
    }

    private function call2()
    {
    }
}

Order Properties From Simple to Complex

Properties are ordered by visibility first, then by complexity.

class: Symplify\CodingStandard\Fixer\Order\PropertyOrderByComplexityFixer

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\Order\PropertyOrderByComplexityFixer: ~

❌

<?php

final class SomeFixer
{
    /**
     * @var string
     */
    private $name;

    /**
     * @var Type
     */
    private $service;

    /**
     * @var int
     */
    private $price;
}

👍

<?php

final class SomeFixer
{
    /**
     * @var int
     */
    private $price;

    /**
     * @var string
     */
    private $name;

    /**
     * @var Type
     */
    private $service;
}

Prefer Another Class

🔧
class: Symplify\CodingStandard\Sniffs\Architecture\PreferredClassSniff

# ecs.yml
services:
    Symplify\CodingStandard\Sniffs\Architecture\PreferredClassSniff:
        oldToPreferredClasses:
            DateTime: 'Nette\Utils\DateTime'

❌

<?php

$dateTime = new DateTime('now');

👍

<?php

$dateTime = new Nette\Utils\DateTime('now');

Indexed PHP arrays should have 1 item per line

class: Symplify\CodingStandard\Fixer\ArrayNotation\StandaloneLineInMultilineArrayFixer

-$friends = [1 => 'Peter', 2 => 'Paul'];
+$friends = [
+    1 => 'Peter',
+    2 => 'Paul'
+];

There should not be empty PHPDoc blocks

Just like PhpCsFixer\Fixer\Phpdoc\NoEmptyPhpdocFixer, but this one removes all doc block lines.

class: Symplify\CodingStandard\Fixer\Commenting\RemoveEmptyDocBlockFixer

-/**
- */
 public function someMethod()
 {
 }

Block comment should only contain useful information about types

🔧
class: Symplify\CodingStandard\Fixer\Commenting\RemoveUselessDocBlockFixer

 /**
- * @param int $value
- * @param $anotherValue
- * @param SomeType $someService
- * @return array
  */
 public function setCount(int $value, $anotherValue, SomeType $someService): array
 {
 }

This checker keeps 'mixed' and 'object' and other types by default. But if you need, you can configure it:

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\Commenting\RemoveUselessDocBlockFixer:
        useless_types: ['mixed', 'object'] # [] by default

Block comment should not have 2 empty lines in a row

class: Symplify\CodingStandard\Fixer\Commenting\RemoveSuperfluousDocBlockWhitespaceFixer

 /**
  * @param int $value
  *
- *
  * @return array
  */
 public function setCount($value)
 {
 }

Include/Require should be followed by absolute path

class: Symplify\CodingStandard\Fixer\ControlStructure\RequireFollowedByAbsolutePathFixer

-require 'vendor/autoload.php';
+require __DIR__.'/vendor/autoload.php';

Parameters, arguments and array items should be on the same/standalone line to fit line length

🔧
class: Symplify\CodingStandard\Fixer\LineLength\LineLengthFixer

 class SomeClass
 {
-    public function someMethod(SuperLongArguments $superLongArguments, AnotherLongArguments $anotherLongArguments, $oneMore)
+    public function someMethod(
+        SuperLongArguments $superLongArguments,
+        AnotherLongArguments $anotherLongArguments,
+        $oneMore
+    )
     {
     }

-    public function someOtherMethod(
-        ShortArgument $shortArgument,
-        $oneMore
-    ) {
+    public function someOtherMethod(ShortArgument $shortArgument, $oneMore) {
     }
 }

Are 120 characters too long for you?
Do you want to break longs lines but not inline short lines or vice versa?

Change it:

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\LineLength\LineLengthFixer:
        max_line_length: 100 # default: 120
        break_long_lines: true # default: true
        inline_short_lines: false # default: true

Property name should match its key, if possible

🔧
class: Symplify\CodingStandard\Fixer\Naming\PropertyNameMatchingTypeFixer

-public function __construct(EntityManagerInterface $eventManager)
+public function __construct(EntityManagerInterface $entityManager)
 {
-    $this->eventManager = $eventManager;
+    $this->entityManager = $entityManager;
 }

This checker ignores few system classes like std* or Spl* by default. In case want to skip more classes, you can configure it:

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\Naming\PropertyNameMatchingTypeFixer:
        extra_skipped_classes:
            - 'MyApp*' # accepts anything like fnmatch

Public Methods Should have Specific Order by Interface/Parent Class

🔧
class: Symplify\CodingStandard\Fixer\Order\MethodOrderByTypeFixer

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\Order\MethodOrderByTypeFixer:
        method_order_by_type:
            Rector\Contract\Rector\PhpRectorInterface:
                - 'getNodeTypes'
                - 'refactor'

↓

 final class SomeRector implements PhpRectorInterface
 {
-    public function refactor()
+    public function getNodeTypes()
     {
-        // refactoring
+        return ['SomeType'];
     }
-
-    public function getNodeTypes()
+    public function refactor(): void
     {
-        return ['SomeType'];
+        // refactoring
     }
 }

`::class` references should be used over string for classes and interfaces

🔧
class: Symplify\CodingStandard\Fixer\Php\ClassStringToClassConstantFixer

-$className = 'DateTime';
+$className = DateTime::class;

This checker takes only existing classes by default. In case want to check another code not loaded by local composer, you can configure it:

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\Php\ClassStringToClassConstantFixer:
        class_must_exist: false # true by default

Do you want to allow some classes to be in string format?

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\Php\ClassStringToClassConstantFixer:
        allow_classes:
            - 'SomeClass'

Array property should have default value, to prevent undefined array issues

class: Symplify\CodingStandard\Fixer\Property\ArrayPropertyDefaultValueFixer

 class SomeClass
 {
     /**
      * @var string[]
      */
-    public $apples;
+    public $apples = [];

     public function run()
     {
         foreach ($this->apples as $mac) {
             // ...
         }
     }
 }

Strict types declaration has to be followed by empty line

class: Symplify\CodingStandard\Fixer\Strict\BlankLineAfterStrictTypesFixer

 <?php declare(strict_types=1);
+
 namespace SomeNamespace;

Non-abstract class that implements interface should be final

Except for Doctrine entities, they cannot be final.

🔧
class: Symplify\CodingStandard\Fixer\Solid\FinalInterfaceFixer

-class SomeClass implements SomeInterface
+final class SomeClass implements SomeInterface
 {
 }

In case want check this only for specific interfaces, you can configure them:

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\Solid\FinalInterfaceFixer:
        only_interfaces:
            - 'Symfony\Component\EventDispatcher\EventSubscriberInterface'
            - 'Nette\Application\IPresenter'

Block comment should be used instead of one liner

class: Symplify\CodingStandard\Fixer\Commenting\BlockPropertyCommentFixer

 class SomeClass
 {
-    /** @var int */
+    /**
+     * @var int
+     */
     public $count;
 }

Use explicit and informative exception names over generic ones

class: Symplify\CodingStandard\Sniffs\Architecture\ExplicitExceptionSniff

❌

<?php

throw new RuntimeException('...');

👍

<?php

throw new FileNotFoundException('...');

Class "X" cannot be parent class. Use composition over inheritance instead.

class: Symplify\CodingStandard\Sniffs\CleanCode\ForbiddenParentClassSniff

# ecs.yml
services:
    Symplify\CodingStandard\Sniffs\CleanCode\ForbiddenParentClassSniff:
        forbiddenParentClasses:
            - 'Doctrine\ORM\EntityRepository'
            # again, you can use fnmatch() pattern
            - '*\AbstractController'

❌

<?php

use Doctrine\ORM\EntityRepository;

final class ProductRepository extends EntityRepository
{
}

👍

<?php

use Doctrine\ORM\EntityRepository;

final class ProductRepository
{
    /**
     * @var EntityRepository
     */
    private $entityRepository;

    public function __construct(EntityRepository $entityRepository)
    {
        $this->entityRepository = $entityRepository;
    }
}

Use explicit return values over magic "&$variable" reference

class: Symplify\CodingStandard\Sniffs\CleanCode\ForbiddenReferenceSniff

❌

<?php

function someFunction(&$var)
{
    $var + 1;
}

👍

<?php

function someFunction($var)
{
    return $var + 1;
}

Use services and constructor injection over static method

class: Symplify\CodingStandard\Sniffs\CleanCode\ForbiddenStaticFunctionSniff

❌

<?php

class SomeClass
{
    public static function someFunction()
    {
    }
}

👍

<?php

class SomeClass
{
    public function someFunction()
    {
    }
}

Constant should have docblock comment

class: Symplify\CodingStandard\Sniffs\Commenting\VarConstantCommentSniff

class SomeClass
{
    private const EMPATH_LEVEL = 55;
}

👍

<?php

class SomeClass
{
    /**
     * @var int
     */
    private const EMPATH_LEVEL = 55;
}

Use per line assign instead of multiple ones

class: Symplify\CodingStandard\Sniffs\ControlStructure\ForbiddenDoubleAssignSniff

❌

<?php

$value = $anotherValue = [];

👍

<?php

$value = [];
$anotherValue = [];

Prefer `sprintf()` over multiple concats ( . ).

🔧
class: Symplify\CodingStandard\Sniffs\ControlStructure\SprintfOverContactSniff

❌

<?php

return 'Class ' . $oldClass . ' was removed from ' . $file . '. Use ' . self::class . " instead';

👍

<?php

return sprintf('Class "%s" was removed from "%s". Use "%s" instead', $oldClass, $file, self::class);

Is 2 . too strict? Just configure it:

# ecs.yml
services:
    Symplify\CodingStandard\Sniffs\ControlStructure\SprintfOverContactSniff:
        maxConcatCount: 4 # "3" by default

There should not be comments with valid code

class: Symplify\CodingStandard\Sniffs\Debug\CommentedOutCodeSniff

❌

<?php

// $file = new File;
// $directory = new Diretory([$file]);

Debug functions should not be left in the code

class: Symplify\CodingStandard\Sniffs\Debug\DebugFunctionCallSniff

❌

<?php

d($value);
dd($value);
dump($value);
var_dump($value);

Use service and constructor injection rather than instantiation with new

❌

<?php

class SomeController
{
   public function renderEdit(array $data)
   {
        $database = new Database;
        $database->save($data);
   }
}

👍

<?php

class SomeController
{
   public function renderEdit(array $data)
   {
        $this->database->save($data);
   }
}

This checkers ignores by default some classes, see $allowedClasses property.

In case want to exclude more classes, you can configure it with class or pattern using fnmatch:

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\DependencyInjection\NoClassInstantiationSniff:
        extraAllowedClasses:
            - 'PhpParser\Node\*'

Doctrine entities are skipped as well. You can disable that by:

# ecs.yml
services:
    Symplify\CodingStandard\Fixer\DependencyInjection\NoClassInstantiationSniff:
        includeEntities: true

Abstract class should have prefix "Abstract"

class: Symplify\CodingStandard\Sniffs\Naming\AbstractClassNameSniff

❌

<?php

abstract class SomeClass
{
}

👍

<?php

abstract class AbstractSomeClass
{
}

Class should have suffix by parent class/interface

🔧
class: Symplify\CodingStandard\Sniffs\Naming\ClassNameSuffixByParentSniff

❌

<?php

class Some extends Command
{
}

👍

<?php

class SomeCommand extends Command
{
}

This checker check few names by default. But if you need, you can configure it:

# ecs.yml
services:
    Symplify\CodingStandard\Sniffs\Naming\ClassNameSuffixByParentSniff:
        parentTypesToSuffixes:
            # defaults
            - 'Command'
            - 'Controller'
            - 'Repository'
            - 'Presenter'
            - 'Request'
            - 'Response'
            - 'EventSubscriber'
            - 'FixerInterface'
            - 'Sniff'
            - 'Exception'
            - 'Handler'

Or keep all defaults values by using extra_parent_types_to_suffixes:

# ecs.yml
services:
    Symplify\CodingStandard\Sniffs\Naming\ClassNameSuffixByParentSniff:
        extraParentTypesToSuffixes:
            - 'ProviderInterface'

It also covers Interface suffix as well, e.g EventSubscriber checks for EventSubscriberInterface as well.

Interface should have suffix "Interface"

class: Symplify\CodingStandard\Sniffs\Naming\InterfaceNameSniff

❌

<?php

interface Some
{
}

👍

<?php

interface SomeInterface
{
}

Trait should have suffix "Trait"

class: Symplify\CodingStandard\Sniffs\Naming\TraitNameSniff

❌

<?php

trait Some
{
}

👍

<?php

trait SomeTrait
{
}

Brave Checkers

Possible Unused Public Method

class: Symplify\CodingStandard\Sniffs\DeadCode\UnusedPublicMethodSniff
Requires ECS due double run feature, use with --clear-cache so all files are included.

❌

<?php

class SomeClass
{
    public function usedMethod()
    {
    }

    public function unusedMethod()
    {
    }
}

$someObject = new SomeClass;
$someObject->usedMethod();

👍

<?php

class SomeClass
{
    public function usedMethod()
    {
    }
}

$someObject = new SomeClass;
$someObject->usedMethod();

Contributing

Open an issue or send a pull-request to main repository.

suin / codingstandard Goto Github PK

codingstandard's Introduction