README

运行命令的 Kirby 插件。

• 这是一个面板按钮！
• 它内置了清理缓存、会话、创建 zip 备份、预生成缩略图、打开 URL、刷新当前面板页面等命令。
• 您可以定义自己的命令（调用 API 钩子、玩游戏、黑入服务器等）
• 它可以在您的前端代码、官方 kirby CLI 和 CRON 中触发。

安装

您必须使用 composer 将插件和 CLI 本地安装到您的项目中

composer require getkirby/cli bnomei/kirby3-janitor

警告

您需要使用 composer 在项目中安装 CLI，而不是使用全局版本。由于 Janitor 依赖于 CLI 可用，因此不支持通过子模块或 ZIP 安装仅安装 janitor 插件。

商业使用

支持开源！

此插件是免费的，但如果您将其用于商业项目，请考虑赞助我或进行捐赠。
如果我的工作帮助您赚了一些钱，那么我觉得我也应该得到一点回报，对吧？

友善一点。分享一点。谢谢。

－ Bruno
 

设置

CLI 命令

在任何蓝图创建一个带有您的命令的 janitor 字段，浏览到该页面并在面板中按按钮。

site/blueprints/page/default.yml

title: Default Page
fields:
  call_my_command:
    type: janitor
    command: 'example --data test'
    label: Call `Example` Command

Janitor 将自动填写当前模型。

• –model 参数将具有当前模型的 UUID 或 ID。您可以使用 janitor()->model($cli->arg('model')) 来获取对象。
• 但如果您在页面上按面板按钮，则 –page 参数将设置为该页面的 UUID 或 ID。使用 $cli->kirby()->page($cli->arg('page')) 来获取对象。
• 如果您在文件视图中调用它，则 –file 参数将设置。使用 $cli->kirby()->file($cli->arg('file')) 来获取对象。
• 在面板用户视图中... --user。使用 $cli->kirby()->user($cli->arg('user')) 来获取对象。
• 最后，当您在 site/blueprints/site.yml 蓝图中具有按钮时，自动设置 --site（布尔值）。if($cli->arg('site')) { $cli->kirby()->site(); }

通过自定义插件 创建 Kirby CLI 命令 或将它们放入 site/commands。

site/commands/example.php

<?php

use Bnomei\Janitor;
use Kirby\CLI\CLI;

return [
    'description' => 'Example',
    'args' => [] + Janitor::ARGS, // page, file, user, site, data, model
    'command' => static function (CLI $cli): void {
        $page = page($cli->arg('page'));

        // output for the command line
        $cli->success(
            $page->title() . ' ' . $cli->arg('data')
        );

        // output for janitor
        janitor()->data($cli->arg('command'), [
            'status' => 200,
            'message' => $page->title() . ' ' . $cli->arg('data'),
        ]);
    }
];

回调

您还可以在自定义插件选项或任何配置文件中创建回调，而不是使用命令。

site/config/config.php

<?php

return [
    'example' => function ($model, $data = null) {
        return [
            'status' => 200,
            'message' => $model->title() . ' ' . $data,
        ];
    },
    // ... other options
];

Janitor 插件有一个特殊的命令 janitor:job，您可以使用它来触发您的回调。

site/blueprints/page/default.yml

title: Default Page
fields:
  call_my_command:
    type: janitor
    command: 'janitor:job --key example --data test'
    label: Call `Example` Command

$model 将匹配您按按钮的页面、文件、用户或站点对象的模型。

注意

为什么只使用一个模型变量而不是为页面、文件、用户和站点分别使用一个变量？一方面是为了能够直接与您可能已经创建的任何现有版本2回调一起工作，另一方面是因为这样非常容易获取触发回调的模型。

内置命令和示例

此插件包含一些您可能希望使用的命令，以及一些用于展示按钮各种选项（例如如何更改图标或在新标签页中打开URL）的示例命令。一些命令可以在面板和终端中使用，而其他命令的使用则限于其中一个。在终端中，您可以使用--help参数查看每个命令的帮助信息。

• janitor:backupzip，创建备份压缩文件
• janitor:call，调用当前模型上的方法，可选的数据参数
• janitor:cleancontent，从内容文件中删除您在蓝图上未定义的字段
• janitor:clipboard，将定义的值复制到您的剪贴板
• janitor:download，触发下载URL
• janitor:flush，通过提供名称来刷新缓存（默认：页面缓存）
• janitor:job，运行回调
• janitor:maintenance，切换维护模式
• janitor:open，在面板中触发打开URL
• janitor:out，向CLI输出流发送消息
• janitor:pipe，将输入参数映射到输出参数
• janitor:render，渲染特定页面或所有页面（创建缩略图作业）
• janitor:thumbs，处理特定页面或所有页面的缩略图作业
• janitor:tinker，在终端中运行REPL会话
• janitor:trash，通过键或页面（默认：页面缓存）从给定缓存中删除条目
• janitor:undertaker，将页面及其子页面备份到zip文件。您需要手动通过钩子触发它。

