bitrix-best-practice-core

Bitrix Core のベストプラクティス

Bitrix/PHP で使用すべきベストプラクティスを把握するためのスキルです。

使用方法

1. タスクが関係するアーキテクチャ層を特定します。
2. その層に直接関係するルールファイルだけを開きます。
3. まず、リポジトリのより厳格なルールとモジュールの制約に従います。
4. 独自の抽象化より、Bitrix のフレームワーク標準のパターンを優先します。

ルールファイルの選択

command.md を読む場合

タスクが次のいずれかの領域に関係する場合は、command.md を読みます。

• Bitrix\Main\Command\CommandInterface、AbstractCommand、またはアプリケーションコマンドの作成
• コマンドのライフサイクルにおける run()、execute()、beforeRun()、afterRun()
• CommandValidationException、CommandException、またはコマンド結果の処理
• コマンド入力の検証、または実行におけるトランザクション境界

controller.md を読む場合

タスクが次のいずれかの領域に関係する場合は、controller.md を読みます。

• Bitrix\Main\Engine\Controller またはその派生クラスを継承するクラス
• 任意の *Action() メソッド
• Engine Controller のフィルター、属性、プレフィルター、レスポンス

error.md を読む場合

タスクが次のいずれかの領域に関係する場合は、error.md を読みます。

• Bitrix\Main\Error、Bitrix\Main\ErrorCollection、またはそれらを基にしたアプリケーションのエラークラス
• サービス、コントローラー、レスポンスフローにおける getErrors()、getError()、getErrorCollection()、getErrorByCode()
• UI、AJAX、その他のクライアント向けの code、customData、公開エラー契約の選択
• Result、コントローラーのライフサイクル、AjaxJson の間で、作成済みのエラーを引き継ぐ処理

result.md を読む場合

タスクが次のいずれかの領域に関係する場合は、result.md を読みます。

• Bitrix\Main\Result、isSuccess()、setData()、getData()、addError()、addErrors()
• サービス、コマンド、ハンドラー、インテグレーション層から Result を結果契約として返す処理
• Bitrix\Main\Result、独自の *Result クラス、暗黙的な配列のいずれを戻り値 DTO として選ぶか
• Result::setData() のペイロード構成、および成功データとエラーフローの境界

request.md を読む場合

タスクが次のいずれかの領域に関係する場合は、request.md を読みます。

• Bitrix\Main\Request、HttpRequest、$this->getRequest()、Context::getCurrent()->getRequest()
• get()、getQuery()、getPost()、getHeader()、getCookie()、getJsonList() の選択
• $_REQUEST、$_GET、$_POST、$_COOKIE、php://input をフレームワーク標準のリクエスト API に置き換える処理
• JSON ボディ、JsonPayload、decodeJson()、decodeJsonStrict()

response.md を読む場合

タスクが次のいずれかの領域に関係する場合は、response.md を読みます。

• Bitrix\Main\Response、HttpResponse、addHeader()、setStatus()、addCookie()、redirectTo()
• Bitrix\Main\Engine\Response\Json、AjaxJson、Redirect、File、HtmlContent、レンダリング用レスポンスヘルパー
• 手動の header()、Set-Cookie、setcookie()、json_encode() を Bitrix 標準のレスポンス層に置き換える処理
• コントローラーアクションまたはその他のインフラストラクチャエンドポイントで使用する HTTP レスポンスタイプの選択

routing.md を読む場合

タスクが次のいずれかの領域に関係する場合は、routing.md を読みます。

• <module>/install/routes/ 内のファイル、または /bitrix/routes/ と /local/routes/ でのルート登録
• RoutingConfigurator、prefix、group、ルートの HTTP メソッド、where、default、name
• PublicPageController、または urlrewrite.php を使用するレガシー URL のモダンルーティングへの移行
• マルチサイトインストールにおけるサイトガード、および特定サイト向けルート
• ルート内の [Controller::class, 'action'] 配列

loader.md を読むタイミング

タスクが次のいずれかの領域に関わる場合は、loader.md を読んでください。

• Loader::includeModule() または Loader::requireModule()；
• CModule::IncludeModule() または CModule::IncludeModuleEx()；
• モジュールがない場合のフォールバックを伴う、オプションのモジュール連携；
• モジュールがない場合に暗黙的にスキップせず、エラーにする必要があるフェイルファストの依存関係。

