bnomei / kirby3-janitor
Kirby 插件,用于在面板、PHP 代码或 cronjob 中运行命令,如清理缓存
Requires
- php: >=8.2
- getkirby/composer-installer: ^1.2
- symfony/deprecation-contracts: ^3.0.1
- symfony/finder: ^7.0
Requires (Dev)
- getkirby/cli: dev-develop
- getkirby/cms: ^4.3.0
- larastan/larastan: ^2.9
- laravel/pint: ^1.13
- pestphp/pest: ^2.24
- pestphp/pest-plugin-type-coverage: ^2.4
- spatie/ray: ^1.39
- dev-master
- 4.4.2
- 4.4.1
- 4.4.0
- 4.3.1
- 4.3.0
- 4.2.0
- 4.1.0
- 4.0.2
- 4.0.1
- 4.0.0
- 3.12.0
- 3.11.0
- 3.10.1
- 3.10.0
- 3.9.2
- 3.9.1
- 3.9.0
- 3.8.0
- 3.7.0
- 3.6.0
- 3.5.4
- 3.5.3
- 3.5.2
- 3.5.1
- 3.5.0
- 3.4.5
- 3.4.3
- 3.4.2
- 3.4.1
- 3.4.0
- 3.3.0
- 3.2.2
- 3.2.1
- 3.2.0
- 3.1.0
- 3.0.2
- 3.0.1
- 3.0.0
- 2.16.3
- 2.16.2
- 2.16.1
- 2.16.0
- 2.15.1
- 2.15.0
- 2.14.0
- 2.13.0
- 2.12.0
- 2.11.0
- 2.10.1
- 2.10.0
- 2.9.0
- 2.8.0
- 2.6.9
- 2.6.8
- 2.6.6
- 2.6.5
- 2.6.4
- 2.6.3
- 2.6.2
- 2.6.1
- 2.6.0
- 2.5.3
- 2.5.2
- 2.5.1
- 2.5.0
- 2.4.8
- 2.4.7
- 2.4.6
- 2.4.5
- 2.4.4
- 2.4.3
- 2.4.1
- 2.4.0
- 2.3.7
- 2.3.6
- 2.3.5
- 2.3.4
- 2.3.3
- 2.3.2
- 2.3.1
- 2.3.0
- 2.2.9
- 2.2.7
- 2.2.6
- 2.2.5
- 2.2.4
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.0
- 2.0.2
- 2.0.1
- 2.0.0
- 1.4.2
- 1.4.1
- 1.4.0
- 1.3.0
- 1.2.1
- 1.2.0
- 1.1.0
- 1.0.9
- 1.0.8
- 1.0.7
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
This package is auto-updated.
Last update: 2024-09-12 12:55:29 UTC
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
,触发下载URLjanitor:flush
,通过提供名称来刷新缓存(默认:页面缓存)janitor:job
,运行回调janitor:maintenance
,切换维护模式janitor:open
,在面板中触发打开URLjanitor: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
选项一起使用,在新标签页中打开URLlabel
,设置按钮的标签progress
,设置在按钮等待响应时显示的消息,支持查询语言success
,设置在所有200状态返回时显示的消息,支持查询语言unsaved
,如果为false
,则当面板视图有未保存内容时禁用按钮
Janitor API选项
在命令或回调中,您将通过其API设置/返回数据到Janitor按钮。根据您返回的内容,可以在面板中触发各种操作。
backgroundColor
,请参阅backgroundColor
字段选项clipboard
,要复制到剪贴板的字符串color
,请参阅color
字段选项download
,开始下载的URLerror
,请参阅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
,您还可以覆盖维护片段。
依赖项
免责声明
此插件“按原样”提供,不提供任何保证。请自行承担风险使用,并在将其用于生产环境之前自行测试。如果您发现任何问题,请创建新问题。
许可证
不建议在任何推广种族主义、性别歧视、恐同、动物虐待、暴力或其他任何形式仇恨言论的项目中使用此插件。