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

ScheduledTasks — GP247 / S-Cart 向けスケジュールタスク管理

はじめに

ScheduledTasks は、Laravel Scheduler がサイト上で実行するすべてのスケジュールタスクをサイトオーナーが確認・操作できるようにする無料プラグインです。対象は GP247 コアのタスク（例：キューに入ったメールの送信）、各プラグインのタスク、開発者が書いたサイト独自コードのタスクです。 このドキュメントは、サイトオーナー / 運用担当者（インストール、スケジューラーの有効化、タスクの操作）と開発者（新しいタスクの追加方法）を対象としています。 読み終えると、ご自身の環境でスケジューラーを動かす方法、プラグインが管理者の設定をどのように適用するか、そしてプラグインが自由なコマンド追加を許可せずコードに既にあるタスクだけを操作する理由がわかります。

重要： セキュリティ上の理由から、画面では新しいコンソールコマンドを追加できません。コマンド名や引数を入力することもできません。プラグイン はコードでスケジュール済みのタスクだけを操作します。詳しくは 画面からコマンドを追加できない理由 をご覧ください。

機能

すべてのタスクは多重実行が防止されます。プラグインを無効化またはアンインストールすると、すべてのタスクはコードに書かれたとおりに実行されます。

インストール

1. ScheduledTasks フォルダーをサイトの app/GP247/Plugins/ にコピーします（または管理画面 →「プラグイン」で ZIP ファイルをアップロードします）。

2. 管理画面 →「プラグイン」で Scheduled Tasks を探し、「インストール」をクリックします。

   成功すると、「システム」メニューに「スケジュールタスク」が追加されます。

3. 「システム → スケジュールタスク」を開きます。

   初めて開くと、サイトのスケジュールに現在あるタスクの一覧が表示されます。黄色の枠「このサイトではスケジューラーが一度も実行されていません」が表示された場合は、 スケジューラーを有効にする に進んでください。

要件： GP247 core ≥ 3.0 と Livewire（GP247 の管理画面に同梱）。

スケジューラーを有効にする

スケジューラー（Laravel Scheduler）は、毎分どのタスクが実行時刻を迎えたかを確認するアプリケーションの一部です。スケジューラーは自動では動きません。毎分 php artisan schedule:run を呼び出す仕組みが必要です。 これがないとタスクは一つも実行されず、画面上の設定もすべて効果がありません。ご自身の環境に合った方法を一つ選んでください。

ホスティングで cron を追加する方法（cPanel など）

1. ホスティングの管理パネルにログインし、「Cron Jobs」（「スケジュールタスク」/「Scheduled Tasks」という名前の場合もあります）を開きます。

2. 頻度で「毎分」（Once Per Minute / * * * * *）を選びます。

3. コマンド欄に次の行を貼り付けます。/path/to/site はご自身のサイトのフォルダーに置き換えてください。スケジュールタスク画面にはサイトの正しいパスを入れたこの行が 表示されているので、そこからコピーすることもできます。

   cd /path/to/site && php artisan schedule:run >> /dev/null 2>&1
   

4. 保存し、1〜2分待ってから「スケジュールタスク」画面を再読み込みします。

   成功すると、黄色 / 赤の枠が消え、緑色の行「スケジューラーは稼働中です — 最終実行 …」に変わります。何回か実行されると、 この行に「約 N 分ごと · ホスト: …」も表示されます。

画面からコマンドを追加できない理由

画面で操作できるのは、コードのスケジュールに既にあるタスクだけです（スケジュールの変更、オン / オフ、今すぐ実行）。新しいタスクの追加はできません。 コマンド名や引数の入力欄はなく、php artisan list の一覧から選ぶこともできません。理由は次のとおりです。