插件将自动注册以janitor:*开头的这些命令 - 无需复制。
但如果您想重新使用提供的其他任何示例，则需要将它们复制到您的site/commands文件夹中。

蓝图字段选项

您在蓝图中使用field: janitor创建的按钮可以配置为执行各种操作。查看示例default.yml蓝图以熟悉如何使用它。

• autosave，如果为true，则在按按钮之前保存
• backgroundColor，设置按钮的背景颜色
• color，设置按钮的文本颜色
• confirm，设置在单击按钮并执行命令之前确认的文本，可以防止用户在操作系统对话框中单击取消时执行命令
• command，与您在终端中输入的命令类似，支持查询语言和页面/文件/用户/站点/数据参数
• cooldown，消息在按钮上闪烁的时间（毫秒，默认：2000）
• error，设置在所有非200状态返回时显示的消息，支持查询语言
• help，设置按钮的帮助信息
• icon，设置按钮的图标
• intab，如果为true，则与open选项一起使用，在新标签页中打开URL
• label，设置按钮的标签
• progress，设置在按钮等待响应时显示的消息，支持查询语言
• success，设置在所有200状态返回时显示的消息，支持查询语言
• unsaved，如果为false，则当面板视图有未保存内容时禁用按钮

Janitor API选项

在命令或回调中，您将通过其API设置/返回数据到Janitor按钮。根据您返回的内容，可以在面板中触发各种操作。

• backgroundColor，请参阅backgroundColor字段选项
• clipboard，要复制到剪贴板的字符串
• color，请参阅color字段选项
• download，开始下载的URL
• error，请参阅error字段选项
• help，请参阅help字段选项
• icon，请参阅icon字段选项
• label，请参阅label字段选项
• message，请参阅message字段选项
• open，要打开的URL，与intab字段选项一起使用可在新标签页中打开
• reload，如果为true，则在收到API调用后重新加载面板视图
• success，请参阅success字段选项
• status，返回200用于绿色按钮闪烁，其他任何内容用于红色闪烁

示例

再次...查看内置命令和插件示例命令，以了解如何自行使用字段和API选项。

test_ping:
  type: janitor
  command: 'ping' # see tests/site/commands/ping.php
  label: Ping
  progress: ....
  success: Pong
  error: BAMM

janitor_open:
  type: janitor
  command: 'janitor:open --data {{ user.panel.url }}'
  intab: true
  label: Open current user URL in new tab
  icon: open
  # the open command will forward the `data` arg to `open` and open that URL

janitor_clipboarddata:
  type: janitor
  command: 'janitor:clipboard --data {{ page.title }}'
  label: 'Copy "{{ page.title }}" to Clipboard'
  progress: Copied!
  icon: copy
  # the clipboard command will forward the `data` arg to `clipboard` and copy that

janitor_download:
  type: janitor
  command: 'janitor:download --data {{ site.index.files.first.url }}'
  label: Download File Example
  icon: download
  # the download command will forward the `data` arg to `download` and start downloading that

janitor_backupzip:
  type: janitor
  command: 'janitor:backupzip'
  cooldown: 5000
  label: Generate Backup ZIP
  icon: archive

janitor_render:
  type: janitor
  command: 'janitor:render'
  label: Render pages to create missing thumb jobs

janitor_thumbssite:
  type: janitor
  command: 'janitor:thumbs --site'
  label: Generate thumbs from existing thumb jobs (full site)

janitor_callWithData:
  label: Call method on model with Data
  type: janitor
  command: 'janitor:call --method repeatAfterMe --data {{ user.id }}'

如果您想的话，也可以调用CLI附带的任何核心命令，例如clear:cache。

请注意，Janitor面板按钮和webhooks将自动将--quiet选项附加到所有命令中，以静音输出到不存在的CLI。但如果您使用janitor()->command()，则必须自行将--quiet附加到您的命令中。

在您的代码中运行命令

您也可以在模型、模板、控制器或钩子等自己的代码中运行任何命令。由于命令不会直接返回数据，您需要使用辅助函数janitor()->data($commandName)检索为Janitor存储的数据。

获取命令返回的数据

Kirby\CLI\CLI::command('whistle'); // tests/site/commands/whistle.php
var_dump(janitor()->data('whistle'));

创建并下载备份

site/config/config.php

<?php

