Basercms5 Plugin Development

baserCMS 5系 プラグイン開発の正本パターン集

baserCMS 5系（CakePHP 5ベース）でプラグインを新規開発・改修するときのコーディングパターンを機能別にまとめたもの。環境・ディレクトリ構成・命名規則・コアハック禁止（vendor/baserproject・vendor/cakephp は読み取り専用）などの共通ルールは basercms5-development、テーマ（templates 中心）の開発は basercms5-theme-development、4系からの移行作業は basercms-plugin-4-to-5-upgrade、テストの実行・基盤導入は basercms-unittest、bc-custom-content（カスタムコンテンツ）を使った開発は basercms5-custom-content-development を参照する。

1. 新規開発の始め方

• 雛形は bake で生成する: bin/cake bake bc_plugin {PluginName} でプラグイン雛形、bin/cake bake bc_all {ModelName} --plugin {PluginName} で Table/Entity/Controller/テンプレート一式を生成できる。既存プラグインへのテスト基盤の後付け手順は basercms-unittest を参照。
• 標準ディレクトリ構成:
  • src/{PluginName}Plugin.php — プラグインクラス
  • src/Controller/（フロント）・src/Controller/Admin/（管理画面）
  • src/Model/Table/・src/Model/Entity/
  • src/View/Helper/・src/Event/（イベントリスナー。置くだけで自動 attach される）
  • config/（config.php・setting.php・routes.php・Migrations/）
  • templates/（フロント）・templates/Admin/（管理画面。検索フォームは templates/Admin/element/search/）
  • webroot/（js/css/img。Vue ソースは webroot/js/src）
• プラグインクラスは class SamplePlugin extends \BaserCore\BcPlugin と書く。install(array $options = []): bool は return parent::install($options); を基本とし、bootstrap() は**動的な設定（実行時に決まる値の Configure 追加、ログ設定の登録など）**にのみ使う。
• setting.php / config.php は「静的な return 配列」にする（実行型コードを書かない）。動的に決まる部分は bootstrap() に分離する。

  // config/setting.php
  return [
      'BcApp' => [...],
      'BcShortCode' => ['Sample' => ['Sample.showList']],
  ];

• adminNavigation（管理メニュー）は setting.php に登録する。'plugin'・'controller' はいずれも CamelCase で書く（'controller' => 'SampleArticles'）。snake_case で書くと全管理画面が404になる（メニュー描画時のURL解決に失敗するため対象画面以外も巻き込む）。
• 管理画面URLの {controller} セグメントは実際にはプラグイン名をダッシュ区切り（kebab-case）にしたもの（例: BlogTagGroup → /baser/admin/blog-tag-group/{controller}/...）。他プラグインのURLパターンから類推せず、bin/cake routes | grep <PluginName>（大文字小文字を落として検索）で実際のルートを確認してから使う。
• BcBlog（bc-blog）の管理画面「記事編集」URLは edit/{blogContentId}/{id} の2引数が必須（Admin\BlogPostsController::beforeFilter() が $this->request->getParam('pass.0') をブログコンテンツIDとして要求し、無いと BcException: コンテンツデータが見つかりません。 になる）。記事IDだけの edit/{id} ではアクセスできない。他プラグインが特定ブログ記事の編集画面へリンクを張る場合（例: 追加フィールドプラグインの編集導線）は、edit($blogContentId, $id) のシグネチャ通り両方を渡す。
• 有効化は管理画面のプラグイン管理から行うか、plugins テーブルへ直接 INSERT（status=1）する。DBで有効化されたプラグインは自動で読み込まれるため、composer への登録や composer dump-autoload は不要。
• サードパーティ製ライブラリ（例 phpoffice/phpspreadsheet）は composer require で導入する。雛形アセット（Excel テンプレート等）は templates/Admin/Excel/... に置き、\Cake\Core\Plugin::templatePath('Sample') . 'Admin' . DS . 'Excel' . DS . ... で参照する（templatePath() は末尾スラッシュ付き）。

2. ORM / Table / Entity

責務分離: バリデーション・ビジネスロジックは Table（src/Model/Table）、行データの振る舞いは Entity（src/Model/Entity）に書く。DB変更は Migration (phinx) を使う。

