注文のライフサイクル

🌐 言語: 🇻🇳 Tiếng Việt · 🇬🇧 English · 🇯🇵 日本語（現在）

GP247 のプラグイン・テンプレートのインストールガイド

はじめに

このドキュメントでは、プラグインやテンプレート（まとめて「拡張機能」と呼びます）を GP247 の Web サイトにインストールする方法を説明します。対象はサイトオーナーで、技術に詳しくない方も含みます。 GP247 には4 つのインストール方法があります。公式の拡張機能ライブラリからオンラインでインストールする方法、 手元の .zip ファイルをインポートする方法、フォルダーをサーバーにコピーして手動でインストールする方法、 そして開発者や自動化向けのコマンドライン（gp247:ext-*）です。読み終えると、自分に合った方法を選び、 手順どおりに進められるようになります。

💡 ヒント: プラグインとテンプレートのインストール方法はまったく同じです。違いは、管理画面でのメニューの場所だけです。 プラグイン（機能追加）とテンプレート（デザイン）の 2 つのメニューに分かれています。 このドキュメントで「拡張機能」と書いている箇所は、両方に当てはまります。

1. インストールの前に知っておくこと

  1. 拡張機能を管理する権限を持つアカウントで管理画面にログインする必要があります。

  2. 拡張機能は、あなたの Web サイトと互換性がある必要があります。インストール時、GP247 は拡張機能の gp247.json に宣言された 3 つの条件を自動でチェックします。

    • requireCore：必要な gp247/core のバージョン（現在の標準は 3.0）。
    • requireComposerPackages：必須のパッケージ（例：テンプレートには常に gp247/front が必要）。
    • requireGp247Extensions：先にインストールしておく必要がある他の拡張機能。

    gp247/core 2.1 から、キー requireComposerPackages/requireGp247Extensions が旧名 requirePackages/requireExtensions に代わりました。Core 2.1 は旧キーも読み込みます（後方互換）が、非推奨です。

    条件が 1 つでも欠けていると、GP247 はエラーを表示し、インストールを許可しません。先に不足しているものをインストールしてください。

  3. インストール後、GP247 はキャッシュ（ルート・設定）を自動で削除します。手作業は不要です。 テンプレートの場合は、インストール後に**「サイト情報」画面で有効化**する必要があります（6 章を参照）。 有効化して初めて、デザインが反映されます。

用語の早見表：

  • 拡張機能（Extension）：プラグインとテンプレートの総称です。
  • gp247.json：拡張機能の情報（名前、バージョン、互換性の条件）を宣言するファイルです。
  • configKey：拡張機能の一意の識別子です。フォルダー名と同じです。

2. 方法 1 — オンラインでインストール（拡張機能ライブラリから）

これは最も簡単な方法です。管理画面の中で GP247 の公式拡張機能ストアを閲覧し、ボタンを押すだけでインストールできます。 ファイルを手動でダウンロードする必要はありません。

💡 ヒント: 管理画面に入れない場合や、スクリプトでインストールしたい場合は、同じライブラリをコマンドラインからも使えます。 5.1 節を参照してください。

⚠️ 注意: この方法は、Web サイトで GP247 ライブラリへの接続が有効になっている場合にのみ表示されます （プラグインは api_plugins、テンプレートは api_templates の設定が有効）。オンラインのメニューが見当たらない場合は、 方法 2 または方法 3 を使ってください。

ステップ 0（1 回だけ）— ライブラリに接続するための API ライセンスを登録する

拡張機能ストアを閲覧する前に、Web サイトが GP247 ライブラリに自分を識別させるための API ライセンスが必要です。 このライセンスは無料です。

  1. 管理画面で API ライセンス設定（Register / Install API license）を開きます。通常、プラグイン／テンプレートの オンライン画面の中にあります。
  2. 登録／インストールをクリックします。GP247 がライブラリに接続し、あなたのドメイン用のライセンスキーを取得します。
  3. 成功すると、このキーは Web サイトのルートフォルダーにある .env ファイルの GP247_API_LICENSE 変数に自動で保存されます。 .env ファイルを手で編集する必要はありません。

GP247_API_LICENSE が設定されれば、Web サイトはライブラリに接続済みです。下のインストール手順に進んでください。 ステップ 0 は 1 回だけ行います。次回以降のインストールでは不要です。

