ドキュメント

開発者向けのプラグイン開発とテーマデザインのガイドです。

プラグイン開発

YikaiCMS のプラグインシステムは WordPress スタイルの Action / Filter フック機構を採用しており、コアコードを変更することなく機能を拡張できます。

ディレクトリ構成

各プラグインは plugins/ 配下のフォルダーであり、少なくとも 2 つのファイルを含みます：

plugins/
  my-plugin/
    plugin.json        # プラグイン記述ファイル（必須）
    main.php           # エントリーファイル（必須）
    admin.php          # 管理画面ページ（任意）

plugin.json

プラグインのメタ情報を記述し、システムはこれをもとに管理画面でプラグイン一覧を表示します。

{
    "name": "私のプラグイン",
    "version": "1.0.0",
    "description": "これはプラグインの機能説明です。",
    "author": "あなたの名前",
    "requires_php": "8.0",
    "requires_cms": "1.0.0"
}

フックシステム

main.php の中で add_action() と add_filter() を使ってフックのコールバックを登録します。

利用可能な Action フック

API 関数

// コールバックを登録（priority が小さいほど先に実行、デフォルト 10）
add_action(string $hook, callable $callback, int $priority = 10): void

// フックをトリガー
do_action(string $hook, mixed ...$args): void

// フィルターを登録
add_filter(string $hook, callable $callback, int $priority = 10): void

// フィルターを適用し、処理後の値を返す
apply_filters(string $hook, mixed $value, mixed ...$args): mixed

管理画面ページ

プラグインに管理画面の設定 UI が必要な場合は admin.php を作成し、/admin/plugin_page.php?plugin=プラグインのディレクトリ名 からアクセスします。

<?php
// plugins/my-plugin/admin.php

if (!defined('ROOT_PATH')) {
    exit('Access Denied');
}

$pageTitle = '私のプラグインの設定';
require_once ROOT_PATH . '/admin/includes/header.php';
?>

<div class="max-w-3xl">
    <h2 class="text-xl font-bold mb-4">プラグイン設定</h2>
    <!-- あなたの設定フォーム -->
</div>

<?php require_once ROOT_PATH . '/admin/includes/footer.php'; ?>

main.php の中で、プラグインカードに「管理画面」へのエントリーリンクを追加できます：

add_action('ik_admin_footer_scripts', function () {
    if (basename($_SERVER['SCRIPT_NAME']) !== 'plugin.php') return;
    echo '<script>
    (function(){
        var card = document.getElementById("plugin-my-plugin");
        if (!card) return;
        var info = card.querySelector(".text-xs.text-gray-400");
        if (info) {
            var a = document.createElement("a");
            a.href = "/admin/plugin_page.php?plugin=my-plugin";
            a.className = "text-primary hover:underline ml-4";
            a.textContent = "管理画面を開く";
            info.appendChild(a);
        }
    })();
    </script>';
});

完全な例：トップへ戻るプラグイン

ページ右下に「トップへ戻る」ボタンを表示する、最もシンプルなフロントエンドプラグインです。

plugins/back-to-top/plugin.json

{
    "name": "トップへ戻る",
    "version": "1.0.0",
    "description": "フロントページの右下にトップへ戻るボタンを表示します。",
    "author": "Yikai CMS",
    "requires_php": "8.0",
    "requires_cms": "1.0.0"
}

plugins/back-to-top/main.php

<?php
if (!defined('ROOT_PATH')) {
    exit('Access Denied');
}

add_action('ik_footer_scripts', function () {
    ?>
    <div id="backToTop" onclick="window.scrollTo({top:0,behavior:'smooth'})"
         style="position:fixed;bottom:30px;right:30px;z-index:9999;
                width:44px;height:44px;border-radius:50%;
                background:#3b82f6;color:#fff;display:none;
                align-items:center;justify-content:center;
                cursor:pointer;box-shadow:0 2px 12px rgba(59,130,246,0.4)">
        <svg width="20" height="20" viewBox="0 0 24 24" fill="none"
             stroke="currentColor" stroke-width="2.5">
            <path d="M18 15l-6-6-6 6"/>
        </svg>
    </div>
    <script>
    (function(){
        var btn = document.getElementById('backToTop');
        window.addEventListener('scroll', function(){
            btn.style.display = window.scrollY > 400 ? 'flex' : 'none';
        });
    })();
    </script>
    <?php
});

