bitrix-project-structure

プロジェクト構成とオートローディング

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

ルート

• /bitrix/ — カーネルとマーケットプレイスのモジュールが含まれます。アップデートで置き換えられるため、編集しないでください（bitrix-framework）。
• /local/ — プロジェクトのすべてのコードを置きます。/local/ 内の同じ相対パスが /bitrix/ より優先されます。
• /upload/ — ユーザーおよびモジュールのファイルを置きます。

/local/
├── modules/<vendor>.<module>/   # project code lives in modules (bitrix-modules)
├── components/<ns>/<name>/      # bitrix-components
├── templates/<site_tpl>/        # site templates, component template overrides
├── routes/web.php               # bitrix-routing
├── js/<vendor>/<module>/<ext>/  # extension id vendor.module.ext (bitrix-extensions)
├── activities/                  # bizproc activities (also activities/custom)
├── gadgets/<ns>/<name>/         # desktop gadgets
├── blocks/                      # landing blocks repo
├── php_interface/
│   ├── init.php                 # every hit, before page code
│   ├── dbconn.php               # Since main 24.100 here; kernel constants
│   ├── after_connect_d7.php     # after the "default" DB connect only
│   └── user_lang/<lang>/lang.php # phrase overrides
├── .settings.php                # replaces /bitrix/.settings.php (bitrix-settings)
└── .settings_extra.php

/local/php_interface/ にも /bitrix/php_interface/ と同じアクセス保護を設定してください。

php_interface ファイル

• init.php：モジュールより前に必要な定数と、どのモジュールにも属さないフック用の実行時 addEventHandler() のみを記述します。それ以外はモジュール（install/、include.php、.settings.php）に移してください。
• after_connect_d7.php は default 接続オブジェクト内でインクルードされます。文字セット、sql_mode、タイムゾーンの設定には $this->queryExecute("SET …") を使用してください。実行されるファイルは1つだけです。/local にコピーを置くと /bitrix のファイルは無効になるため、そのステートメントも引き継いでください。その他の接続では、connections 内の 'include_after_connected' => '/abs/path.php' を指定して、それぞれのファイルを実行します。

モジュールの読み込み（Loader）

状況	呼び出し
モジュールが必須。読み込み失敗はバグ	Loader::requireModule('vendor.module') — LoaderException をスローします
オプションの連携機能	if (Loader::includeModule('crm')) { … }
シェアウェア／デモの状態確認	Loader::includeSharewareModule()

includeModule() は、モジュールが b_module に登録されていない場合（ファイルがあるだけでは不十分です）、またはその include.php が false を返した場合に false を返します。成功すると、PSR-4 のルートを登録し、include.php をインクルードして、モジュールの services を登録します。読み込みはサービスの深部ではなく、エントリーポイント（コントローラー、エージェント、コマンド）で一度だけ行ってください。旧式の CModule::IncludeModule() は互換性維持用です。

モジュールの lib/ における PSR-4

• ルート：vendor.module → Vendor\Module\ → lib/、1単語の mymodule → Bitrix\Mymodule\。
• フォルダーは名前空間のセグメント、ファイルはクラスに対応します：Vendor\Module\Public\Service\PostService → lib/Public/Service/PostService.php。
• Loader は大文字と小文字を区別したパスを試し、次にすべて小文字のパスを試します（カーネルでは両方の形式が混在しています。main 26.600 以降、多くのカーネルの lib/ ディレクトリは PascalCase です）。PostTable は post.php としても検索されます。
• カーネルの lib/ ファイルをパス指定で require しないでください。カーネルのアップデートでファイル名が変更されるためです（例：lists 26.200 で PascalCase に変更）。
• PSR-4 に準拠しない旧式コードでは、include.php 内で Loader::registerNamespace('Vendor\\Legacy', $absDir) または Loader::registerAutoLoadClasses('vendor.module', ['COldClass' => 'classes/old.php']) を使用してください。

Composer

• composer.json を DOCUMENT_ROOT の外（例：プロジェクトルート）に置き、.settings.php に 'composer' => ['value' => ['config_path' => '../composer.json']] を設定します。カーネルが vendor/autoload.php をインクルードします。
• bitrix.php（Symfony Console）で必要です — bitrix-console-commands。
• /bitrix/ にパッケージをインストールしないでください。

ファイルの優先順位

• コンポーネント、サイトテンプレート、php_interface ファイル、.settings*.php：まず /local/、次に /bitrix/。
• コンポーネントテンプレート：サイトテンプレートの components/… が、コンポーネント独自の templates/ より優先されます。
• モジュール：両方に存在する場合は /local/modules/<id> が優先されます。
• モジュールのルートは自動読み込みされません。/local/routes/web.php から require してください（bitrix-routing）。