ℹ️ 情報: 2 種類のライセンスの違い：

  • API ライセンス（ステップ 0、無料）：Web サイトがライブラリに接続して閲覧するためのキーです。GP247_API_LICENSE に保存されます。
  • 有料拡張機能のライセンス：有料の拡張機能ごとの個別ライセンスです。有料の拡張機能をダウンロードするときだけ必要です（この章の最後を参照）。

オンラインインストールの手順

  1. 管理画面にログインします。プラグイン（またはテンプレート）メニューを開き、サブメニューの**「ライブラリから」**（Online・拡張機能ストア）を選びます。
  2. GP247 ライブラリの拡張機能の一覧が表示されます。キーワードで検索したり、無料／有料で絞り込んだり、並べ替えたりできます。 各拡張機能には名前、バージョン、価格が表示されます。
  3. インストールしたい拡張機能を選び、「インストール」(Install) ボタンを押します。
  4. GP247 が自動で、ファイルのダウンロード → 互換性チェック → 展開 → インストールを行います。成功すると、 インストール成功の通知が表示され、拡張機能がインストール済みの一覧に表示されます。

有料（paid）の拡張機能について： ステップ 0 の無料 API ライセンスに加えて、有料の拡張機能にはその拡張機能専用のライセンスが必要です （購入後、あなたのドメイン用に発行されます）。まだ持っていない場合は、ダウンロード前にライセンスを有効化するよう管理画面が案内します。 無料の拡張機能は、専用ライセンスなしですぐにダウンロード・インストールできます（ステップ 0 の API ライセンスだけで十分です）。

3. 方法 2 — インポート（.zip ファイルをアップロード）

拡張機能の .zip ファイルをすでに持っている場合に使います（ライブラリ外で購入した、開発者から受け取った、自分でパッケージ化した、など）。 このファイルを管理画面からアップロードすると、GP247 が自動で展開してインストールします。

手順：

  1. プラグイン（またはテンプレート）メニューを開き、「インポート」(Import) を選びます。
  2. パソコンから拡張機能の .zip ファイルを選び、アップロード／インポートを押します。
  3. GP247 が自動でチェックしてインストールします。成功すると、拡張機能がインストール済みの一覧に表示されます。

.zip ファイルの要件：

  • 正しい .zip 形式であること（.rar、.7z などは不可）。
  • サイズは最大 50MB（さらに、サーバーのアップロード上限 — PHP の upload_max_filesize / post_max_size — を超えないこと）。
  • .zip の中に gp247.json ファイルがあること（ない場合、GP247 は「設定が正しくありません」というエラーを表示します）。
  • インストール済みの拡張機能と重複しないこと：configKey がすでにサイトに存在する場合、誤って上書きしないよう GP247 は拒否します。 新しいバージョンに上げたいときは、上書きインポートではなく**アップデート（update）**機能を使ってください。

ℹ️ 情報: 小さな注意点です。テンプレートをインポートした後、画面がテンプレートの一覧ではなくプラグインの一覧に戻ることがあります （現在のシステムの仕様です）。心配はいりません。テンプレートのファイルはテンプレートフォルダーに正しくインストールされています。 テンプレートメニューを開けば表示されます。その後、**「サイト情報」**画面（6 章）で有効化してください。

4. 方法 3 — 手動インストール（フォルダーをサーバーにコピー）

サーバーのファイルにアクセスできる（FTP、SSH、ホスティングのファイルマネージャー）場合で、拡張機能を直接置きたいときに使います。 主に開発者向けです。上の 2 つの方法が使えない場合にも使えます。

手順：

  1. 拡張機能のフォルダー全体（AppConfig.php と gp247.json を含むフォルダー）を、種類に応じてサーバーの正しい場所にコピーします。

    • プラグイン → app/GP247/Plugins/<ExtensionName>
    • テンプレート → app/GP247/Templates/<ExtensionName>

    ここで <ExtensionName> は、gp247.json に宣言された configKey と完全に一致している必要があります。

    例えば、configKey が MyBanner のプラグインは次の場所にコピーします。

    app/GP247/Plugins/MyBanner/