テーマデザイン

YikaiCMS のテーマシステムはファイル上書き機構に基づいています。テンプレートファイルをテーマディレクトリに置くと、システムが自動的にテーマ版を優先して読み込み、上書きされていないファイルは includes/ のデフォルトテンプレートにフォールバックします。

ディレクトリ構成

themes/
  my-theme/
    theme.json                       # テーマ記述（必須）
    assets/
      images/
        screenshot.png               # プレビュー画像（管理画面に表示）
      css/
        style.css                    # テーマのカスタムスタイル（任意）
    layouts/
      header.php                     # ヘッダーレイアウト
      footer.php                     # フッターレイアウト
    blocks/
      banner.php                     # トップページのカルーセルブロック
      about.php                      # トップページの「私たちについて」ブロック
      channel.php                    # トップページのチャンネルコンテンツブロック
      stats.php                      # 統計ブロック
      advantage.php                  # 強み紹介ブロック
      testimonials.php               # お客様の声ブロック
      cta.php                        # 行動喚起（CTA）ブロック
    partials/
      breadcrumb.php                 # パンくずナビゲーション
      page-hero.php                  # ページ上部のヒーローバナー
      pagination.php                 # ページネーションコンポーネント
      article-card.php               # 記事カード
      product-card.php               # 製品カード
      case-card.php                  # 事例カード
      job-card.php                   # 求人カード

すべてのファイルは任意であり、カスタマイズしたいファイルだけを上書きすればよいです。

theme.json

{
    "name": "私のテーマ",
    "description": "シンプルで上品な企業サイトのテンプレート",
    "version": "1.0.0",
    "author": "あなたの名前",
    "screenshot": "assets/images/screenshot.png",
    "supports": [
        "banner", "about", "stats",
        "testimonials", "advantage", "cta", "channel"
    ]
}

レイアウトファイル

layouts/header.php と layouts/footer.php は、サイト全体で共通のヘッダーとフッターです。

header.php の基本構造

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title><?php echo e($pageTitle ? $pageTitle . ' - ' : '');
        echo e(config('site_name')); ?></title>
    <link rel="stylesheet" href="/assets/css/tailwind.css">
    <!-- テーマのカスタム CSS を読み込む -->
    <link rel="stylesheet" href="<?php echo theme_asset('css/style.css'); ?>">
    <?php do_action('ik_head'); ?>
</head>
<body>
    <!-- ナビゲーションバーの HTML -->
    <?php do_action('ik_header_after'); ?>

footer.php の基本構造

    <?php do_action('ik_footer_before'); ?>
    <footer>
        <!-- フッターの HTML -->
    </footer>
    <?php do_action('ik_footer_scripts'); ?>
</body>
</html>

トップページブロック

blocks/ 配下のファイルはトップページの各ブロックに対応し、index.php が設定された順序で読み込みます。各ブロックでは以下の定義済み変数を直接利用できます：

共通コンポーネント (Partials)

partials/ 配下のファイルは再利用可能な UI コンポーネントで、一覧ページや詳細ページで require によって読み込まれます：

// パンくずを読み込む（テーマディレクトリから自動的に検索し、includes/partials/ にフォールバック）
require theme_path('partials/breadcrumb.php');

// 製品カードを読み込む
require theme_path('partials/product-card.php');

コンポーネント内で利用できる変数は呼び出しコンテキストによって異なります。たとえば product-card.php では $item（単一の製品データ）が利用できます。

よく使う関数

デプロイ設定

YikaiCMS は URL の疑似静的化（動的 URL → .html 形式）に対応し、SEO を高めます。v1.12.9 以降は単一エントリールーターを内蔵し、WordPress のリライトルールと完全互換——ほとんどの環境で 1 手順、または設定不要です。

Nginx 疑似静的化の設定

include /www/wwwroot/サイトディレクトリ/deploy/nginx-baota.conf;

server ブロックを手書きする場合は、次の 2 つを追加してください（1 つ目で機密ディレクトリを遮断。必ず先に置く）：

location ~* ^/(config|storage|vendor|includes|install/sql|bin|migrations|recipes)(/|$) {
    return 403;
}
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

