basercms5-plugin-development

name	basercms5-plugin-development
description	baserCMS 5系（CakePHP 5ベース）のプラグインを新規開発・改修する際の正本パターン集。「プラグインを作成」「bc_plugin で bake」「管理画面を追加」「Table/Entity の書き方」「initialize でアソシエーション宣言」「validationDefault」「fetchTable と TableRegistry の使い分け」「BcAdminForm / control() の書き方」「検索フォーム element」「control の id/name 生成規則と JS 連携」「イベントリスナー（BcModelEventListener 等）」「adminNavigation の登録」「setting.php / config.php」「BcShortCode 登録」「paginate($query)」「redirect は return」「_ids で belongsToMany 保存」「BcKeyValue」「afterSave の再入ガード」「$.bcUtil.adminBaseUrl」「Time::format の ICU パターン」「routes.php の RouteBuilder」等で参照する。環境・ディレクトリ・命名・コアハック禁止などの共通ルールは basercms5-development、テーマ開発は basercms5-theme-development、4系→5系の移行作業は basercms-plugin-4-to-5-upgrade、テスト実行・テスト基盤導入は basercms-unittest を参照。
license	MIT

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 は / のみ有効。

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')。 は （）で返る点に注意（分岐で snake_case と比較すると常に false）。

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((), , ),  => ]) 
    
  

  受け側の条件は （§2）。

5. イベント

リスナーは src/Event/ に置く。プラグインの BcPlugin が自動 attach するため、リスナーが壊れているとイベント発火で即 Fatal になる点に注意して書く。

• 自動 attach の実体・ファイル名の厳密な規則: BaserCore\Utility\BcEvent::registerPluginEvent()（BaserCorePlugin から有効化済み全プラグインに対して呼ばれる）が、src/Event/{Plugin名}{Controller|Model|View|Helper|Mailer}EventListener.php というファイル名と完全一致するクラスだけを自動生成・EventManager::instance()->on() で登録する。例えば <Plugin> プラグインでヘッダーを差し替えるビューイベントリスナーなら、ファイル名は必ず src/Event/<Plugin>ViewEventListener.php、クラス名も <Plugin>ViewEventListener にする（名前が1文字でもズレると静かに登録されず、イベントが一切発火しない）。
• 基底クラス: モデル系は BcModelEventListener、コントローラ系は BcControllerEventListener、ビュー系は BcViewEventListener、ヘルパ系は BcHelperEventListener を継承する。
• イベント名の命名規則: public $events = [...] に登録する。
  • 自プラグインのモデルイベント: 'SampleArticles.afterSave'（Table 名の複数形）。
  • 他プラグインを修飾する場合: 'BcBlog.BlogPosts.afterSave'（プラグイン名＋Table複数形）。名前が実在イベントと一致しないとエラーも出ずに無発火になるため、発火側を grep -rn "dispatchLayerEvent\|createEvent" vendor/baserproject/... して実在するイベント名に合わせる。
  • View 系は BcViewEventDispatcher が標準イベントを {Plugin}.{ViewName}.afterRender として再ディスパッチする方式。'BcBlog.Blog.afterRender' のように View の getPlugin()/getName() に一致させる。
• ハンドラ名はイベント名の CamelCase: 'BcBlog.BlogPosts.afterSave' → public function bcBlogBlogPostsAfterSave(EventInterface $event)。型ヒントは \Cake\Event\EventInterface。
• イベントデータ: 読み取りは $event->getData('key')、書き込みは $event->setData('key', $v)、サブジェクト（Table/Controller/View）は $event->getSubject()。保存系イベントのエンティティは $event->getData('entity') で取る。
• コンストラクタで Table を即時取得しない。リスナーは bootstrap 段階で生成されるため、コンストラクタ内の TableRegistry::...->get() は MissingTableClassException になる。ハンドラ内で必要になったときに遅延取得する。
• Model.afterFind というイベントは存在しない。find 結果の加工は formatResults() かカスタム finder に書く。
• View 系ハンドラでビュー変数を読むときは $view->get('varName') を使う（ プロパティは無い）。 プロパティも無い（未知プロパティ参照は扱いとなり で全画面を巻き込む）ので で書く。

6. Vue / jQuery 連携

• 管理画面の ajax / リンク URL をハードコードしない。配置（サブディレクトリ・prefix 変更）で壊れるため、baser が用意するグローバル $.bcUtil.adminBaseUrl（baseUrl + '/' + baserCorePrefix + '/' + adminPrefix + '/'、末尾スラッシュ付き）に連結して書く: $.bcUtil.adminBaseUrl + 'sample/sample_articles/edit/' + id。
  • Vue2 のテンプレート式からはグローバル $ を参照できないので、computed adminBaseUrl() { return $.bcUtil.adminBaseUrl; } を公開し :href="adminBaseUrl + 'sample/...'" と書く。