• アソシエーションは initialize() で宣言し、エイリアスは複数形にする。className はプラグイン接頭辞付き・複数形で書く。エイリアスは contain()・条件キー・エンティティのプロパティ名すべてに波及する。

  public function initialize(array $config): void
  {
      parent::initialize($config);
      $this->setTable('sample_articles');
      $this->addBehavior('BaserCore.BcUpload', [...]);
      $this->belongsTo('Users', ['className' => 'BaserCore.Users', 'foreignKey' => 'user_id']);
      $this->hasMany('SampleComments', ['className' => 'Sample.SampleComments', 'foreignKey' => 'article_id', 'dependent' => true]);
      $this->belongsToMany('SampleTags', [
          'className' => 'Sample.SampleTags',
          'joinTable' => 'sample_articles_sample_tags',
          'foreignKey' => 'article_id',
          'targetForeignKey' => 'tag_id',
      ]);
  }

  dependent は hasMany/hasOne のみ有効。
• バリデーションは validationDefault() に書く。カスタムルールはシグネチャ ($value, $context) のメソッドを add() で登録する。

  public function validationDefault(\Cake\Validation\Validator $validator): \Cake\Validation\Validator
  {
      $validator->notEmptyString('title', 'タイトルを入力してください');
      $validator->add('title', 'custom', ['rule' => [$this, 'customMethod'], 'message' => '...']);
      return $validator;
  }

• 検索はクエリビルダで書く: $this->find()->where([...])->contain([...])->orderBy([...])->first()/all()。list は find('list', keyField: 'id', valueField: 'name')。
  • 配列値に IN は自動付与されない。複数値は必ず 'field IN' => (array)$values と明示する（書かないと Cannot convert value Array 例外）。空配列の IN () は例外になるので、空になりうる場合は先頭でガードして早期 return する。
  • null 一致は IS 演算子: ['field IS' => null]／否定は ['field IS NOT' => null]。
  • 関連テーブルの列で絞り込むときは contain() ではなく ->innerJoinWith('Assocs') か matching() を使う（contain は WHERE に使えない）。条件キーは複数形エイリアス（SampleComments.user_id）。常時 join すると関連なし行が除外される点に注意。
• 保存はエンティティ経由: $entity = $table->newEntity($data);（新規）または $entity = $table->patchEntity($table->get($id), $data);（更新）→ $table->save($entity);。
• belongsToMany の保存は _ids で書く: patchEntity($e, $data + ['sample_tags' => ['_ids' => [$id, ...]]], ['associated' => ['SampleTags']])。表示側は contain(['SampleTags'])。
• name/value の KVS テーブルは initialize() に $this->addBehavior('BaserCore.BcKeyValue') を足すと saveKeyValue([$key => $value]) が使える。読み出しは find()->where(['name' => $key])->first()->value。
• 集計は func()->sum() ＋ ->first()->alias ?? 0 で書く:

  $total = $this->find()
      ->where(['user_id' => $userId])
      ->select(['total' => $this->find()->func()->sum('amount')])
      ->first()->total ?? 0;

  • datetime カラムの MIN/MAX に集計関数を使わない。func()->min()/max() は結果が数値型にキャストされて壊れるため、->orderBy(['col' => 'ASC'])->first() で最古/最新行を取り、そのエンティティの日時プロパティを使う。
• afterSave で他テーブルを save する（相互に save し合う）場合は再入ガードフラグを置く。save() に callbacks オプションは存在しない（渡しても黙って無視され afterSave は常に発火する）ため、抑止はフラグで行う。

  private bool $inAfterSave = false;
  public function afterSave(EventInterface $e, EntityInterface $entity, \ArrayObject $o): void
  {
      if ($this->inAfterSave) return;
      $this->inAfterSave = true;
      try { /* 他テーブルの save 等 */ } finally { $this->inAfterSave = false; }
  }