├── AppConfig.php
├── gp247.json
└── ...(残りのファイル)

  2. 拡張機能の public/ フォルダー（css/js/画像）は手でコピーする必要はありません。手順 4 で**「インストール」**を押すと、 GP247 が自動で public/GP247/Plugins/<ExtensionName>（または public/GP247/Templates/<ExtensionName>）にコピーします。 2026-09-27 のアップデート以降の動作です。それより古いバージョンでは、これまでどおり手でコピーしてください。

  3. 管理画面でプラグイン（またはテンプレート）メニューを開きます。コピーした拡張機能が一覧に自動で表示されます （GP247 がフォルダーをスキャンして検出します）。状態は未インストールです。

  4. その拡張機能の横にある**「インストール」**(Install) ボタンを押します。GP247 が互換性をチェックしてからインストールします。 成功すると、ボタンがインストール済みの状態に変わります。

⚠️ 注意: 拡張機能のフォルダーには AppConfig.php が必須です。GP247 はこのファイルを手がかりに検出します。 このファイルが欠けていると、拡張機能は管理画面の一覧に表示されません。

上書きコピー（または git pull）で新しいバージョンに上げる場合。 新しいバージョンを古いフォルダーに上書きコピーしても、置き換わるのはファイルだけです。 新しいバージョンのデータ更新はまだ実行されていません。

ℹ️ 対応バージョン: 2026-09-29 のアップデート以降

コピーした後、プラグイン（またはテンプレート）の一覧をもう一度開きます。バージョン列に黄色のラベル **「データ更新待ち: x → y」が付いています。その横の「データ更新を適用」**ボタン（データベースのアイコン）を押すか、 php artisan gp247:update を実行してください。詳しくは GP247 アップデートガイド — C 節を参照してください。

5. 方法 4 — コマンドライン（gp247:ext-*）

💡 ヒント: AI エージェントと一緒に作業しますか？ gp247-skills リポジトリのスキル gp247-extension-lifecycle を使ってください。 このスキルはサイトのバージョンを調べ、そのサイトに実際にあるコマンドとオプションだけを使い、インストール／有効化／無効化／アップデート／削除の各ステップの結果を報告します。

開発者、CI/CD、Docker、またはターミナルが使える共有ホスティング向けです。拡張機能のライフサイクル全体をコマンドラインから操作できます。 管理画面と同じエンジンを使うため、互換性チェック、GP247_PROTECTED_*、使用中／デフォルトテンプレートのガードもまったく同じように適用されます。 プラグインとテンプレートは同じコマンド群を使います。--type=plugin|template で選びます。

5.1. ライブラリからコマンドラインでオンラインインストール（gp247 3.x）

これはオンライン（方法 1）をターミナルで行う方法です。管理画面を開く必要がなく、スクリプトや Docker でサイトを構築するときに便利です。 Web サイトのルートフォルダーで実行します。

# 1) Web サイトごとに 1 回だけ：API ライセンス（無料）を登録 — 方法 1 のステップ 0 と同じ
php artisan gp247:ext-register-license

# 2) ライブラリから無料の拡張機能をダウンロードしてインストール（key = 拡張機能の configKey）
php artisan gp247:ext-install --type=plugin --key=News

# 有料の拡張機能：その拡張機能専用のライセンスを追加し、1 つの key ずつインストール
php artisan gp247:ext-install --type=plugin --key=ProPlugin --paid --license=<your-license>