• コンソールコマンドはアプリケーションの全権限で実行されます。 GP247 サイトのコマンド一覧には、データをすべて消去するコマンド （db:wipe、migrate:fresh）、プラグイン / テンプレートを削除するコマンド（gp247:ext-uninstall）、暗号化キーを変更して保存済みのすべての API キーを使えなくするコマンド （key:generate）、サイトをメンテナンスモードにするコマンド（down）、スケジューラーを停止させてしまうコマンド（tinker）が含まれています。Web 上でコマンドを選択・入力できるようにすると、管理者アカウントを一つでも 乗っ取った人がこれらのコマンドを実行できてしまいます。真夜中に自動実行するようスケジュールすることさえ可能です。
• 引数もコマンド名と同じくらい危険です。 無害に見えるコマンドでも、--force、--execute、--database=… で動作がまったく変わります。
• コマンド一覧は自動で変わります。 プラグインやパッケージをインストールするたびに変わり、誰も確認しません。「禁止コマンド」の一覧は常に古くなってしまいます。
• 何を実行するかを決めるのはコードだけです。 コード内のタスクは開発者が書き、テストし、アプリケーションと一緒にデプロイします。 管理者が調整するのは、いつ実行するかと実行するかどうかだけです。

「今すぐ実行」もブラウザ内でコマンドを実行するわけではありません。スケジューラーの次回実行時に実行するよう印を付けるだけです。「今すぐ実行」用の追加の引数 （必要な場合）は、サイトの設定ファイル（run_now_args）でのみ宣言でき、ブラウザから受け取ることはありません。

スケジュールタスクの追加方法（開発者向け）

タスクの追加は開発者がコードで行う作業です。デプロイ後、タスクはスケジューラーの次回実行時に自動的に画面に表示されます （「新規検出」ラベル + 通知ベル）。以降は、管理者が他のタスクと同じように操作します。

サイト独自のコード — ファイル routes/console.php

<?php
use Illuminate\Support\Facades\Schedule;

// 1) artisan コマンド（推奨）
Schedule::command('report:send --daily')->dailyAt('07:00');

// 2) キューに入れるジョブ — ジョブのクラス名で識別
Schedule::job(new \App\Jobs\SyncStock)->everyFifteenMinutes();

// 3) クロージャ — 名前を付けることが必須。付けないと操作できません
Schedule::call(fn () => \App\Support\Cleanup::run())
    ->name('cleanup-temp-files')
    ->hourly();

GP247 プラグイン — ファイル Provider.php の、プラグインが有効かを確認するブロック内

if (gp247_extension_check_active($config['configGroup'], $config['configKey'])) {
    // ...
    $this->callAfterResolving(\Illuminate\Console\Scheduling\Schedule::class, function ($schedule) {
        $schedule->command('myplugin:sync')->everyThirtyMinutes();
    });
}

「プラグインが有効」のブロック内に置くことで、プラグインを無効にするとタスクもスケジュールから消えます。

識別のルール — 書く前に知っておくこと

プラグインはタスクをその識別子で認識します。管理者の設定（独自スケジュール、オン / オフ）はすべてその識別子に紐付きます。

• 引数を変える = 新しいタスク。 report:send --daily を report:send --day に変えると別のタスクになります。旧タスクは「コードに存在しません」 と表示され（履歴は保持）、新タスクはコードのスケジュールで実行されます。旧タスクの管理者設定は引き継がれません。
• コードのスケジュールを変えても識別子は変わりません。 管理者が独自スケジュールを設定している場合、画面に「コードのスケジュールが変更されました: X → Y」と表示されます。
• 同じ識別子が2回宣言された場合は、宣言順に #2、#3 のサフィックスが付きます。
• ->name() のないクロージャは件数だけを数え、「識別できない」と警告します。

すべきこと・すべきでないこと

• すべきこと： 定期的な処理はすべて、ホスティング独自の crontab ではなく Laravel Schedule に入れてください。スケジュール外のスクリプト（bash、curl など）は アプリケーションから見えません。
• 不要なこと： withoutOverlapping() を自分で追加する必要はありません。プラグインがすべてのタスクの多重実行を防止します。withoutOverlapping(n) を設定した場合は、 ご自身のロック期限 n がそのまま使われます。
• runInBackground()、onOneServer()、timezone()、environments() は Laravel と同様に動作します。画面は「次回」を タスク自身のタイムゾーンで計算します。
• 「今すぐ実行」時に専用の引数が必要なコマンド（例：自前の時間帯チェックをスキップする --force）は、サイトの run_now_args で宣言します （カスタマイズ を参照）。

動作の仕組み

スケジューラーの各実行

schedule:run の各実行（毎分）で、Laravel が実行時刻を迎えたタスクを選ぶ前に、プラグインは次のことを行います。

1. スケジューラーのハートビート（時刻、実行ホスト）を記録します。
2. スケジュール内のタスク一覧を読み取り、新しいタスクを追加し、既存のタスクを更新します。
3. 管理者の設定を各タスクに適用し（下表）、その後は通常どおり Laravel に実行させます。

