bagisto-coding-standards

コーディング規約

すべての Bagisto コードに適用される基本ルールを一か所にまとめています。DataGrid、決済クラス、テーマの変更にも、パッケージの変更と同じ基準が適用されます。

機械的な判断は Pint に任せます。 vendor/bin/pint を実行し、スペース、インポート順、末尾のカンマなどはその結果に従ってください。以下に記載するのは、Pint では検出できないことであり、対応しなければレビューで差し戻される内容です。

参照ファイル

ファイル	参照するタイミング
code-style.md	PHP を記述するとき全般 — 複数節からなる条件、クラスメンバーの順序
comments.md	言語を問わず、コメントや docblock を記述するとき
laravel.md	フレームワークの慣習 — イベント、マイグレーション、設定、ヘルパー、バリデーション、キュー
data-access.md	データベースの読み書き — リポジトリのルールと唯一の例外
database-compatibility.md	クエリ、マイグレーション、または生の SQL を扱うとき — MySQL、MariaDB、PostgreSQL のすべてで動作する必要があります
security.md	出力、入力、アップロード、SQL、シークレット、決済
security-authorization.md	ルート、権限、ガード、他のユーザーのデータへのアクセス
blade.md	.blade.php を扱うとき全般 — 名前空間、: と :: の使い分け、コンポーネント、ページの骨組み
blade-formatting.md	インデント、属性の配置、@props の位置合わせ、定型例
localization.md	ユーザー向け文字列、または Resources/lang/ の変更

@php ブロック内にも PHP のルールが適用されます。Pint はブロック内を検査できません。

ルールをひと目で確認

• **すべてのメソッドとプロパティに、可視性にかかわらず DocBlock を付けます。**説明は大文字で始まり、ピリオドで終わる文とし、最大2行にします。型情報はシグネチャに記述し、ネイティブ型で表現できない情報に限り、@param／@returnを追加します。
• **クラスメンバーは、定数 → プロパティ → コンストラクター → public → protected → private の順に並べます。**可視性ごとに連続したブロックにします。public メソッドから呼び出されるヘルパーも、末尾の protected ブロックに配置します。
• **複数の節を含む条件式は複数行にし、各行の先頭に論理演算子を置きます。**節が1つだけの条件式は1行のままにします。このルールの判断基準は行の長さではなく、節の数です。
• メソッド本体、オブジェクトリテラル、マークアップ内にはコメントを書きません。「理由」を説明する1行コメントも不可です。自明でない理由は、メソッドの DocBlock またはコミットメッセージに記載します。理解するために説明文が必要な行は、名前を付けたメソッドに切り出します。comments.mdを参照してください。
• **クラスの上に DocBlock を置くことは、いかなる場合もありません。**コアクラスの98.7%にはクラスの DocBlock がありません。DocBlock はメソッド、プロパティ、定数に付け、クラス、インターフェース、トレイト、列挙型には付けません。
• **DocBlock は最大2行です。**通常は1行です。2行に収まらない場合は、DocBlock に記載する内容ではありません。削るか、コミットメッセージに移します。
• **データベースへのアクセスはすべてリポジトリを経由します。**コントローラー、リスナー、ジョブ、サービスでDB::やモデルクエリーを使ってはいけません。唯一認められる例外は、DataGrid のprepareQueryBuilder()です。
• **すべてのクエリーは MySQL、MariaDB、PostgreSQL で実行できる必要があります。**リテラルの'like'や手書きの SQL 関数ではなく、db_grammar()を使います。また、制約違反を捕捉して競合を解決してはいけません。ステートメントが失敗すると、PostgreSQL ではトランザクション全体が中断されるためです。database-compatibility.mdを参照してください。
• **イベントはクラスではなく、ドット区切りの文字列です。**例：catalog.product.update.after。イベントはbefore／afterのペアで発火させます。laravel.mdを参照してください。
• **:は PHP の値をバインドし、::はリテラルの:を Vue に渡します。**また、::が機能するのは Blade コンポーネントタグのみです。間違えてもエラーは通知されません。blade.mdを参照してください。
• **サーバー側で認可し、値を埋め込む箇所でエスケープします。**コントロールを非表示にするのは表示上の処理です。何を許可するかはルートとコントローラーが判断します。また、要素内のテキストとして安全な値でも、属性内では危険な場合があります。security.mdを参照してください。
• **ストアフロントのすべてのクエリーを、その所有者の範囲に限定します。**リクエストの ID だけで行を選択してはいけません。これは、ここで最も簡単に実際の脆弱性を引き起こす原因です。security-authorization.mdを参照してください。
• **ユーザーに表示する文字列はすべてtrans()を通します。**キーを23すべてのロケールに追加し、php artisan bagisto:translations:checkで検証します。
• **翻訳キーは kebab-case、ルート名は snake_case にします。**同じ機能でも、キーはadmin::app.eu-withdrawal.view.received-at、ルートはadmin.sales.eu_withdrawals.indexです。そのため、もう一方の表記を検索して名前を変更してはいけません。URL パスはどちらの規則にも従いません。localization.mdを参照してください。
• **手を加えた箇所は修正します。**編集するファイルに既存の違反があれば、それも修正対象です。自分が変更した行だけでなく、クラス全体のメンバーの順序と DocBlock を確認します。

コードとこれらのファイルの内容が異なる場合

チェックアウトしたコードを優先します。周囲のコードに従い、そのことを概要に記載して、差異を報告してください。これらのファイルはある時点のスナップショットであり、正とする情報源ではありません。

単にファイルの内容が間違っている場合とは異なります。変更していないクラスに DocBlock がないのは技術的負債であって、規約ではありません。最悪の例ではなく、ルールに従ってください。

関連項目

• bagisto-code-review — 他の人の変更にこれらすべてを適用します。
• bagisto-package-development — これらのルールが適用される構成です。