bitrix-framework

Bitrix Framework の標準規約

ベースライン：main 23.0+ · 検証済み：main 26.800.0

タスクに応じたスキルは説明を見て選択してください。このファイルには、すべてのスキルで前提となるルールを記載しています。

バージョンポリシー

• まずプロジェクトを確認します：bitrix/modules/main/classes/general/version.php → SM_VERSION。
• **Since main X.Y** — この機能にはそのバージョンが必要です。各スキルにフォールバックが記載されています。
• **Since main X.Y\*** — 正確なバージョンは不明ですが、X.Y で存在が確認されており、main 25.100.500 には存在しません。少し前のバージョンから存在する可能性があります。モジュールも同様です（**Since rest 26.200\***）：main 25.100.500 に同梱されたモジュールバージョンには存在しません。
• カーネルのソース：bitrix/modules/<module>/lib/。main 26.600 以降、多くの lib/ ディレクトリ名は PascalCase（lib/Data）です。古いものは小文字です。大文字と小文字を区別せずに検索してください。

機能	main での開始バージョン
ルーティング（/local/routes）	21.400
/local/.settings.php	24.100
バリデーション（Bitrix\Main\Validation）	24.300
コントローラーのレンダリングヘルパー	25.700
新しい make:*（サービス、エンティティ、イベント、メッセージ、エージェントなど）	25.900
永続ストレージ	25.1100
コントローラーのフィルター属性、アクションパラメーターのルール、LoggerFactory	26.250*
モジュールインストーラーの install/migrations（UpdateSystem\Migration）	26.600*
#[ActionAccess]	26.600*
機能フラグ Config\Feature	26.700

厳守すべき規約

• カスタムコードはすべて /local/ に配置し、/bitrix/ は編集しないでください。/local/ のファイルは、/bitrix/ の同じパスにあるファイルより優先されます。
• まず D7 を使います。D7 API が存在しない場合に限り、レガシー（CIBlock*、CUser、$DB）を使い、その旨をコメントに記載してください。
• コントローラー、ルート、コンポーネント、イベントハンドラーは薄く保ち、ロジックはサービスに、データは ORM テーブルに配置してください。
• モジュールのクラスを使う前に、Loader::includeModule()／requireModule() を呼び出してください。
• declare(strict_types=1)、型付きシグネチャを使用し、モジュール間では例外やマジック配列ではなく Result／Error を使ってください。
• /local/.settings.php は /bitrix/.settings.php 全体を置き換えます。変更したセクションだけでなく、すべてのセクションをコピーしてください。
• ルートは /local/routes/*.php にのみ追加してください（モジュールのルートはそこから require します）。urlrewrite.php に新しいルートを追加しないでください。
• マイグレーション：モジュール独自のテーブル／イベント／エージェントは、そのモジュールのインストーラー（install/migrations、bitrix-modules）に配置します。プロジェクトデータと設定は sprint.migration に配置します。インストールされていない場合は、インストールを提案してください。マイグレーションフレームワークをでっち上げないでください。

DI の境界

コンテキスト	コンストラクター DI	方法
アプリケーションサービス	はい	ServiceLocator::get(FQCN) による自動注入。インターフェースまたはスカラー引数の場合に限り、services に登録します
コントローラーアクション	はい、パラメーター	具象クラスを型指定します。アクションパラメーターのインターフェースは解決されません
コントローラーコンストラクター	いいえ	エンジンから渡されるのは Request のみです
コンソールコマンド	いいえ	execute() 内で ServiceLocator::getInstance()->get() を使います
イベントハンドラー	いいえ	ハンドラー内で解決します
Messenger レシーバー	はい	自動注入されます。インターフェースまたはスカラー引数の場合に限り登録します

具象クラスに対して className のみを指定した services エントリーは、自動注入を無効にします（引数なしで new $class() が呼び出されます）。constructor クロージャーまたは constructorParams を使用するか、登録しないでください。詳細：bitrix-service-locator。

セキュリティのデフォルト設定

• $_GET／$_POST／$_SESSION／$_COOKIE は読み取らず、Context のリクエストと Application::getSession() を使ってください。
• AJAX アクションではデフォルトのプリフィルター（Authentication、HttpMethod、Csrf）を維持し、各アクションで権限をチェックしてください。
• 出力をエスケープし（htmlspecialcharsbx、Json::encode）、入力をキャストし、ORM の select／order／runtime／ExpressionField に渡される値はすべてホワイトリストで制限してください。
• シークレットは環境変数または .settings.php から取得し、コード、オプション、マイグレーションには記載しないでください。

完了前の確認事項

• コードは /local/ にあり、モジュールが読み込まれ、厳密な型指定がされていること。
• すべてのカーネルクラス、メソッド、名前付き引数がプロジェクトのメインバージョンに存在すること（Since を確認）。
• コントローラー／コンポーネント／テンプレートで DB にアクセスせず、エラーは Result を介して返されること。
• 読み取りが繰り返される場合はタグ付きキャッシュを使用し、ORM キャッシュは cleanCache() でクリアすること。
• イベントとエージェントはインストール時に登録し、アンインストール時に削除すること。
• 本番環境では exception_handling.debug が false であること。