プラグインはどのタスクのコードも変更しません。その実行回のスケジュール、実行条件、多重実行防止のロックを調整するだけです。

管理者の設定の適用方法

すべての変更は管理画面のログに記録されます：誰が、いつ、IP、タスク、旧 → 新の値。

実行回のステータス

スケジュール外で実行されたコマンド

手動で、または独自の crontab から実行された artisan コマンドは、次のいずれか一つのグループに該当する場合に「スケジュール外」タブ（閲覧のみ）に記録されます。

• GP247、プラグイン、またはサイト独自コードのコマンド（routes/console.php に書かれたコマンドを含む）
• スケジュールに登録されているコマンド（他パッケージのコマンドを含む）— 手動実行はそのタスクにまとめられます
• サイト設定の external_commands リストに一致するコマンド

スケジューラー自身が起動したプロセスは重複して記録されません。その他のフレームワーク / パッケージのコマンド（例：migrate、optimize:clear） や、artisan コマンドではないスクリプトは記録されません。

スケジューラーの稼働状況

プラグインは crontab やプロセス一覧を読み取りません。schedule:run が実行された各回を認識し、データベースに保存します （キャッシュを削除しても失われません）。画面は実行回の間隔（「約 N 分ごと」）を測定し、実行中のホストを一覧表示します。 php artisan schedule:pause で一時停止されたスケジュールは別途表示されます。

問題が発生したとき

• 設定を読み取れない（データベースのエラー、テーブルがない）、または履歴の書き込みに失敗した場合 → すべてのタスクはコードに書かれたとおりに実行され、 エラーはログに記録されます。プラグインがスケジュールを止めることは決してありません。
• プラグインを無効化またはアンインストールした場合 → 操作レイヤーがなくなり、すべてのタスクはコードに書かれたとおりに実行されます。

権限

これはサイト全体の設定です。各ストア（マルチストア）の管理者はアクセスできません。

カスタマイズ

プラグインの config.php は編集しないでください。このファイルはプラグインを更新するたびに上書きされます。代わりに次のようにします。

1. サイトのルートフォルダー（config/app.php の隣）に config/scheduled-tasks.php ファイルを作成します。

2. 変更したいキーだけを書きます。例：

   <?php
   return [
       'retention_days' => 30,              // 実行履歴の保持日数（デフォルト 90）
       'scheduler_stale_minutes' => 5,      // スケジューラーが停止したとみなすまでの最小しきい値（分）（デフォルト 3）
       'record_external' => true,           // スケジュール外で実行されたコマンドを記録（デフォルトはオン）
       'external_commands' => ['backup:*'], // スケジュール外で実行されたときに追跡するパッケージのコマンドを追加
       'run_now_args' => [                  // 「今すぐ実行」時の追加の引数（タスクの識別子ごと）
           'report:send --daily' => '--force',
       ],
   ];
   

3. サイトで設定キャッシュを有効にしている場合は、新しい値を読み込むために php artisan config:cache を再実行します。

履歴を手動で削除する場合：php artisan scheduled-tasks:purge-runs は削除対象の行数を数えるだけです。--execute を付けると実際に削除します。

アンインストール

プラグインをアンインストールすると、プラグインの3つのテーブル（実行履歴、スケジューラーのハートビート、設定済みのスケジュール / オン・オフ）が削除され、すべてのタスクはコードの スケジュールに戻ります。タスクのコードには影響しません。

ライセンス

MIT — 無料。

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

スケジュールを変更するとき

• cron はちょうど5フィールドである必要があります（分 時 日 月 曜日）。構文が誤っているとエラーを表示し、旧スケジュールを維持します。タスクが 「スケジュールなし」の状態になることを防ぐためです。
• コードのスケジュールと同じスケジュールを保存 = 戻すことになります。独自スケジュールは作成されないので、後で開発者がコードのスケジュールを変更すれば、タスクもそれに従います。
• 1分未満のタスクはスケジュールを変更できません。 cron 式の最小単位は毎分であり、「10秒ごと」は表現できないためです。
• コードのスケジュールより頻繁なスケジュールも保存できますが、警告が表示されます。 重いタスクを頻繁に実行しすぎると、ホスティングが過負荷になるおそれがあります。