• 削除は get($id) → delete($entity) で書く（関連の dependent => true が cascade する）。deleteAll() は ORM の cascade を通さず子が孤児として残るので、子を連れて消す削除には使わない。
• fetchTable() は Controller / Command 専用。Table・Lib・Helper・イベントリスナー内では \Cake\ORM\TableRegistry::getTableLocator()->get('Sample.SampleArticles') を使う（fetchTable を呼ぶと BadMethodCallException）。エイリアスは常に複数形。
• **getControlSource()（フォーム選択肢の供給元）**は Table に定義し、テンプレートからは $this->BcAdminForm->getControlSource('Sample.SampleArticles.user_id') のように Plugin.複数形モデル.field で呼ぶ（単数形だと MissingTableClassException）。
• disableHydration() を使うと結果はフラット連想配列になる。select には明示エイリアスを付けて（->select(['id' => 'SampleArticles.id', 'tag_name' => 'SampleTags.name'])）$row['id'] でフラット参照する。
• 生SQLが必要なときは $this->getConnection()->execute($sql)->fetchAll('assoc')（戻りはフラット連想配列）。トランザクションは $this->getConnection()->begin()/commit()/rollback()。
• プラグイン共通のメソッドは共通基底 Table（\BaserCore\Model\Table\AppTable を継承した SampleAppTable 等）に置き、各 Table はそれを継承する。

3. コントローラ

管理画面コントローラは src/Controller/Admin/ に置き、プラグインの Admin 基底（SampleAdminAppController など、BcAdminAppController を継承）を経由して継承する。

• テーブル取得は $this->fetchTable('Sample.SampleArticles')（複数形エイリアス）。
• ページネーションはクエリビルダを組んで $this->paginate($query) に渡す（PaginatorComponent は存在しない。loadComponent('Paginator') は MissingComponentException）。必要な関連は contain()、手書き結合は leftJoinWith()/innerJoinWith()/matching()、->groupBy()/->having() も使える。並べ替え・ページはクエリ文字列 ?sort=&direction=&page= で自動処理される。
• サイト設定値は \BaserCore\Utility\BcSiteConfig::get('admin_list_num') で取得する。ログインユーザーは \BaserCore\Utility\BcUtil::loginUser()（未ログイン時は false を返すので ?-> は効かない。(BcUtil::loginUser() ?: null)?->id か明示分岐で書く）。
• フラッシュメッセージは $this->BcMessage->setSuccess('...') / setError('...')。
• redirect() は必ず return $this->redirect([...]); と書く。redirect は Response を返すだけで後続コードが実行され続けるため、ガード節（引数チェック→リダイレクト）では return しないと直後の処理まで走って TypeError 等になる。例外: initialize()/beforeFilter() など : void 宣言のメソッド内では return を付けない（付けると TypeError）。
• request は immutable。getter への代入は書けない。値を足すときは withQueryParams()/withData() で新しい request を作って setRequest() する。

  $this->setRequest($this->getRequest()->withQueryParams(
      $this->getRequest()->getQueryParams() + ['begin' => $begin]
  ));

  読み取りは getData('key')/getQuery('key')/getParam('key')/getQueryParams()。ajax 判定は $this->getRequest()->is('ajax')。getParam('controller') は CamelCase（'SampleArticles'）で返る点に注意（分岐で snake_case と比較すると常に false）。
• カスタム Component は public function initialize(array $config): void { parent::initialize($config); } のシグネチャで書き、コントローラ参照は $this->getController() で取得する。使用するコントローラの initialize() で $this->loadComponent('Sample.Excel') のように明示ロードする（自動ロードはされない）。
• delete アクションの定石: $this->getRequest()->allowMethod(['post', 'delete']) → $entity = $table->get($id)（RecordNotFoundException を try/catch して「無効な処理です」→ index へ）→ $table->delete($entity)。一覧の bca-submit-token 経由の POST を受けるアクションは FormProtection の unlockedActions に登録する（§6）。
• テンプレートが参照する計算値・設定値はコントローラで明示的に set() する。旧来のコールバックによる自動注入は無いので、行ごとの計算値は Table の計算メソッド（calcBalance($entity) 等）を paginate 後にループ適用する。プラグイン設定（Configure::read('Sample')）を多数のテンプレートが参照する場合は、プラグインの Admin 基底コントローラの beforeRender() で一括 set する。

  public function beforeRender(\Cake\Event\EventInterface $event): void
  {
      parent::beforeRender($event);
      $this->set(\Cake\Core\Configure::read('Sample'));
  }

  各 Admin コントローラは BcAdminAppController 直継承ではなくこの基底を継承する（直継承だと設定ビュー変数が全画面で欠落する）。
• エラー応答は例外で書く: throw new \Cake\Http\Exception\BadRequestException(...) / NotFoundException / InternalErrorException。レスポンス操作は $this->setResponse($this->getResponse()->withStatus(400))。
• 検索インデックス・ヘルプは $this->setSearch('sample_articles_index') / $this->setHelp('...') で設定する。