# テンプレート：同じコマンドで --type を変更（インストール後も有効化が必要、6 章を参照）
php artisan gp247:ext-install --type=template --key=<TemplateName>
  • ステップ 1 の前に、.env の APP_URL を Web サイトの本番ドメインに設定してください（http://localhost のままにしないこと）。 ライセンスはこのドメインに紐付けられます。ドメインが違うと、その後のライブラリへの呼び出しはすべて拒否されます。
  • ext-register-license はキーを .env の GP247_API_LICENSE に自動で書き込みます。.env に書き込めない場合 （一部の共有ホスティングではファイルがロックされています）、コマンドがキーを表示するので、自分で .env に貼り付けてください。秘密にし、コミットしないでください。
  • ext-install がライセンスやドメインに関するエラーを出した場合、gp247:ext-register-license を再実行するよう案内が表示されます。
  • インストールしたプラグインは有効な状態になり、キャッシュも自動で更新されます。テンプレートはインストール後も **「サイト情報」**画面で有効化する必要があります。この手順にはコマンドがありません（6 章）。
  • ファイルはディスク上にあるがまだインストールしていない拡張機能（手動でコピーした、またはインストーラーに同梱されている）→ --key でその場でインストールします。再ダウンロードはしません。
  • 新しいバージョンへ：php artisan gp247:ext-update --type=plugin --key=News（または --all）。
  • git pull／Composer／手動コピーでファイルを置き換え済みの場合：--local を付けると何もダウンロードせず、不足しているデータ更新だけを実行します。 php artisan gp247:ext-update --local --type=plugin --key=News（または --all。 プレビューするには --dry-run を追加）。2026-09-29 のアップデート以降で使えます。
  • 必須の composer パッケージ（requireComposerPackages、例：laravel/socialite）がありますか？　先にそのパッケージを composer require してください。 ext-install はチェックするだけで、composer パッケージを自動でインストールしません。

5.2. 拡張機能のライフサイクルに関するその他のコマンド

# ローカルの拡張機能 + 状態 + 利用可能なアップデートを一覧表示
php artisan gp247:ext-list --type=plugin

# ローカルの .zip、展開済みフォルダー、またはマーケットプレイス（key 指定）からインストール
php artisan gp247:ext-install --type=plugin --file=storage/tmp/MyBanner.zip
php artisan gp247:ext-install --type=plugin --key=News

# 有効化 / 無効化 / アンインストール（複数の key を指定可能）
php artisan gp247:ext-enable  --type=plugin --key=News
php artisan gp247:ext-uninstall --type=plugin --key=News

# マーケットプレイスからアップデート（1 つ、または新しいバージョンがあるものすべて）
php artisan gp247:ext-update --type=plugin --all

# git pull / composer / 手動コピーでファイルを置き換え済み：データ更新だけを実行
php artisan gp247:ext-update --local --all --type=plugin --dry-run
php artisan gp247:ext-update --local --all --type=plugin

# マーケットプレイスを検索；有料拡張機能のライセンスを管理
php artisan gp247:ext-search --type=plugin --keyword=blog
php artisan gp247:ext-license --type=plugin --key=ProPlugin --license=XXItXX

補足：

  • どのコマンドにも --json を付けると、機械が読めるエンベロープ（{ok,command,data,warnings,error}）と 標準の終了コード（0 = 成功／0 以外 = 失敗）が得られます。スクリプトや CI に向いています。
  • バッチ：ext-install/enable/disable/uninstall は複数の key を受け付けます（--key=A --key=B または --key=A,B）。各項目は独立して処理され、キャッシュは最後に 1 回だけ再構築されます。いずれかの項目が失敗すると 0 以外で終了します。 有料の拡張機能は 1 つの key ずつインストールしてください。
  • 再実行しても安全：ext-install はインストール済みの拡張機能を拒否します（アップデートには ext-update、 再インストールには ext-uninstall を使います）。
  • 詳しいリファレンス：command-line-reference_ja.md。

6. インストール後 — 有効化と確認

  1. プラグインの場合： 通常、インストールが終わればすぐに使えます。一部のプラグインには**「有効にする／無効にする」**(Enable/Disable) と 「設定」(Config) ボタンがあります。必要に応じて調整してください。

  2. テンプレートの場合： インストールしただけでは、テンプレートはサイトに存在するだけです。ストアで使うには 有効化が必要です。管理画面 → **「システム管理」→「サイト情報」を開き、「テンプレート」**欄でテンプレートを選び、 確認を押します。1 つのストアで使えるテンプレートは 1 つです。複数ストアのサイト（MultiStore）では、ストアごとに選びます。

    ⚠️ 注意: テンプレートを変更すると、旧テンプレートのトップページのレイアウトブロックとバナーが削除され、 新しいテンプレートのサンプルデータが読み込まれます。この操作は元に戻せないため、管理画面は必ず事前に確認を求めます。 現在使っているテンプレートを選び直した場合は、何も変わりません。

    ℹ️ 情報: コマンドラインには、ストアにテンプレートを有効化するコマンドはありません。gp247:ext-enable --type=template はテンプレートの設定行を有効にするだけです。gp247:template-setup はデフォルトテンプレート （GP247_TEMPLATE_FRONT_DEFAULT）をルートストアに適用するだけです。有効化は必ず管理画面で行います。

  3. GP247 はインストール後にキャッシュを自動で削除します。何らかの理由でデザインや機能が更新されない場合は、 Web サイトのルートフォルダーで次のコマンドを実行し、キャッシュを手動で削除してください。

    php artisan optimize:clear

  4. Web サイト（または関連する管理画面）を開き、拡張機能が正しく動作しているか確認します。

