運用ガイド

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

GP247 アップデートガイド

はじめに

このドキュメントでは、GP247（S-Cart）のウェブサイトを新しいバージョンにアップデートする方法を説明します。 稼働中のサイトにとって安全な方法です。データもカスタマイズも失いません。対象はサイト管理者です。技術に詳しくない方でも大丈夫です。手順どおりに進め、コマンドを正しくコピーするだけで完了します。ポイントは GP247 の標準コマンドを優先すること （gp247:update、gp247:info、gp247:doctor）です。パッケージ（core/front/shop）ごとの個別コマンドをたくさん覚える必要はもうありません。

ℹ️ 区別すべき 2 種類のコマンド:

標準コマンド（推奨）: gp247:update — 1 つのコマンドで、サイトにある すべての GP247 パッケージのアップデートを処理します。

パッケージ別コマンド（上級者向け）: gp247:core-update、gp247:shop-update など — 1 つのパッケージだけを対象に実行します。通常は直接呼び出す必要はありません。 gp247:update が正しい順番で代わりに呼び出してくれるからです。

アップデートは 2 つの作業で構成されます

GP247 のアップデートには、必ず 2 つの独立した作業があります。両方とも実行してください。

ソースコードの更新 — 各パッケージの新しいコードを Composer（composer update）でダウンロードします。この手順で変わるのは vendor/ フォルダ内のファイルだけです。
変更をサイトに適用 — データ構造（データベース）の更新、キャッシュの再作成などを、標準 artisan コマンド gp247:update で行います。

⚠️ 注意: composer update を実行するだけでは不十分です。手順 2 を省略すると、コードは新しいのにデータ構造やキャッシュが古いままになり、サイトでエラーが起きることがあります。

ℹ️ 対応バージョン: GP247 v2.1（最初の公開版）から。データ構造を変える変更、 または既存データの意味を変える変更には、すべて自動変換の処理が付いています。それを gp247:update が実行します。手順 2 が必須なのはこのためです。また、php artisan migrate を自分で実行する必要が一切ないのもこのためです。どの変換処理も再実行しても安全です。コマンドを 2 回実行しても、それ以上は何も変わりません。

アップデート前の準備

最初にバックアップを取ります。 データベースとソースコードのフォルダをバックアップします。これが最も大切な手順です。問題が起きても、いつでも元のバージョンに戻せます。
現在のバージョンを確認します。 ターミナル（Windows では「コマンドプロンプト」）を開き、ウェブサイトのルートフォルダに移動して、次のように入力します。
```
php artisan gp247:info
```
成功すると、インストール済みパッケージ（core / front / shop）のバージョンが一覧表示されます。アップデート後に比較できるよう、この数字を控えておいてください。
（推奨）環境を確認します。 診断コマンドを実行して、サーバーが条件を満たしているか確認します（PHP のバージョン、必須拡張モジュール、ファイルの書き込み権限、DB 接続）。
```
php artisan gp247:doctor
```
すべての項目が OK なら、安心してアップデートできます。fail の項目があれば、先にその項目を完全に解決してからアップデートしてください。

アップデート手順（標準・推奨の方法）

ターミナルでウェブサイトのルートフォルダに移動します。
Composer で新しいソースコードをダウンロードします。使っているパッケージに合わせて実行します。わからない場合は 3 つとも実行してかまいません。存在しないパッケージはスキップされます。
```
composer update gp247/core
composer update gp247/front
composer update gp247/shop
```
成功すると、Composer がアップグレードされたパッケージの一覧を表示します。
標準コマンド 1 つで変更をサイトに適用します。
```
php artisan gp247:update
```
このコマンドは、次の処理を自動で順番に行います（安全で、データを壊しません）。
- core を更新します。
- shop のデータ構造をアップグレードします（shop モジュールがインストールされている場合のみ）。
- 使用中のデータより新しいファイルを持つプラグイン／テンプレートのデータ更新を適用します（たとえばプラグインを git pull した直後など）。詳しくは下の C 項を参照してください。
- サイトが新しいコードを読み込めるよう、キャッシュ（route/config）を再作成します。
成功すると、実行した手順が表示されます（例: gp247:core-update、 gp247:cache-rebuild）。
最後に確認します。 もう一度 php artisan gp247:info を実行し、準備のときに控えたバージョン番号と比べます。新しいバージョンになっていれば完了です。サイト（トップページと管理画面）を開いて、正常に表示されることも確認してください。