return [
    // ATTENTION: choose a different secret!
    'bnomei.janitor.secret' => 'e9fe51f94eadabf54',

    'routes' => [
        // custom webhook endpoint reusing janitors secret
        [
            'pattern' => 'webhook/(:any)/(:any)',
            'action' => function($secret, $command) {
                if ($secret != janitor()->option('secret')) {
                    \Kirby\Http\Header::status(401);
                    die();
                }

                if ($command === 'backup') {
                    janitor()->command('janitor:backupzip --quiet');
                    $backup = janitor()->data('janitor:backupzip')['path'];
                    if (F::exists($backup)) {
                        \Kirby\Http\Header::download([
                            'mime' => F::mime($backup),
                            'name' => F::filename($backup),
                        ]);
                        readfile($backup);
                        die(); // needed to make content type work
                    }
                }
            }
        ],
    ],
];

使用参数调用命令

向核心CLI函数提供参数可能有些棘手，因为您需要分离参数键和参数值。对于单个参数来说似乎很简单，但对于动态参数列表以及如果值包含空格字符或引号来说，可能会有些繁琐。但别担心——Janitor也有相应的助手。

Kirby\CLI\CLI::command('uuid', '--page', 'some/page'); // tests/site/commands/uuid.php

janitor()->command('uuid --page some/page');

var_dump(janitor()->data('uuid')['message']); // page://82h2nkal12ls

请记住，使用janitor()->command($string)助手，您可以调用自己的命令以及核心命令，而不仅仅是Janitor定义的命令。

如果您想自行处理命令字符串，可以使用以下静态助手方法。

list($name, $args) = Bnomei\Janitor::parseCommand('uuid --page page://82h2nkal12ls');
Kirby\CLI\CLI::command($name, ...$args);

带秘密的webhook

您不能未经认证地调用Janitor的API。您要么需要使用面板按钮，要么可以在您的site/config/config.php文件中设置一个secret，并使用该秘密调用Janitor API URL。

site/config/config.php

<?php

return [
  'bnomei.janitor.secret' => 'e9fe51f94eadabf54', // whatever string you like
  //... other options
];

如果您想将秘密存储在.env文件中并由我的dotenv插件加载，您也可以使用回调。

/.env

# whatever key and value you like
MY_JANITOR_SECRET=e9fe51f94eadabf54

site/config/config.php

<?php

return [
  'bnomei.janitor.secret' => fn() => env('MY_JANITOR_SECRET'),
  //... other options
];

示例URL

https://dev.bnomei.com/plugin-janitor/e9fe51f94eadabf54/janitor%3Abackupzip

带urlencoded参数的示例URL

http://dev.bnomei.com/plugin-janitor/e9fe51f94eadabf54/janitor%3Athumbs%20--site

CRON

使用wget或curl的webhook

您也可以使用秘密来使用wget或curl触发一个作业。

wget https://dev.bnomei.com/plugin-janitor/e9fe51f94eadabf54/janitor%3Abackupzip --delete-after
// or
curl -s https://dev.bnomei.com/plugin-janitor/e9fe51f94eadabf54/janitor%3Abackupzip > /dev/null

您是否有关于PHP bin和cron的问题？阅读这篇文章。

Kirby CLI（通过composer安装）

在您的cron调度程序中添加以下命令

cd /path/to/my/kirby/project/root && vendor/bin/kirby janitor:backupzip

维护模式

您可以使用这样的清洁工按钮切换维护模式

  janitor_maintenance:
    type: janitor
    command: 'janitor:maintenance --user {{ user.uuid }}'
    cooldown: 5000
    label: 'Maintenance: {{ site.isUnderMaintenance.ecco("DOWN","UP") }}'
    icon: '{{ site.isUnderMaintenance.ecco("cancel","circle") }}'

如果您需要在强制维护模式下添加自定义检查，可以通过为bnomei.janitor.maintenance.check选项提供一个回调函数来实现。

site/config/config.php

<?php

return [
    // return `true` for maintenance and `false` to skip maintenance
    'bnomei.janitor.maintenance.check' => function(): bool {
        // example: block unless it is a logged-in user and it has the admin role
        return kirby()->users()->current()?->role()->isAdmin() !== true;
    },
    // other options...
];

如果您创建了自定义的维护片段并将其存储为site/snippets/maintenance.php，您还可以覆盖维护片段。

依赖项

• Kirby CLI
• CLImate
• Symfony Finder

免责声明

此插件“按原样”提供，不提供任何保证。请自行承担风险使用，并在将其用于生产环境之前自行测试。如果您发现任何问题，请创建新问题。

许可证

MIT

不建议在任何推广种族主义、性别歧视、恐同、动物虐待、暴力或其他任何形式仇恨言论的项目中使用此插件。