Basercms5 Theme Development

baserCMS 5系 テーマ開発パターン集

本スキルの対象は baserCMS 5系（CakePHP 5ベース）におけるテーマの新規開発・改修。5系のテーマはプラグイン形式であり、plugins/<ThemeName>/ に配置してテンプレート（templates/）・アセット（webroot/）・少数のフロント表示用 Helper（src/View/Helper/）で構成する。環境・ディレクトリ・命名・コアハック禁止などの共通ルールは basercms5-development、テーマに Controller/Table などプラグイン相当の内部コードを持たせる場合は basercms5-plugin-development、4系テーマからの移行作業は basercms-theme-4-to-5-upgrade を参照する。

1. テーマプラグインの構造

テーマは以下のディレクトリ構成で作る（コアの参考実装: vendor/baserproject/bc-front/templates/、サンプル: plugins/BcThemeSample/）。

plugins/<ThemeName>/
├── config.php                  … テーマ情報（return 配列。'type' => 'Theme' 必須）
├── src/<ThemeName>Plugin.php   … プラグインクラス（bake 生成の雛形でよい）
├── src/View/Helper/            … テーマ独自のフロント表示用 Helper（任意）
├── templates/
│   ├── layout/                 … レイアウト（default.php 等）
│   ├── element/                … 共通エレメント（header.php / footer.php 等）
│   ├── element/widget/         … ウィジェット用 element（§5）
│   ├── Pages/                  … 固定ページテンプレート（default.php 等）
│   ├── Blog/<content>/         … ブログテンプレート（posts.php / index.php / single.php / archives.php）
│   └── Mail/<content>/         … メールフォームテンプレート（index.php / confirm.php / submit.php）
└── webroot/                    … css / js / img（テーマアセット）

• config.php は return ['type' => 'Theme', 'title' => ..., 'description' => ..., 'author' => ..., 'url' => ...]; の形式で書く。
• レイアウト templates/layout/default.php では本文を $this->fetch('content') で出力し、<head> 内は $this->BcBaser->charset() / title() / metaDescription() / css() / js() / scripts()、</body> 直前で $this->BcBaser->func() 等の BcBaser API を使って組み立てる。
• 固定ページテンプレート templates/Pages/default.php は、管理画面で編集された本文を echo $page->contents で出力する（$page は Page エンティティ）。
• コンテンツ別テンプレは templates/Blog/<コンテンツのテンプレート名>/posts.php のように「機能プラグイン名/テンプレート名/アクション名」で配置し、管理画面のコンテンツ設定で選択されたテンプレート名のディレクトリが使われる。テーマに無いテンプレートはコア（bc-front/templates/plugin/BcBlog/ plugin/BcMail/ 等）へフォールバックする。
• webroot/ 配下のアセットは /テーマ名snake形式/css/style.css のような URL（プラグイン webroot 配信）で配信される（§4）。
• テーマの適用は管理画面（テーマ管理）から行う。開発環境で直接切り替える場合は sites テーブルの theme カラムを UPDATE してキャッシュクリア（bin/cake cache clear_all）する。

2. View・ビュー変数の作法

layout / element / テンプレート内の $this は View 自身である。Helper 内の $this->getView() と混同しない（View で $this->getView() を呼ぶと Call to undefined method ...View::getView()）。

コントローラが供給するビュー変数に依存せず、テンプレート側で必要な値を自前で導出するのが基本。コアはフロントの全ビューへ $user 等のグローバル変数を供給しない。

// ログインユーザー（UserInterface|false — false があり得るので必ず判定する）
$user = \BaserCore\Utility\BcUtil::loginUser();
$authPrefixes = $user ? $user->getAuthPrefixes() : [];

// 現在のプレフィックス（Front / Admin など）
$currentPrefix = \BaserCore\Utility\BcUtil::getRequestPrefix($this->getRequest());

// セッション
$session = $this->getRequest()->getSession();

現在のコンテンツ・サイト情報はリクエスト属性から取る。どちらもエンティティで、コンテキストによっては null があり得るため ?-> で参照する。

$currentContent = $this->getRequest()->getAttribute('currentContent'); // Content エンティティ|null
$currentSite = $this->getRequest()->getAttribute('currentSite');       // Site エンティティ|null
$entityId = $currentContent?->entity_id;  // 機能側レコードID（ブログコンテンツID 等）
$siteId = $currentSite?->id;

現在のURLパスは $this->getRequest()->getPath() と書く（先頭スラッシュ付きで返る）。

