bnomei/kirby3-janitor

Kirby 插件,用于在面板、PHP 代码或 cronjob 中运行命令,如清理缓存


README

Release Downloads Coverage Maintainability Discord

运行命令的 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,您还可以覆盖维护片段。

依赖项

免责声明

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

许可证

MIT

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