7. どの方法を使うべき？（簡単な比較）

方法 使うタイミング 利点 必要なもの
オンライン 公式ストアから閲覧してすばやくインストールしたい 最も簡単、完全に自動 ライブラリ接続が有効なサイト、有料版はライセンス
インポート .zip ファイルをすでに持っている サーバーへのアクセスが不要 有効な .zip、50MB 以下、gp247.json を含む
手動 サーバーのファイル権限がある／上の 2 つの方法が使えない 自分で管理でき、アップロードや API に依存しない FTP/SSH/ファイルマネージャーの権限、正しいフォルダーへのコピー
CLI（gp247:ext-*） 開発者、CI/CD、Docker、スクリプト／バッチでのインストール スクリプト化できる（--json + 終了コード）、複数項目のバッチ、管理画面と同じエンジン プロジェクトのルートでのターミナル権限

8. よくあるトラブルと対処

  • インストール時に互換性エラーが出る： requireCore / requireComposerPackages / requireGp247Extensions の条件が不足しています。 不足しているもの（例：テンプレートの前に gp247/front）をインストールしてから、もう一度試してください。
  • インポートで「設定が正しくありません」と表示される： .zip の正しい階層に gp247.json がないか、圧縮の仕方が間違っています （親フォルダーが 1 階層余分に入っている）。圧縮ファイルの構造を確認してください。
  • インポートで重複と表示される： その拡張機能はすでにインストールされています。新しいバージョンに上げたい場合は、上書きインポートではなくアップデート機能を使ってください。
  • 手動でインストールしたが管理画面に表示されない： 正しいフォルダー（app/GP247/Plugins か Templates か）にコピーしたか、フォルダーに AppConfig.php があるかを確認してください。その後 php artisan optimize:clear を実行し、管理画面を再読み込みします。
  • インストールしたが、拡張機能の画面が崩れている（色がない、ボタンが押せない、画像が表示されない）： 静的ファイル （css/js/画像）が public/ にコピーされていません。2026-09-27 のアップデートより前に、フォルダーをコピーして拡張機能をインストールしたサイトでよく起こります。 php artisan gp247:doctor を実行してください。extension_assets の項目に不足している拡張機能が表示されます。その後 php artisan gp247:ext-publish --type=plugin --key=<ExtensionName> を実行します（テンプレートなら --type=template、すべてなら --all）。
  • .zip ファイルが大きすぎてアップロードできない： 50MB を超えているか、サーバーのアップロード上限を超えています。代わりに方法 3 （手動）を使ってください。

9. よくある質問（Q&A）

Q1: プラグインのインストールとテンプレートのインストールは違いますか？

→ インストール方法はまったく同じです（同じ方法が使えます）。違うのは操作する場所だけです。プラグインはプラグインメニュー、テンプレートは テンプレートメニューです。テンプレートだけは、インストール後に**「システム管理」→「サイト情報」で有効化**して初めて反映されます。

Q2: 管理画面に「オンライン」のメニューが見当たりません。

→ Web サイトで GP247 ライブラリへの接続（api_plugins/api_templates）が有効になっていません。方法 2（インポート） または方法 3（手動）を使ってください。

Q3: オンラインライブラリを使うには、最初に何をすればよいですか？

→ 管理画面で API ライセンス（無料）を 1 回だけ登録します。方法 1 のステップ 0 を参照してください。このキーは .env ファイルの GP247_API_LICENSE 変数に自動で保存され、Web サイトが拡張機能ストアに接続して閲覧できるようになります。

Q4: 有料の拡張機能はどうやってインストールしますか？