• Vue バンドルはソース（webroot/js/src）を直して webpack で再ビルドする（コンパイル済み .bundle.js/.bundle.css を手で編集しない）。webpack.config.js があれば cd plugins/Sample && npm install && npx webpack。出力は webroot/js/[name].bundle.js、CSS は ../css/[name].bundle.css。再ビルド後に bundle へ反映されたか grep し、ブラウザは Cmd+Shift+R で確認する。
• ajax アクションは Response を返す: return $this->getResponse()->withType('application/json')->withStringBody(json_encode($rows ?: []));。文字列を return しても出力されない。Vue が参照するフィールドはフラット配列に整形して返す。
• Vue が動的生成するフォーム行（明細等）は FormProtection に弾かれる（Unexpected field '...' in POST data）。描画時に DOM に無いフィールドは送信トークンに含まれないため、動的フィールドを POST するアクションは beforeFilter() で $this->FormProtection->setConfig('unlockedActions', ['add', 'edit', ...]) に登録する（CSRF は別ミドルウェアなので維持される）。Vue 側の :name は 'Model[' + i + '][field]' 形式で書く（コントローラの getData('Model') で受かる形）。
• prop に複数型が来るなら type: [String, Number] のように許容する。ajax レスポンスが JSON でなく文字列になると v-for が文字単位で反復する（Expected Array, got String が1文字ずつ大量に出たらサーバ側エラーを疑う）。

7. 日付・数値・文字列

• $this->Time->format($d, 'yyyy-MM-dd') は ICU パターンで書く（PHP の date() 形式ではない。Y=週年・m=分・M=月なので 'Y-m-d' と書くと月が0になる）。スラッシュ区切りは 'yyyy/MM/dd'、時刻込みは 'yyyy-MM-dd HH:mm'。第2引数を省略すると日時表示になるため、日付のみは必ず指定する。BcTime->format も同様。
  • 一方、エンティティの日時プロパティの $v->format('Y/m/d') は PHP の date() 形式（DateTimeInterface::format）。TimeHelper 経由（ICU）と使い分ける。
  • null になりうる日付は $this->Time->format($e->x, 'yyyy-MM-dd')（helper は null で空文字）か $e->x?->format('Y-m-d') で書く。
• Number::format() / NumberHelper::format() / currency() は第1引数 null 不可（TypeError）。nullable な値は format($x ?? 0, [...]) / currency($e->budget ?? 0, ...) とガードする。
• Text::truncate() / BcText::truncate() も第1引数 string 必須。nullable カラムは truncate((string)$e->notes, 46) と (string) キャストする。
• 独自の数値フォーマット登録（addFormat 相当）は無い。記号なし3桁区切りは $this->Number->format($v, ['places' => 0]) で書く（currency() の第2引数は ICU の ISO 通貨コード前提で、未知コードは接頭辞としてそのまま出力される）。

8. ルーティング・ショートコード・管理画面CSS

• config/routes.php は RouteBuilder のクロージャで書く:

  <?php
  use Cake\Routing\RouteBuilder;
  return function (RouteBuilder $routes) {
      $routes->connect('/sample/*', ['plugin' => 'Sample', 'controller' => 'SampleArticles', 'action' => 'view']);
  };
  

  コントローラ名は CamelCase。Router::getRequest() を routes.php で使う場合は CLI 実行時に null になるため if (!$request) return; のガードを必ず入れる（無いと bin/cake が全コマンド停止する）。
• ショートコードは setting.php の 'BcShortCode' キーに登録する（§1のコード例参照）。登録元プラグインが無効だと未登録扱いとなり、コンテンツ中の [Sample.showList] がエラーなく生テキストのまま露出する（プラグイン有効化が前提）。
• 横長テーブル（多数列）の管理画面では、管理テーマの .bca-container(flex) 子要素 .bca-main に min-width:0 が無いためページ全体が横スクロールする。その画面の CSS に .bca-main { min-width: 0; } を足し、テーブルは overflow:auto のスクロールラッパーで囲う（position:sticky の列固定もこれで効く）。CSSがバンドル内なら webpack 再ビルド（§6）。

9. テスト

テストの実行手順・プラグイン単体（スタンドアロン）テスト基盤の導入・Fixture Factory の書き方は basercms-unittest スキルを正本として参照する。開発時の要点だけ挙げると: 管理画面はログイン付きコントローラ統合テストで GET 描画200＋POST フロー（DB 変化の assert）を固定する、描画200は warning を握り潰すのでテスト後に error.log の pristine を確認する、JS 連携がある画面は「JS が期待する DOM id/name が HTML に実在する」assert（§4の番人パターン）を置く、日付保存は値まで assert する（silently NULL を見逃さない）。