geo-ip.md を読むタイミング

タスクが次のいずれかの領域に関わる場合は、geo-ip.md を読んでください。

• Bitrix\Main\Service\GeoIp\Manager、getRealIp()、getDataResult()、または getCountryCode() / getCityName() などの便利なゲッター；
• GeoIP ルックアップ、範囲キャッシュ、または geodata における IPv4 と IPv6 の違いに関連する Bitrix\Main\Web\IpAddress；
• カスタム GeoIP ハンドラー、Bitrix\Main\Service\GeoIp\Base のサブクラス、または onMainGeoIpHandlersBuildList による登録；
• onGeoIpGetResult による GeoIP 結果の後処理；
• 単純な文字列ルックアップと、完全な Result ベースの GeoIP ルックアップの選択；
• IP アドレスによる位置情報の特定。

uri.md を読むタイミング

タスクが次のいずれかの領域に関わる場合は、uri.md を読んでください。

• Bitrix\Main\Web\Uri、new Uri($url)、getQuery()、addParams()、deleteParams()、toAbsolute()、または resolveRelativeUri()；
• Bitrix コードでの URL / URI / リダイレクト URL の解析、変更、または再構築；
• クエリー文字列、ホスト、パス、フラグメント、または絶対 URL に対する Uri、parse_url()、parse_str() の使い分け；
• preserveDots が重要となる、ドットまたはスペースを含むクエリーパラメーター。

http-client.md を読むタイミング

タスクが次のいずれかの領域に関わる場合は、http-client.md を読んでください。

• Bitrix\Main\Web\HttpClient、new HttpClient()、get()、post()、query()、または download()；
• アウトバウンド HTTP(S) リクエスト、Webhook 送信、リモートのダウンロード／アップロード、または外部 API 連携；
• リモートの http / https URL に対する file_get_contents($url) / stream_context_create() の置き換え；
• curl_init、curl_setopt、curl_exec、その他の生の curl_* 呼び出しを、フレームワーク標準のトランスポートに置き換えること。

json.md を読むタイミング

タスクが次のいずれかの領域に関わる場合は、json.md を読んでください。

• Bitrix\\Main\\Web\\Json、Json::encode()、Json::decode()、または Json::validate()；
• json_encode() / json_decode() の直接呼び出しや、ローカルの JSON コーデックヘルパーの置き換え；
• Json::DEFAULT_OPTIONS、エンコードフラグ、エンコード／デコード時の ArgumentException、またはデコードした構造の検証；
• HTML 属性内の JSON 文字列、または文字列のシリアライズと完成済み JSON レスポンスの使い分け。

jwt.md を読むタイミング

タスクが次のいずれかの領域に関わる場合は、jwt.md を読んでください。

• Bitrix\Main\Web\JWT、JWT::encode()、JWT::decode()、JWT::urlsafeB64Encode()、または JWT::urlsafeB64Decode()；
• Bitrix\Main\Web\JWK、JWK::parseKeySet()、または JWK::parseKey()；
• JWT / JWK / JWKS / JOSE 互換データの発行、検証、または解析；
• フレームワーク標準の JWT/JWK API と、トークンの手動構築、キー解析、Base64 URL セーフヘルパーの使い分け。

date-time.md を読むタイミング

タスクが次のいずれかの領域に関わる場合は、date-time.md を読んでください。

• Bitrix\Main\Type\Date または Bitrix\Main\Type\DateTime；
• createFromUserTime()、tryParse()、toUserTime()、toString()、createFromTimestamp()、または createFromPhp()；
• Bitrix コードにおける日付と時刻の解析、書式設定、またはタイムスタンプ変換；
• Bitrix の日付型と \DateTime / \DateTimeImmutable の使い分け。

option.md を読むタイミング

タスクが以下の領域のいずれかに関わる場合は、option.md を読んでください。

• Bitrix\Main\Config\Option、Option::get()、set()、getRealValue()、getForModule() または delete()；
• legacy trigger としての COption::GetOptionString()、SetOptionString()、GetOptionInt() または RemoveOption()；
• default_option.php、module options.php、サイト固有の設定、または DB 内の feature flag / policy；
• Option の永続的な設定、.settings.php の deploy-time config、一時的な runtime-state のどれを選ぶか。

logger.md を読むタイミング

タスクが以下の領域のいずれかに関わる場合は、logger.md を読んでください。