→ 通常どおりオンラインでインストールします。ただし、無料の API ライセンスに加えて、有料の拡張機能にはあなたのドメイン用の専用ライセンスが必要です （購入後に発行されます）。無料の拡張機能では不要です。

Q5: インポートできる .zip ファイルはどんな構造が必要ですか？

→ .zip の中に gp247.json ファイル（AppConfig.php や拡張機能の他のファイルと一緒に）が必要です。親フォルダーを余分に 1 階層含めて gp247.json が深くなりすぎないようにしてください。ファイルは 50MB 以下である必要があります。それより大きい場合は手動でインストールします。

Q6: 手動でインストールしたのに、管理画面に拡張機能が表示されません。

→ 次を確認してください。正しいフォルダー app/GP247/Plugins/<Key> または app/GP247/Templates/<Key> にコピーしたか、フォルダーに AppConfig.php があるか、<Key> が gp247.json の configKey と一致しているか。その後 php artisan optimize:clear を実行し、管理画面を再読み込みしてください。

Q7: テンプレートをインポートしたら、なぜプラグインの一覧に戻るのですか？

→ 現在のシステムの仕様です。テンプレートのファイルは正しい場所にインストールされています。テンプレートメニューを開けば表示されます。 その後、「サイト情報」（6 章）で有効化してください。

Q8: インストール後、手動でキャッシュを削除する必要がありますか？

→ 通常は不要です。GP247 はインストール後にキャッシュを自動で削除します。更新されない場合は php artisan optimize:clear を実行してください。

Q9: 古いバージョンの上に新しいバージョンをインポートで上書きできますか？

→ おすすめしません。configKey がすでに存在する場合、インポートは拒否されます。新しいバージョンに上げるには**アップデート （update）機能を使ってください。データベースに保存した設定はそのまま残ります。手動や git pull でファイルを上書きした場合は、 拡張機能の横にある「データ更新を適用」**を押す（または php artisan gp247:update を実行する）と、新しいバージョンのデータ処理が実行されます。

Q10: 拡張機能をアンインストール・削除するには？　また、うっかりソースを消さないようにするには？

→ 拡張機能の一覧には 2 段階の削除があります。「データのみ削除」（データベース内のデータ・設定だけを削除し、 ソースファイルは残します）と、「削除」（データとサーバー上のソースファイルをすべて削除します）です。 注意：有効化中のテンプレートは削除できません（先に別のテンプレートに切り替えてください）。

重要な拡張機能をうっかり削除しないよう、GP247 には保護の仕組みがあります。.env ファイルの変数 GP247_PROTECTED_PLUGINS（プラグイン用）と GP247_PROTECTED_TEMPLATES（テンプレート用）に、それらの configKey をカンマ区切りで 宣言します。例：

GP247_PROTECTED_PLUGINS="Payment,ShippingVN"
GP247_PROTECTED_TEMPLATES="GP247Front"

保護された拡張機能では、管理画面に**「データのみ削除」と「削除」の両方のボタンが表示されません**。つまり、画面からアンインストールや 削除ができず、操作ミスによるソース・データの消失を防げます。本当に削除したい場合は、対応する .env 変数からその拡張機能の名前を外してから、もう一度試してください。

コマンドラインでは、2 段階の削除は次のように対応します。gp247:ext-uninstall --type=... --key=...（インストール済み → データと ファイルの両方を削除）と、gp247:ext-uninstall ... --only-data（データだけを削除し、ファイルは残す）です。 未インストールだがディスク上に残っている拡張機能（例：同梱のプラグイン）は、--purge を付けない限り拒否されます（付けた場合はファイルだけを削除します）。 CLI も管理画面と同様に GP247_PROTECTED_* と使用中／デフォルトテンプレートのガードを守ります。 保護されている、または使用中の拡張機能は、--purge を付けても明確なメッセージとともに拒否されます。

変更履歴

日付 GP247 バージョン 変更内容
2026-09-29 拡張機能のファイルを手動コピー／git pull／Composer で置き換えた場合：一覧画面に**「データ更新待ち」ラベルと「データ更新を適用」**ボタンを表示。コマンド gp247:ext-update --local を追加（4 章、5 章）。

📅 最終更新: 2026-10-22 · ✍️ 作成者 (Author): GP247