✅ ほとんどのウェブサイトでは、上の 4 つの手順で十分です。以下の項目は、特別な必要があるとき（翻訳の再取得、公開済みの画面デザインの再作成など）にだけ使います。

上級者向けオプション

A. 言語ファイルの再取得（`--overwrite-lang`）

既定では、gp247:update は管理画面で自分で修正した翻訳をそのまま残します。パッケージの最新の既定翻訳を取り込みたい場合（これまで修正した言語文字列は上書きされます）は、次のオプションを追加します。

php artisan gp247:update --overwrite-lang

⚠️ 注意: 翻訳を既定値に本当にリセットしたいときだけ使ってください。多く修正している場合は、先に言語テーブルをバックアップしてください。詳しくは言語システムのドキュメントを参照してください。

B. 公開済みの画面デザイン／アセットの再作成（`--publish=<tokens>`）

composer update が更新するのは vendor/ 内のコードだけです。外部に公開（publish）済みの画面ファイル（public/GP247 内の管理画面 CSS/JS、resources/views/vendor/… 内の view、 app/GP247/… 内のストアフロントのテンプレート）は、自動では上書きされません。これらを更新したい場合は、--publish オプションに「トークン」の一覧（カンマ区切り）を指定します。

php artisan gp247:update --publish=core-public                 # 安全: ビルド済みの管理画面 CSS/JS だけを更新
php artisan gp247:update --publish=core-public,front-view      # ストアフロントのテンプレートも上書き（データを破壊）
php artisan gp247:update --publish=all                         # すべてを更新（データを破壊 — 先にバックアップ）

有効なトークン: core-public、core-view、front-public、front-view、 shop-view-admin、shop-view-front、all。

📖 各トークンがどのフォルダに影響するかは、コマンドラインリファレンスの「gp247:update」の項を参照してください。

C. `git pull`、Composer、手動コピーでプラグイン／テンプレートを更新した場合

ℹ️ 対応バージョン: 2026-09-29 の更新から

拡張機能ライブラリで「更新」(Update) を押すと、GP247 はファイルを置き換えるとともに、新しいバージョンに必要なデータ更新（新しい設定の追加、古いデータの変換など）も実行します。プラグイン／テンプレートのファイルを別の方法（git pull、Composer、FTP、フォルダのコピー）で置き換えた場合は、ファイルだけが変わり、データの部分はまだ実行されていません。

GP247 は拡張機能ごとにインストール済みのバージョンを記録しています。そのため、このケースを検出でき、足りない部分を適用する方法を 3 つ用意しています（どれか 1 つを選びます）。

いつもどおり php artisan gp247:update を実行します。このコマンドには、すべてのプラグインとテンプレートに適用する手順が含まれています。

拡張機能の部分だけを実行します。

php artisan gp247:ext-update --local --all --type=plugin --dry-run   # プレビューのみ（まだ何もしない）
php artisan gp247:ext-update --local --all --type=plugin             # すべてのプラグインに適用
php artisan gp247:ext-update --local --type=plugin --key=InOut       # または 1 つのプラグインだけ

コマンドラインが使えない場合（共有ホスティング）: 管理画面の「プラグイン」（または「テンプレート管理」）を開きます。適用待ちの拡張機能には、「バージョン」列に黄色のラベル 「データ更新待ち: x → y」 が表示されます。「操作」列の 「データ更新を適用」 ボタン（データベースのアイコン）を押します。

注意点:

何度実行しても安全です。適用済みの拡張機能はスキップされます。
2026-09-29 より前にインストールしたサイトには、バージョンの記録がありません。そのため初回は、インストール済みのプラグイン／テンプレートがすべて「待ち」と表示されます。一度適用すれば解消します。
ある拡張機能のデータ更新がエラーになっても、新しいファイルはそのまま残ります（ライブラリからの更新のように自動では元に戻りません）。原因を直してから再実行してください。完了するまで、gp247:doctor は extension_data_pending の項目を報告します。

条件と制約（操作の前に確認）

通常のアップデート（gp247:update）を実行するとき

稼働中のサイトでも安全 — このコマンドはアップグレードだけを行い、データを壊す再インストール（re-install）の手順は一切実行しません。そのため本番サイトでもそのまま使えます。
制限のあるホスティングでも実行可能 — cron、キューワーカー、websocket は必要ありません。 php artisan コマンドを実行できれば、サイトを完全にアップデートできます。
shop の手順は shop がインストール済みの場合のみ — shop モジュールがインストールされていないサイトでは、shop のアップグレードを自動でスキップし、エラーも出しません。

--overwrite-lang を使うとき