location ~ ^/detail/(\d+)\.html$ { rewrite ^ /detail.php?id=$1 last; }
location ~ ^/case/(\d+)\.html$ { rewrite ^ /detail.php?id=$1 last; }
location ~ ^/case/([a-z0-9_-]+)\.html$ { rewrite ^ /detail.php?slug=$1 last; }
location ~ ^/list/(\d+)\.html$ { rewrite ^ /list.php?id=$1 last; }
location ~ ^/list/(\d+)/page/(\d+)\.html$ { rewrite ^ /list.php?id=$1&page=$2 last; }
location ~ ^/([a-z0-9_-]+)/page/(\d+)\.html$ { rewrite ^ /list.php?slug=$1&page=$2 last; }
location ~ ^/product/(\d+)\.html$ { rewrite ^ /product.php?id=$1 last; }
location ~ ^/product/([a-z0-9_-]+)/page/(\d+)\.html$ { rewrite ^ /list.php?slug=product&cat=$1&page=$2 last; }
location ~ ^/product/([a-z0-9_-]+)\.html$ { rewrite ^ /list.php?slug=product&cat=$1 last; }
location ~ ^/job/(\d+)\.html$ { rewrite ^ /job_detail.php?id=$1 last; }
location ~ ^/([a-z0-9_-]+)/([a-z0-9_-]+)\.html$ { rewrite ^ /page.php?parent=$1&slug=$2 last; }
location ~ ^/([a-z0-9_-]+)\.html$ { rewrite ^ /page.php?slug=$1 last; }
location / { try_files $uri $uri/ /index.php?$query_string; }

Apache 疑似静的化の設定

Apache 環境では、YikaiCMS に .htaccess ファイルが付属しており、インストール後に自動的に有効になるため、追加の設定は不要です。Apache で mod_rewrite モジュールが有効になっていることを確認してください。

疑似静的化が機能しない場合は、以下の点を確認してください：

• Apache 設定で AllowOverride All が有効になっている
• mod_rewrite モジュールが読み込まれている（a2enmod rewrite）
• .htaccess ファイルがサイトのルートディレクトリに存在する

Alibaba Cloud 拡張版共有ホスティング

Alibaba Cloud 拡張版 Linux 共有ホスティングは Nginx エンジンを使用しており、.htaccess をサポートしません。ホスティングのコントロールパネルで疑似静的化ルールを個別に設定する必要があります。

設定手順

1. クラウド共有ホスティング管理ページにログインする
2. 対象のホストを見つけ、管理をクリックする
3. 左側のナビゲーション：高度な環境設定 → NGINX 設定
4. テキストボックスに下記の設定内容を貼り付ける
5. 設定を保存をクリックする

location ~ ^/(config|storage|vendor|includes|install/sql|bin|migrations|recipes)/ {
    deny all;
}
location ~ /\.(git|env|htaccess|htpasswd) {
    deny all;
}
location / {
    if (!-e $request_filename) {
        rewrite ^ /index.php last;
    }
}

location / {
    rewrite ^/detail/(\d+)\.html$ /detail.php?id=$1 last;
    rewrite ^/case/(\d+)\.html$ /detail.php?id=$1 last;
    rewrite ^/case/([a-z0-9_-]+)\.html$ /detail.php?slug=$1 last;
    rewrite ^/list/(\d+)\.html$ /list.php?id=$1 last;
    rewrite ^/list/(\d+)/page/(\d+)\.html$ /list.php?id=$1&page=$2 last;
    rewrite ^/([a-z0-9_-]+)/page/(\d+)\.html$ /list.php?slug=$1&page=$2 last;
    rewrite ^/product/(\d+)\.html$ /product.php?id=$1 last;
    rewrite ^/product/([a-z0-9_-]+)/page/(\d+)\.html$ /list.php?slug=product&cat=$1&page=$2 last;
    rewrite ^/product/([a-z0-9_-]+)\.html$ /list.php?slug=product&cat=$1 last;
    rewrite ^/job/(\d+)\.html$ /job_detail.php?id=$1 last;
    rewrite ^/([a-z0-9_-]+)/([a-z0-9_-]+)\.html$ /page.php?parent=$1&slug=$2 last;
    rewrite ^/([a-z0-9_-]+)\.html$ /page.php?slug=$1 last;
    try_files $uri $uri/ /index.php?$args;
}

URL 対応表