bnomei / kirby3-janitor
Kirby Plugin for running commands like cleaning the cache from within the Panel, PHP code or a cronjob
Fund package maintenance!
bnomei
Patreon
buymeacoff.ee/bnomei
paypal.me/bnomei
Installs: 27 656
Dependents: 3
Suggesters: 6
Security: 0
Stars: 88
Watchers: 5
Forks: 7
Open Issues: 6
Type:kirby-plugin
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-10-12 13:12:20 UTC
README
Kirby Plugin for running commands.
- It is a Panel Button!
- It has commands built-in for cleaning the cache, sessions, create zip-backup, pre-generate thumbs, open URLs, refresh the current Panel page and more.
- You can define your own commands (call API hooks, play a game, hack a server, ...)
- It can be triggered in your frontend code, with the official kirby CLI and a CRON.
Install
You have to use composer to install both the plugin and the CLI locally into your project:
composer require getkirby/cli bnomei/kirby3-janitor
Warning
You need to install the CLI with composer into your project and not use the global version. Since Janitor depends on the CLI to be available, installing only the janitor plugin via submodules or via ZIP is NOT supported.
Commercial Usage
Support open source!
This plugin is free but if you use it in a commercial project please consider to sponsor me or make a donation.
If my work helped you to make some cash it seems fair to me that I might get a little reward as well, right?
Be kind. Share a little. Thanks.
‐ Bruno
Setup
CLI Command
In any blueprint create a janitor field with your command, browse to that page in panel and press the button.
site/blueprints/page/default.yml
title: Default Page fields: call_my_command: type: janitor command: 'example --data test' label: Call `Example` Command
Janitor will automatically fill in the current model.
- The
--model
argument will have the UUID or ID of the current model. You can usejanitor()->model($cli->arg('model))
to get the object. - But if for example you press the panel button on a page you will have
--page
argument set to the UUID or ID of that page. Use$cli->kirby()->page($cli->arg('page'))
to get the object. - If you call it on a file view then
--file
arg will be set. Use$cli->kirby()->file($cli->arg('file'))
to get the object. - On a panel user view...
--user
. Use$cli->kirby()->user($cli->arg('user'))
to get the object. - And lastly
--site
(boolean) will be automatically set when you had the button in thesite/blueprints/site.yml
blueprint.if($cli->arg('site')) { $cli->kirby()->site(); }
Create a Kirby CLI command via a custom plugin or put them into 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'), ]); } ];
Callback
Instead of using a command you can also create a callback in a custom plugin options or any config file.
site/config/config.php
<?php return [ 'example' => function ($model, $data = null) { return [ 'status' => 200, 'message' => $model->title() . ' ' . $data, ]; }, // ... other options ];
The Janitor plugin has a special command janitor:job
that you can use to trigger your callback.
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
The $model
will match the model of whatever page, file, user or site object you pressed the button at.
Note
Why just a single model variable instead of one each for page, file, user and site? For one reason to make it work directly with any existing version 2 callbacks you might have already created and secondly because this why it is very easy to get the model that triggered the callback.
Built in commands and examples
This plugin comes with a few commands you might like to use yourself and some example commands used to showcase the various options the button has (like how to change the icon or open a URL in a new tab). Some commands can be used in both panel and terminal. Others are limited in their use to either one of them. In the terminal you can use --help
argument to view the help for each command.
janitor:backupzip
, creates a backup zipjanitor:call
, calls a method on the current model with optional data parameterjanitor:cleancontent
, removes fields from content file that are not defined in your blueprintsjanitor:clipboard
, copies a defined value to your clipboardjanitor:download
, triggers a download of an URLjanitor:flush
, flush a cache by providing its name (default: pages cache)janitor:job
, run a callbackjanitor:maintenance
, toggle maintenance modejanitor:open
, triggers opening of an URL in paneljanitor:out
, sends a message to the CLI output streamjanitor:pipe
, map input argument to output argumentjanitor:render
, render a certain page or all pages (to create thumb jobs)janitor:thumbs
, process thumb jobs of a certain page or all pagesjanitor:tinker
, run a REPL session in terminaljanitor:trash
, removes an entry from given cache by key or page (default: pages cache)janitor:undertaker
, backups a page and its subpages to a zip. You need to manually trigger it with a hook.
The plugin will register these commands starting with janitor:*
automatically - no copying required.
But if you want to re-use any of the other example provided you need to copy them to your site/commands
-folder
Blueprint field options
The button you create with the field: janitor
in your blueprint can be configured to do various things. Checkout the example default.yml blueprint to familiarize yourself with how to use it.
autosave
, iftrue
then save before pressing the buttonbackgroundColor
, sets backgroundColor of buttoncolor
, sets text color of buttonconfirm
, sets text for confirmation after clicking the button and before executing the command, can prevent the execution of the command if the user clickscancel
in the OS dialogcommand
, command like you would enter it in terminal, with query language support and page/file/user/site/data argumentscooldown
, time in milliseconds the message is flashed on the button (default: 2000)error
, set message to show on all non-200-status returns with query language supporthelp
, set help of the buttonicon
, set the icon of the buttonintab
, iftrue
then use in combination with theopen
-option to open an URL in a new tablabel
, set label of the buttonprogress
, set message to show while the button waits for the response, with query language supportsuccess
, set message to show on all 200-status returns, with query language supportunsaved
, iffalse
then disable the button if panel view has unsaved content
Janitor API options
In either the command or the callback you will be setting/returning data to the Janitor button via its api. Depending on what you return you can trigger various things to happen in the panel.
backgroundColor
, seebackgroundColor
-field optionclipboard
, string to copy to clipboardcolor
, seecolor
-field optiondownload
, URL to start downloadingerror
, seeerror
-field optionhelp
, seehelp
-field optionicon
, seeicon
-field optionlabel
, seelabel
-field optionmessage
, seemessage
-field optionopen
, URL to open, use withintab
-field option to open in a new tabreload
, iftrue
will reload panel view once api call is receivedsuccess
, seesuccess
-field optionstatus
, return200
for a green button flash, anything else for a red flash
Examples
Again... check out the built-in commands and plugin example commands to learn how to use the field and api options yourself.
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 }}'
If you want you can also call any of the core shipping with the CLI like clear:cache
.
Keep in mind that the Janitor panel button and webhooks will append the --quiet
option on all commands automatically to silence outputs to the non-existing CLI. But if you use janitor()->command()
you will have to append --quiet
to your command yourself.
Running commands in your code
You can run any command in you own code as well like in a model, template, controller or hook. Since commands do not return data directly you need to retrieve data stored for Janitor using a helper janitor()->data($commandName)
.
Get data returned from a command
Kirby\CLI\CLI::command('whistle'); // tests/site/commands/whistle.php var_dump(janitor()->data('whistle'));
Create and download a backup
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 } } } ], ], ];
Calling a command with parameters
Supplying parameter to the core CLI functions can be a bit tricky since you need to separate argument key and argument values. It seems easy with one but gets a bit tedious with a dynamic list of parameters and if values contain space
-chars or quotes. But fret not – Janitor has a helper for that as well.
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
Remember that using the
janitor()->command($string)
-helper you can call any of your own commands and the core commands as well, not just the ones defined by Janitor.
If you want to work with command strings yourself you can use the following static helper method.
list($name, $args) = Bnomei\Janitor::parseCommand('uuid --page page://82h2nkal12ls'); Kirby\CLI\CLI::command($name, ...$args);
Webhook with secret
You can not call Janitors api unauthenticated. You either need to use the panel button or you can set a secret
in your site/config/config.php
file and call the janitor api URL with that secret.
site/config/config.php
<?php return [ 'bnomei.janitor.secret' => 'e9fe51f94eadabf54', // whatever string you like //... other options ];
You could also use a callback if you want to store the secret in a .env
file and have it loaded by my dotenv plugin.
/.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 ];
example URL
https://dev.bnomei.com/plugin-janitor/e9fe51f94eadabf54/janitor%3Abackupzip
example URL with urlencoded arguments
http://dev.bnomei.com/plugin-janitor/e9fe51f94eadabf54/janitor%3Athumbs%20--site
CRON
Webhook with wget or curl
You can also use the secret to trigger a job using wget or 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
Are you having issues with PHP bin and cron? read this.
Kirby CLI (installed with composer)
in your cron scheduler add the following command
cd /path/to/my/kirby/project/root && vendor/bin/kirby janitor:backupzip
Maintenance Mode
You can toggle maintenance mode with a janitor button like this:
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") }}'
If you need to add a custom check when maintenance mode is enforced you can do this by providing a callback for the bnomei.janitor.maintenance.check
option.
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... ];
You can also overwrite the maintenance snippet if you create your own and store it as site/snippets/maintenance.php
.
Dependencies
Disclaimer
This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.
License
It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.