4. 管理画面フォーム・一覧・検索

• 管理画面のフォームは $this->BcAdminForm を使い、入力は必ず control() で出す（input() は無い）。フロント用 $this->BcForm/$this->Form や素のウィジェット（text()/select()/multiCheckbox()）を直接呼ぶと bca-* の管理スタイルが当たらず崩れる。一覧の一括処理（ListTool.batch）・一括選択（ListTool.checkall）・submit()/button() も BcAdminForm で出す。
• フォーム開始: エンティティがあるなら create($entity)、コンテキストレスなら create(null, ['valueSources' => ['data', 'context']]) と書く（GET検索フォームは ['query', 'context']）。文字列モデル名を渡すと No context provider found for value of type string。
• 複数チェックボックスは options をループして個別 control で書く（['multiple' => 'checkbox'] や multiCheckbox() は崩れる）:

  <?php $selected = array_map('strval', (array)$this->getRequest()->getData('SampleArticle.tags')) ?>
  <?php foreach($options as $v => $label): ?>
    <?php echo $this->BcAdminForm->control('SampleArticle.tags[]', [
        'type' => 'checkbox', 'label' => $label, 'value' => $v,
        'checked' => in_array((string)$v, $selected, true), 'hiddenField' => false]) ?>
  <?php endforeach ?>

  受け側の条件は 'field IN' => (array)$values（§2）。
• control() の label に HTML を渡すときは配列形式 ['text' => '<span...>', 'escape' => false] と書く（文字列だとエスケープされ生表示）。
• 検索フォームは templates/Admin/element/search/{name}.php（単数 search/） に置く。コントローラの setSearch('sample_articles_index') がこのパスを解決する。検索は GET 送信が基本（条件がURLに残りページャ遷移でも保持）で、コントローラは getQueryParams() から条件を読む。入力値の再表示には valueSources に query を含める。
• control() の DOM 生成規則を把握して JS と整合させる（描画は通るのに JS 連携が無言で死ぬ最頻出ポイント）:
  • id は小文字ハイフン: control('SampleArticle.publish_date') → id="samplearticle-publish-date"（Text::slug による）。
  • name は Model[field] 形式: name="SampleArticle[publish_date]"。
  • バンドルJSが CamelCase id（#SampleArticlePublishDate）や別形式の name を掴む設計なら、JS 側を実生成の id/name に合わせるか、control(..., ['id' => 'SampleArticlePublishDate']) で明示 id を振る（その場合 label の for も合わせる。name は POST キーなので変えない）。フォーム全体への委譲 $("#FormId").on('change', 'select, input', ...) にすると id 依存自体をなくせる。
  • 統合テストで「JS が期待する id/name が HTML に実在する」ことを assert する番人パターンを置くと、この不整合の回帰を検出できる（描画200のテストでは検出できない。basercms-unittest 参照）。
• 年月セレクトは control('Model.field.year', ['type' => 'select', 'options' => $years, 'label' => false]) のように自前 options で書く（year()/month() というメソッドは無い）。getData('Model.field') は ['year' =>, 'month' =>] で受かる。
• 一覧 element とフォームの同居に注意: Paginator->sort() や element('pagination') を含む一覧 element を、ページネーションしない画面（編集フォームへの埋め込み等）で描画すると You must set a pagination instance using setPaginated() first で落ちる。ページャ系の描画は「専用一覧コントローラのときだけ」に getParam('controller') === 'SampleArticles'（CamelCase）でガードする。
• 生SQL等のカスタムページネーションは、総件数＋当ページ行を自前で取得し new \Cake\Datasource\Paging\PaginatedResultSet(new \ArrayIterator($rows), $params) をビュー変数に set する（PaginatorHelper が PaginatedInterface を自動検出する）。sort カラムはホワイトリストで ORDER BY を組み立てる。
• フォーム拡張フックは $this->BcFormTable->dispatchBefore()/dispatchAfter()、$this->BcAdminForm->dispatchAfterForm() を使う。
• BcBaser->link() に画像/HTML を渡すときは ['escape' => false]。アイコンボタンは ['class' => 'bca-btn-icon', 'data-bca-btn-type' => 'add', 'data-bca-btn-size' => 'lg'] の作法で書く。