自分で修正した翻訳がパッケージの既定値で上書きされます — このため、このオプションは既定で有効になっていません。意図的にリセットしたいときだけ有効にしてください。

--publish=<tokens> を使うとき

安全なのは core-public だけです — これはビルド済みの管理画面 CSS/JS で、上書きしてもカスタマイズは失われません。
それ以外のトークンはすべてデータを破壊します — view／テンプレートを上書きするため、その場で修正した画面デザインのカスタマイズが消えます。先に対象フォルダをバックアップしてください。
--force フラグはありません — データを破壊するトークンを自分で入力したこと自体が同意とみなされます。対話型のターミナルで実行した場合は、誤操作を防ぐため、コマンドが警告して確認を求めます（既定は「いいえ」）。
トークンを打ち間違えると、何もせずにすぐ停止します — 無効なトークンを入力した場合、コマンドはアップデートを始める前にエラーを表示して終了します。サイトには一切影響しません。

よくある質問（Q&A）

Q1: composer update だけ実行すればよいですか？gp247:update は必要ですか？

→ 両方の実行が必須です。composer update は新しいコードを vendor/ にダウンロードするだけです。変更（DB の更新、キャッシュの再作成）を実際にサイトに適用するのは gp247:update です。

Q2: gp247:core-update、gp247:shop-update などをパッケージごとに覚える必要がありますか？

→ いいえ。標準コマンド gp247:update を使ってください。パッケージ別のコマンドを正しい順番で自動的に呼び出し、shop の部分はサイトに shop がインストールされている場合だけ実行します。

Q3: gp247:update を実行すると、データやカスタマイズは失われますか？

→ いいえ。既定では安全なアップグレードだけを行います。データはそのまま、自分で修正した翻訳もそのまま、公開済みの view／テンプレートにも触れません。上書きが起きるのは、--overwrite-lang または --publish（core-public 以外のトークン）を自分で追加したときだけです。

Q4: cron やキューのない共有ホスティングでもアップデートできますか？

→ できます。gp247:update には cron、キューワーカー、websocket は必要ありません。 php artisan を実行できれば十分です。

Q5: アップデート後、管理画面の CSS/JS がおかしくなったらどうすればよいですか？

→ ビルド済みの管理画面アセットを更新します（安全で、カスタマイズは失われません）。 php artisan gp247:update --publish=core-public。

Q6: --publish=all と --publish=core-public の違いは何ですか？

→ core-public は管理画面の CSS/JS だけを更新します（安全）。all は view／テンプレートを含めて すべてを更新するため、画面デザインのカスタマイズが上書きされます。all を使う前にバックアップを取ってください。

Q7: アップデートが成功したかどうかは、どうやって確認しますか？

→ php artisan gp247:info を実行し、アップデート前のバージョン番号と比べます。新しいバージョンになっていて、サイトが正常に動いていれば完了です。

Q8: アップデートの途中でエラーが出た場合、問題はありますか？

→ gp247:update は手順ごとに実行し、1 つの手順でエラーが出るとそこで止まります。そのため、サイトが中途半端な状態になることは通常ありません。エラーメッセージを読んで対処するか、バックアップから復元してから再度試してください。

Q9: アップデートのたびに gp247:doctor を実行する必要がありますか？

→ 必須ではありません。ただし、環境の問題を早めに見つけるため、アップデート前の実行をおすすめします（特にサーバーや PHP のバージョンを変えた直後）。アップデート後は、extension_data_pending の項目で、データ更新待ちのプラグイン／テンプレートがわかります（C 項を参照）。

Q10: GP247 のすべてのコマンドとオプションは、どこで確認できますか？

→ コマンドラインリファレンスを参照してください。GP247 のすべての artisan コマンドを、オプションと使用例付きで一覧にしています。

変更履歴

日付	GP247 バージョン	変更内容
2026-09-29		`gp247:update` に、`git pull`／Composer／手動コピーで更新されたプラグイン／テンプレートのデータ更新を適用する手順を追加しました（GP247 がインストール済みのバージョンを記録）。`gp247:ext-update --local` コマンドと、管理画面の「データ更新を適用」ボタンを追加しました（C 項）。
2026-08-29	gp247/core 2.2	`gp247:update` が core のアップグレード用マイグレーションも実行するようになりました（`gp247:core-update` 経由）。以前は再シードだけでした。公開版 v2.1 からのルールを明記しました。互換性を壊す変更にはすべて自動のデータ変換が付くため、`composer update` + `gp247:update` だけで手順全体が完了します。

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