オン / オフ、今すぐ実行のとき

• コードのスケジュールに残っているタスクだけが操作できます。 「コードに存在しません」のタスクとスケジュール外で実行されたコマンドは閲覧のみです。 操作すべきスケジュールがもうない（または最初からない）ためです。
• スケジューラーが稼働していないとき、「今すぐ実行」はロックされます。 印が処理されることはないので、実行されたと誤解しないようロックしています。
• 実行待ちの間は再度押せません。 各タスクの実行待ちの印は一つだけです。実行が終わると新しい印を受け付けます。
• 前回の実行が終わっていなければ、新しい実行は待機します。 同じタスクの2つの実行が重なることを防ぎます。

キューを扱うとき

• 一覧にある失敗したジョブだけを再試行できます。 また、削除機能はありません。ジョブの削除は元に戻せない操作だからです。
• 待機中のジョブ数を数えられるのは database ドライバーのときだけです。 sync の場合、画面は 0 を表示する代わりに、サイトがキューを使用していないことをはっきり示します。

権限と範囲について

• 書き込みの操作にはすべて「設定」権限（または administrator ロール）が必要です。閲覧権限だけのユーザーにはボタンが表示されず、無理に 呼び出しても拒否されます。
• 各ストア（マルチストア）の管理者はアクセスできません。 スケジュールはサイト全体のものであり、特定のストアに属するものではないためです。

よくある質問（Q&A）

Q1: プラグインをインストールしたのに、画面に「スケジューラーが一度も実行されていません」と表示されるのはなぜですか？

→ プラグインは自分でスケジューラーを動かしません。サイトには毎分 schedule:run を呼び出す cron（または supervisor / Docker）が必要です。 スケジューラーを有効にする の手順に従い、1〜2分待ってからページを再読み込みしてください。

Q2: 毎日実行する新しいコマンドを画面から追加できますか？

→ できません。セキュリティのための意図的な仕様です（画面からコマンドを追加できない理由 を参照）。開発者にタスクを コードで宣言してもらってください。デプロイ後、タスクは自動的に画面に表示され、操作できるようになります。

Q3: スケジュールを変更しました。いつから有効になりますか？

→ スケジューラーの次回実行から、通常は1分以内に有効になります。何かを再起動する必要はありません。

Q4: 「今すぐ実行」を押したのにタスクが実行されません。

→ スケジューラーの稼働状況の行を確認してください。スケジューラーが動いていなければ、印は処理されません。タスクの前回の実行がまだ続いている場合は、 新しい実行は前回が終わるまで待機します。結果はタスクの履歴タブで確認できます。

Q5: タスクをオフにすると、実行中の回は止まりますか？

→ 止まりません。オフは以降の実行を止めるだけで、実行中の回は終わるまで実行されます。

Q6: 開発者がコードのスケジュールを変更しましたが、私は独自スケジュールを設定していました。どうなりますか？

→ あなたの独自スケジュールが引き続き使われ、画面に「コードのスケジュールが変更されました: X → Y」と表示されます。コードに従いたい場合は「コードのスケジュールに戻す」をクリックしてください。

Q7: 手動で実行したばかりのコマンドが「スケジュール外」タブに表示されないのはなぜですか？

→ 記録されるのは、GP247 / プラグイン / 独自コードのコマンド、スケジュールにあるコマンド、external_commands に一致するコマンドだけです。他のパッケージのコマンドを追跡したい場合は、 config/scheduled-tasks.php の external_commands にコマンド名のパターンを追加してください。

Q8: ホスティングの cron が5分ごとです。画面にずっとエラーが表示されますか？

→ 表示されません。プラグインは実際の周期を測定し、max(3分, 2 × 周期) を超えた場合にだけ「実行されていない」と表示します。5分ごとの cron なら、新しい実行がないまま10分経過したときです。

Q9: キャッシュを削除（php artisan cache:clear）すると、スケジューラーの状態は失われますか？

→ 失われません。スケジューラーのハートビートはキャッシュではなく、プラグインのデータベースに保存されています。

Q10: プラグインをアンインストールすると、サイトのタスクはなくなりますか？

→ なくなりません。タスクはコードにあるので、コードのスケジュールどおりに通常どおり実行されます。削除されるのは、実行履歴と画面で設定した 内容だけです。

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