Coding Standards ¶

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.

symfony のコードは、世界中の何千人もの開発者によって貢献されています。コードのすべての部分を見慣れたものにするために、Symfony はすべての貢献が従わなければならないいくつかのコーディング標準を定義しています。

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.

これらの Symfony コーディング標準は、PSR-1、PSR-2、PSR-4、および PSR-12 標準に基づいているため、それらのほとんどは既にご存知かもしれません。

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:

コードを手動でレビューする代わりに、Symfony を使用すると、貢献したコードが予想されるコード構文と一致することを簡単に確認できます。まず、PHP CS Fixer ツールをインストールしてから、次のコマンドを実行して問題を修正します。

    
                        $ 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:

Symfony のコーディング標準について詳しく知りたい場合は、以下で説明するほとんどの機能を含む短い例を次に示します。

    
        
                
                
                        /*
 * 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;
各カンマ区切りの後にスペースを 1 つ追加します。
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 !==);
式に対して変数をチェックするときに Yoda 条件を使用して、条件ステートメント内での偶発的な代入を回避します (これは ==、!=、===、および !== に適用されます)。
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);
return ステートメントがステートメントグループ (if ステートメントなど) 内で単独である場合を除き、return ステートメントの前に空白行を追加します。
Use return null; when a function explicitly returns null values and use return; when the function returns void values;
return null を使用します。関数が明示的に null 値を返し、return を使用する場合。関数が void 値を返すとき。
Do not add the void return type to methods in tests;
テストのメソッドに void 戻り値の型を追加しないでください。
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;
ファイルごとに 1 つのクラスを定義します。これは、外部からインスタンス化することを意図していないプライベートヘルパークラスには適用されず、PSR-0 および PSR-4 オートロード標準には関係ありません。
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() and tearDown() methods of PHPUnit tests, which must always be the first methods to increase readability;
最初にパブリックメソッドを宣言し、次に保護されたメソッドを宣言し、最後にプライベートメソッドを宣言します。この規則の例外は、クラスコンストラクターと PHPUnit テストの setUp() メソッドと TearDown() メソッドです。
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;
例外とエラーメッセージの文字列は、sprintf を使用して連結する必要があります。
Do not use else, elseif, break after if and case conditions which return or throw something;
何かを返したりスローしたりする if および case 条件の後に、else、elseif、break を使用しないでください。
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;
グローバル名前空間の一部ではないすべてのクラスに use ステートメントを追加します。
When PHPDoc tags like @param or @return include null and other types, always place null at the end of the list of types.
@param や @return などの PHPDoc タグに null やその他の型が含まれている場合は、常に型のリストの最後に null を配置します。

Naming Conventions ¶

Use camelCase for PHP variables, function and method names, arguments (e.g. $acceptableContentTypes, hasSession());
PHP 変数、関数名、メソッド名、引数 (例: $acceptableContentTypes、hasSession()) には camelCase を使用します。
Use snake_case for configuration parameters and Twig template variables (e.g. framework.csrf_protection, http_status_code);
構成パラメーターと Twig テンプレート変数 (framework.csrf_protection、http_status_code など) には snake_case を使用します。
Use SCREAMING_SNAKE_CASE for constants (e.g. InputArgument::IS_ARRAY);
定数には SCREAMING_SNAKE_CASE を使用します (例: InputArgument::IS_ARRAY)。
Use UpperCamelCase for enumeration cases (e.g. InputArgumentMode::IsArray);
列挙型の場合には UpperCamelCase を使用します (例: InputArgumentMode::IsArray)。
Use namespaces for all PHP classes, interfaces, traits and enums and UpperCamelCase for their names (e.g. ConsoleLogger);
すべての PHP クラス、インターフェース、特性、および列挙型に名前空間を使用し、それらの名前に UpperCamelCase を使用します (例: 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;
PHPUnit *TestCase を除くすべての抽象クラスには、Abstract をプレフィックスとして付けてください。初期の Symfony クラスの一部はこの規則に従っておらず、下位互換性のために名前が変更されていないことに注意してください。ただし、すべての newabstract クラスはこの命名規則に従う必要があります。
Suffix interfaces with Interface;
インターフェイスのサフィックスインターフェイス。
Suffix traits with Trait;
特性に特性の接尾辞を付けます。
Don't use a dedicated suffix for classes or enumerations (e.g. like Class or Enum), except for the cases listed below.
以下にリストされている場合を除き、クラスまたは列挙に専用の接尾辞 (Classor Enum など) を使用しないでください。
Suffix exceptions with Exception;
例外には Exception という接尾辞を付けます。
Prefix PHP attributes with As where applicable (e.g. #[AsCommand] instead of #[Command], but #[When] is kept as-is);
該当する場合は、PHP 属性の前に As を付けます (たとえば、#[Command] の代わりに #[AsCommand] を付けますが、#[When] はそのままにします)。
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);
PHP ファイル (EnvVarProcessor.php など) の名前付けには UpperCamelCase を使用し、Twig テンプレートと Web アセット (section_layout.html.twig,index.scss) の名前付けにはスネークケースを使用します。
For type-hinting in PHPDocs and casting, use bool (instead of boolean or Boolean), int (instead of integer), float (instead of double or real);
PHPDocs の型ヒントとキャストには、bool (boolean または Boolean の代わりに)、int (integer の代わりに)、float (double または real の代わりに) を使用します。
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);
サービス名は、そのクラスの完全修飾クラス名 (FQCN) と同じでなければなりません (例: 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);
同じクラスに複数のサービスがある場合は、メインサービスに FQCN を使用し、残りのサービスには小文字とアンダースコア付きの名前を使用します。オプションで、それらをドットで区切られたグループに分割します (例: 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);
パラメータ名には小文字を使用します (%env(VARIABLE_NAME)% 構文で環境変数を参照する場合を除く)。
Add class aliases for public services (e.g. alias Symfony\Component\Something\ClassName to something.service_name).
パブリックサービスのクラスエイリアスを追加します (例: alias Symfony\Component\Something\ClassName to something.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);
クラス、メソッド、および関数の PHPDoc ブロックを追加するのは、それらが名前、ネイティブ型宣言、またはコンテキスト (例: instanceof チェック) を複製しない関連情報を追加する場合のみです。
Only use annotations and types defined in the PHPDoc reference. In order to improve types for static analysis, the following annotations are also allowed:
PHPDoc リファレンスで定義されている注釈と型のみを使用してください。静的分析の型を改善するために、次の注釈も許可されています。
- Generics, with the exception of @template-covariant.
  @template-covariant を除くジェネリック。
- Conditional return types using the vendor-prefixed @psalm-return;
  ベンダー接頭辞 @psalm-return を使用した条件付きの戻り値の型。
- Class constants;
  クラス定数。
- Callable types;
  呼び出し可能な型。
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;
メソッドが何も返さない場合は、@return アノテーションを省略します。
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);
クラス、メソッド、および関数で 1 行の PHPDoc ブロックを使用しないでください。それらに含まれる注釈が 1 つだけの場合でも同様です (たとえば、/** {@inheritdoc} */ を 1 行で記述しないでください)。
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.
新しいクラスを追加する場合、または既存のクラスに大幅な変更を加える場合、個人の連絡先情報を含む @author タグが追加または拡張される場合があります。個人の連絡先情報は、コアチームへの要求ごとに更新または削除される可能性があることに注意してください。

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.
Symfony は MIT ライセンスの下でリリースされており、ライセンスブロックはすべての PHP ファイルの先頭、名前空間の前に存在する必要があります。