3. ヘルパ

BcBaser の委譲機構（PluginBaserHelper）

$this->BcBaser->blogPosts('news', 5) のような機能系ショートカットは、BcBaserHelper 自体のメソッドではなく、各プラグインの Bc<Plugin>BaserHelper::methods() が返すマッピングテーブル経由で __call に委譲される（例: bc-blog の BcBlogBaserHelper::methods() に 'blogPosts' => ['Blog', 'posts']）。

• 実在確認は2段階で行う: ①grep -rln "function <名前>" vendor/baserproject/ で関数定義を探す → ②見つからなければ grep -rn "'<名前>'" vendor/baserproject/*/src/View/Helper/Bc*BaserHelper.php で methods() マッピングを探す。マッピング委譲のため関数定義が無いのが正常であり、①だけで「存在しない」と判定しない。
• 委譲先メソッドは提供プラグインが有効なときだけ動く。無効時は BadMethodCall になる。

よく使う静的ユーティリティ

\BaserCore\Utility\BcSiteConfig::get('formal_name');  // サイト基本設定（address / name 等のキー）
\BaserCore\Utility\BcUtil::fullUrl($url);              // フルURL生成

ヘルパの動的ロード

ヘルパは new でインスタンス化せず（DIコンテナ未注入で getService() が失敗する）、View からロードする。loadHelper() はインスタンスを返す。

$blog = $this->getView()->loadHelper('BcBlog.Blog');  // Helper 内から
$blog = $this->loadHelper('BcBlog.Blog');             // テンプレート内（$this が View）から

参照名の規約と他プラグイン依存のガード

• コア機能の参照名は Bc 接頭辞で書く: ヘルパ BcBlog.Blog、テーブル TableRegistry::getTableLocator()->get('BcBlog.BlogPosts')、element $this->BcBaser->element('BcBlog.xxx')。コアテーブルは複数形＋プラグイン接頭辞（BaserCore.Contents / BaserCore.Sites）。
• テーマから他プラグインのヘルパを呼ぶ場合は、プラグイン無効時にテーマごと落ちないよう Plugin::isLoaded() でガードし、必要なら loadHelper する。

if (\Cake\Core\Plugin::isLoaded('<Plugin>')) {
    $helper = $this->helpers()->has('Sample')
        ? $this->Sample
        : $this->loadHelper('<Plugin>.Sample');
    $helper->show(['num' => 3]);
}

4. アセットとURL

css() / js() のシグネチャ

BcBaser->css($path, $inline = true, $options = [])（js() も同様）。第2引数は $inline（false でバッファに溜めて scripts() で出力）で、media 等の属性は第3引数に書く。

$this->BcBaser->css('style');                                  // <link ...>
$this->BcBaser->css(['print'], true, ['media' => 'print']);    // 属性は第3引数
$this->BcBaser->js('theme', true, ['defer' => true]);

URL はハードコードしない

リンク・画像などの URL はルート相対（/about/ 等）をハードコードせず BcBaser->getUrl('/path') を通して書く。サブディレクトリ設置時に base が自動付与される。

<a href="<?php echo $this->BcBaser->getUrl('/about/') ?>">会社概要</a>
<?php $this->BcBaser->link('会社概要', '/about/') ?>

Helper 内で URL 文字列を組み立てる場合は \Cake\Routing\Router::url($url) を通すか、リクエストの webroot を前置する: $this->getView()->getRequest()->getAttribute('webroot') . ltrim($url, '/')。

アップロード画像の表示（BcUploadHelper::uploadImage）

uploadImage('<field>', $entity, $options) と書く——第1引数は素のフィールド名、第2引数は EntityInterface 必須（文字列不可）。BcUploadHelper はデフォルトで View の plugin/name からテーブルを解決するため、テーマや他プラグインのテンプレから使うときは 'table' => '<Plugin>.<Tables>'（BcUpload behavior 持ち）を options で明示する。画像サイズは 'imgsize'、無い時の代替は 'noimage'。file 型を含むメールフォーム系テンプレは §6 の setTableToUpload() を参照。

テーマアセットの配信形式

テーマの webroot/ 配下はテーマ名の snake_case をプレフィックスとした URL で配信される。

$this->BcBaser->css('style');  // <ThemeName> の webroot/css/style.css を解決
// URL を直接組む場合
$this->BcBaser->getUrl('/sample_theme/css/style.css');  // plugins/SampleTheme/webroot/css/style.css