bnomei/kirby3-janitor

Kirby 3 Plugin for running jobs like cleaning the cache from within the Panel, PHP code or a cronjob

Installs: 309

Dependents: 0

Suggesters: 8

Stars: 20

Watchers: 0

Forks: 0

Open Issues: 0

Type:kirby-plugin

2.2.0 2019-11-07 17:40 UTC

README

Release Stars Downloads Issues Build Status Coverage Status Maintainability Demo Gitter Twitter

Kirby 3 Plugin for running jobs like cleaning the cache from within the Panel, PHP code or a cronjob.

TIP 1: The Janitor plugin can also perform other jobs than the build-in cache jobs.

TIP 2: It can also create logs of what it did.

TIP 3: I can also be used as an CLI.

  1. Custom Jobs
  2. Query Language
  3. Reload Panel
  4. Copy to Clipboard
  5. Open URL
  6. Download File
  7. CLI

Commerical Usage

This plugin is free but if you use it in a commercial project please consider to

Similar plugins

  • Kirby Terminal if you need to execute longer running processes on the terminal
  • Kirby Queue if you want to add scheduled jobs to queque which get trigged by a cron job

Installation

  • unzip master.zip as folder site/plugins/kirby3-janitor or
  • git submodule add https://github.com/bnomei/kirby3-janitor.git site/plugins/kirby3-janitor or
  • composer require bnomei/kirby3-janitor

Screenshot

clean & loot

Usage Examples

PHP code

$success = janitor('clean'); // boolean
// or
$json = janitor('clean', true); // array

Panel Field will create a clickable button

  janitor:
    type: janitor
    label: Clean Cache
    progress: Cleaning Cache...
    job: clean
  heist:
    type: janitor
    label: Enter Bank
    progress: Performing Heist...
    job: heist
    data: Grand # (string) forwarded to job context

Jobs

Predefined Jobs

  • flush calls flush() on kirbys core pages cache.
  • clean removes all cache-files from custom caches or plugins.

Custom Jobs

Go build your own jobs. Trigger APIs, create ZIPs, rename Files, ... check out the examples created for the unittests.

Extend with existing Jobs

Example: 'bnomei.janitor.jobs.extends' => ['bvdputte.kirbyqueue.queues'] will load all classnames or callbacks defined in option('bvdputte.kirbyqueue.queues') as well.

Queries

The data properties will be parsed for queries. You can use that to for example forward the current panel users email to your custom job.

janitor_query:
  type: janitor
  label: Query '{{ user.email }}'
  job: query
  data: '{{ user.email }}'
'query' => function (Kirby\Cms\Page $page = null, string $data = null) {
    return [
        'status' => 200,
        'label' => $data, // this is the email
    ];
},

Panel Features

Context page and data

  myjob:
    type: janitor
    label: Perform Job
    progress: Performing Job...
    job: myjob
    data: my custom data
'page' => function(Kirby\Cms\Page $page = null, string $data = null) {
    // $page => page object where the button as pressed
    // $data => 'my custom data'
    return [
        'status' => 200,
        'label' => $page->title() . ' ' . $data,
    ];
}

Reload Panel View

'reload' => function(Kirby\Cms\Page $page = null, string $data = null) {
    return [
        'status' => 200,
        'reload' => true, // will trigger JS location.reload in panel
    ];
}

Copy to Clipboard

'clipboard' => function(Kirby\Cms\Page $page = null, string $data = null) {
    return [
        'status' => 200,
        'clipboard' => 'Janitor',
    ];
}

Open URL

'openurl' => function(Kirby\Cms\Page $page = null, string $data = null) {
    return [
        'status' => 200,
        'href' => 'https://github.com/bnomei/kirby3-janitor',
    ];
}

Download File

'download' => function(Kirby\Cms\Page $page = null, string $data = null) {
    return [
        'status' => 200,
        'download' => 'https://raw.githubusercontent.com/bnomei/kirby3-janitor/master/kirby3-janitor-screenshot-1.gif',
    ];
}

ATTENTION: The download dialog will only appear at same origin otherwise it will behave like opening an url.

CLI

This plugin comes with an executable php script called janitor to use in the terminal/console. You can use it with an alias like this:

cd your/project/folder/root
alias janitor='php site/plugins/kirby3-janitor/janitor'
janitor --help

TIP: Depending on your OS you might need to make the script executable with chmod 0755 site/plugins/kirby3-janitor/janitor first.

TIP: If you are using a custom folder setup you need to tell the janitor where to get the kirby instance from like this janitor --kirby /public myJob. See Arguments below.

CLI Arguments

janitor --help

Usage: janitor [-f format, --format format (default: label)] [-h, --help] [-k kirby, --kirby kirby (default: /)] [-l, --list] [-v, --verbose] [job]
...

Kirby Instance Loader

The CLI needs to load the same Kirby Instance you website does. To achieve this the CLI attempts to create a special file named janitor-{HASH}.php based on your public index.php. It only comments out the echo statement.

CLI Examples

Examples based on the test from this plugin:

clean with dynamic progressbar

janitor --verbose clean

Using Kirby instance from: {PROJECT}/janitor-7848cb3c7677f4ff109682b2d9cd9978d46f7de8.php
======================================================================> 100%
200

print as table

janitor --format table whistle

----------------
| status | 200 |
----------------
| label  | ♫   |
----------------

print as json and store as file

janitor --format json heist | cat > heist-$(date +%s).json
cat heist-1573147345.json

{
    "status": 200,
    "label": "7 Coins looted at Bank!"
}

Settings

bnomei.janitor. Default Description
jobs array of classnames or callbacks array of ['key' => function() { return []; } ]
jobs.extends [] array of names to other job definitions. example: ['bvdputte.kirbyqueue.queues']
label.cooldown 2000 in millisecondss. the field allow you to override this as well.
secret null any string or callback
log.enabled false if enabled it try to call Kirby-log Plugin

Usage in JS, Vue and as a Cronjob

Kirby API (post Authentification)

let janitor = fetch('https://devkit.bnomei.com/api/plugin-janitor/clean')
  .then(response => response.json())
  .then(json => {
      console.log(json);
  });

Kirby Vue

this.$api.get('plugin-janitor/clean')
  .then(response => {
    console.log(response)
  })

Cronjob

Set a secret in your config.php file and call the janitor api with secret in a crobjob like this. This way you do not need the Kirby API to authentificate.

wget https://devkit.bnomei.com/plugin-janitor/clean/e9fe51f94eadabf54dbf2fbbd57188b9abee436e --delete-after
// or
curl -s https://devkit.bnomei.com/plugin-janitor/clean/e9fe51f94eadabf54dbf2fbbd57188b9abee436e > /dev/null

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.

Credits

License

MIT

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.