Coding Standards
Warning: You are browsing the documentation for Symfony 5.x, which is no longer maintained.
Read the updated version of this page for Symfony 7.2 (the current stable version).
Symfony code is contributed by thousands of developers around the world. To make every piece of code look and feel familiar, Symfony defines some coding standards that all contributions must follow.
These Symfony coding standards are based on the PSR-1, PSR-2, PSR-4 and PSR-12 standards, so you may already know most of them.
Making your Code Follow the Coding Standards
Instead of reviewing your code manually, Symfony makes it simple to ensure that your contributed code matches the expected code syntax. First, install the PHP CS Fixer tool and then, run this command to fix any problem:
1 2
$ cd your-project/
$ php php-cs-fixer.phar fix -v
If you forget to run this command and make a pull request with any syntax issue, our automated tools will warn you about that and will provide the solution.
Symfony Coding Standards in Detail
If you want to learn about the Symfony coding standards in detail, here's a short example containing most features described below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
/*
* This file is part of the Symfony package.
*
* (c) Fabien Potencier <fabien@symfony.com>
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/
namespace Acme;
use Other\Qux;
/**
* Coding standards demonstration.
*/
class FooBar
{
public const SOME_CONST = 42;
/**
* @var string
*/
private $fooBar;
private $qux;
/**
* @param $dummy some argument description
*/
public function __construct(string $dummy, Qux $qux)
{
$this->fooBar = $this->transformText($dummy);
$this->qux = $qux;
}
/**
* @deprecated
*/
public function someDeprecatedMethod(): string
{
trigger_deprecation('symfony/package-name', '5.1', 'The %s() method is deprecated, use Acme\Baz::someMethod() instead.', __METHOD__);
return Baz::someMethod();
}
/**
* Transforms the input given as the first argument.
*
* @param $options an options collection to be used within the transformation
*
* @throws \RuntimeException when an invalid option is provided
*/
private function transformText(bool|string $dummy, array $options = []): ?string
{
$defaultOptions = [
'some_default' => 'values',
'another_default' => 'more values',
];
foreach ($options as $name => $value) {
if (!array_key_exists($name, $defaultOptions)) {
throw new \RuntimeException(sprintf('Unrecognized option "%s"', $name));
}
}
$mergedOptions = array_merge($defaultOptions, $options);
if (true === $dummy) {
return 'something';
}
if (\is_string($dummy)) {
if ('values' === $mergedOptions['some_default']) {
return substr($dummy, 0, 5);
}
return ucwords($dummy);
}
return null;
}
/**
* Performs some basic operations for a given value.
*/
private function performOperations(mixed $value = null, bool $theSwitch = false)
{
if (!$theSwitch) {
return;
}
$this->qux->doFoo($value);
$this->qux->doBar($value);
}
}
Structure
- Add a single space after each comma delimiter;
- Add a single space around binary operators (
==
,&&
, ...), with the exception of the concatenation (.
) operator; - Place unary operators (
!
,--
, ...) adjacent to the affected variable; - Always use identical comparison unless you need type juggling;
- Use Yoda conditions when checking a variable against an expression to avoid
an accidental assignment inside the condition statement (this applies to
==
,!=
,===
, and!==
); - 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 anif
statement); - Use
return null;
when a function explicitly returnsnull
values and usereturn;
when the function returnsvoid
values; - Do not add the
void
return type to methods in tests; - 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 and PSR-4 autoload standards;
- Declare the class inheritance and all the implemented interfaces on the same line as the class name;
- Declare class properties before methods;
- Declare public methods first, then protected ones and finally private ones.
The exceptions to this rule are the class constructor and the
setUp()
andtearDown()
methods of PHPUnit tests, which must always be the first methods to increase readability; - Declare all the arguments on the same line as the method/function name, no matter how many arguments there are. The only exception are constructor methods using constructor property promotion, where each parameter must be on a new line with trailing comma;
- Use parentheses when instantiating classes regardless of the number of arguments the constructor has;
- Exception and error message strings must be concatenated using sprintf;
Exception and error messages must not contain backticks, even when referring to a technical element (such as a method or variable name). Double quotes must be used at all time:
1 2
- Expected `foo` option to be one of ... + Expected "foo" option to be one of ...
- Exception and error messages must start with a capital letter and finish with a dot
.
; Exception, error and deprecation messages containing a class name must use
get_debug_type()
instead of::class
to retrieve it:1 2
- throw new \Exception(sprintf('Command "%s" failed.', $command::class)); + throw new \Exception(sprintf('Command "%s" failed.', get_debug_type($command)));
- Do not use
else
,elseif
,break
afterif
andcase
conditions which return or throw something; - Do not use spaces around
[
offset accessor and before]
offset accessor; - Add a
use
statement for every class that is not part of the global namespace; - When PHPDoc tags like
@param
or@return
includenull
and other types, always placenull
at the end of the list of types.
Naming Conventions
- Use camelCase for PHP variables, function and method names, arguments
(e.g.
$acceptableContentTypes
,hasSession()
);
- Use snake_case for configuration parameters, route names and Twig template
-
variables (e.g.
framework.csrf_protection
,http_status_code
);
- Use SCREAMING_SNAKE_CASE for constants (e.g.
InputArgument::IS_ARRAY
); - Use UpperCamelCase for enumeration cases (e.g.
InputArgumentMode::IsArray
); - Use namespaces for all PHP classes, interfaces, traits and enums and
UpperCamelCase for their names (e.g.
ConsoleLogger
); - Prefix all abstract classes with
Abstract
except PHPUnit*TestCase
. Please note some early Symfony classes do not follow this convention and have not been renamed for backward compatibility reasons. However, all new abstract classes must follow this naming convention; - Suffix interfaces with
Interface
; - Suffix traits with
Trait
; - Don't use a dedicated suffix for classes or enumerations (e.g. like
Class
orEnum
), except for the cases listed below. - Suffix exceptions with
Exception
; - Prefix PHP attributes that relate to service configuration with
As
(e.g.#[AsCommand]
,#[AsEventListener]
, etc.); - Prefix PHP attributes that relate to controller arguments with
Map
(e.g.#[MapEntity]
,#[MapCurrentUser]
, etc.); - Use UpperCamelCase for naming PHP files (e.g.
EnvVarProcessor.php
) and snake case for naming Twig templates and web assets (section_layout.html.twig
,index.scss
); - For type-hinting in PHPDocs and casting, use
bool
(instead ofboolean
orBoolean
),int
(instead ofinteger
),float
(instead ofdouble
orreal
); - Don't forget to look at the more verbose Conventions document for more subjective naming considerations.
Service Naming Conventions
- A service name must be the same as the fully qualified class name (FQCN) of
its class (e.g.
App\EventSubscriber\UserSubscriber
); - If there are multiple services for the same class, use the FQCN for the main
service and use lowercase and underscored names for the rest of services.
Optionally divide them in groups separated with dots (e.g.
something.service_name
,fos_user.something.service_name
); - Use lowercase letters for parameter names (except when referring
to environment variables with the
%env(VARIABLE_NAME)%
syntax); - Add class aliases for public services (e.g. alias
Symfony\Component\Something\ClassName
tosomething.service_name
).
Documentation
- Add PHPDoc blocks for classes, methods, and functions only when they add
relevant information that does not duplicate the name, native type
declaration or context (e.g.
instanceof
checks); Only use annotations and types defined in the PHPDoc reference. In order to improve types for static analysis, the following annotations are also allowed:
- Generics, with the exception of
@template-covariant
. - Conditional return types using the vendor-prefixed
@psalm-return
; - Class constants;
- Callable types;
- Generics, with the exception of
- Group annotations together so that annotations of the same type immediately follow each other, and annotations of a different type are separated by a single blank line;
- Omit the
@return
annotation if the method does not return anything; - Don't use one-line PHPDoc blocks on classes, methods and functions, even
when they contain just one annotation (e.g. don't put
/** {@inheritdoc} */
in a single line); - When adding a new class or when making significant changes to an existing class,
an
@author
tag with personal contact information may be added, or expanded. Please note it is possible to have the personal contact information updated or removed per request to the core team.
License
- Symfony is released under the MIT license, and the license block has to be present at the top of every PHP file, before the namespace.