• Bitrix\Main\Diag\Logger、Bitrix\Main\Diag\LoggerFactory、LoggerRegistry、FileLogger または LogFormatter；
• Psr\Log\LoggerInterface、PSR-3 levels（info、warning、error、debug）および structured context；
• .settings.php の loggers セクションを通じた logger id の登録、または constructorParams を通じた DI；
• AddMessage2Log()、Logger::create()、またはアドホックな file_put_contents() / error_log() を framework-native logging path に置き換える場合；
• 名前付き logger id、default logger fallback、legacy logging boundary のどれを選ぶか。

uuid-generator.md を読むタイミング

タスクが以下の領域のいずれかに関わる場合は、uuid-generator.md を読んでください。

• Bitrix\Main\UuidGenerator または UuidGenerator::generateV4()；
• session id、correlation id、upload token、public proxy id、またはその他のランダムな不透明識別子用の UUID v4 の生成；
• UuidGenerator、uniqid()、Random::getBytes()、UUID の手動生成、ローカルの helper-generator のどれを選ぶか；
• {uuid} のようなラッパー内で UUID が必要でも、canonical generator は単一のままにする legacy boundary。

validation.md を読むタイミング

タスクが以下の領域のいずれかに関わる場合は、validation.md を読んでください。

• *Action() のパラメーター、または input object のプロパティに対する Bitrix\Main\Validation\Rule\...；
• ValidationParameter、ValidationService、ValidationResult、ValidationError または ValidationGroup；
• action に入る前の入力の自動バリデーション、または service layer における DTO / command の手動バリデーション；
• validation attributes、ValidationParameter、明示的な ValidationService::validate() のどれを選ぶか；
• Bitrix\Main\Validation を基盤とする custom validators および custom validation attributes。

service-locator.md を読むタイミング

タスクが以下の領域のいずれかに関わる場合は、service-locator.md を読んでください。

• Bitrix\Main\DI\ServiceLocator、ServiceLocator::getInstance()、get()、has()、addInstance() または addInstanceLazy()；
• {module}/.settings.php、service registration、service id、FQCN binding、または DI の interface binding；
• action autowiring、明示的な ServiceLocator::get(...)、共有 service に対する手動の new MyService() のどれを選ぶか；
• service クラスのアドホックな生成を framework-native container path に置き換える場合。

persistent-storage.md を読むタイミング

タスクが以下の領域のいずれかに関わる場合は、persistent-storage.md を読んでください。

• Bitrix\Main\Data\Storage\PersistentStorageInterface、StorageInterface、DeferredStorageDecorator、または ServiceLocator::get(PersistentStorageInterface::class)；
• 設定なのか一時的な runtime-state なのかを判断する必要があるシナリオでの Bitrix\Main\Config\Option::get() / Option::set()；
• TTL state、progress/checkpoint、one-time token、upload/import session、rate-limit counter、またはリクエスト間で保持するその他の一時的な server-side state；
• データの保存先として Option、persistent storage、cache（Bitrix\Main\Data\Cache / ManagedCache）のどれを選ぶか。

Когда читать cache.md

Читай cache.md, если задача затрагивает хотя бы одну из этих областей:

• Bitrix\Main\Data\Cache, ManagedCache, TaggedCache, Cache::createInstance(), initCache(), startDataCache(), endDataCache() или abortDataCache();
• Application::getInstance()->getCache(), getManagedCache(), getTaggedCache() или container binding cache-сервисов в main/.settings.php;
• выбор между простым TTL-cache, managed invalidation по key/dir и tag-based invalidation;
• CPHPCache, CCacheManager, $CACHE_MANAGER или CStackCacheManager как legacy trigger;
• derived read-cache, который можно потерять и пересчитать, в отличие от runtime-state и постоянной конфигурации.

Когда читать event.md

Читай event.md, если задача затрагивает хотя бы одну из этих областей:

• Bitrix\Main\Event, EventResult, EventManager, send() или getResults();
• генерацию классов событий и обработчиков через Bitrix CLI;
• создание собственного события, контракт параметров и ответов обработчиков или отмену операции по результатам события;
• addEventHandler(), registerEventHandler(), compatible-варианты, порядок вызова и снятие подписок;
• AddEventHandler() или RegisterModuleDependences() как legacy trigger и перенос позиционных обработчиков на D7.