### Install Kirby3-Janitor via Composer

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Installation

Install the plugin using Composer, the dependency manager for PHP.

```bash
composer require bnomei/kirby3-janitor
```

--------------------------------

### Install Kirby3-Janitor via Manual Download

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Installation

Download the master zip file and extract it into the site/plugins/kirby3-janitor directory.

```bash
unzip [master.zip](https://github.com/bnomei/kirby3-janitor/archive/master.zip) as folder site/plugins/kirby3-janitor
```

--------------------------------

### Install Kirby CLI and Janitor Plugin

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Use composer to install the Kirby CLI and the Janitor plugin locally into your project. Ensure you install the CLI locally, as the plugin depends on it.

```bash
composer require getkirby/cli bnomei/kirby-janitor
```

--------------------------------

### Janitor Command Configuration Examples

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

YAML configurations for various Janitor commands, demonstrating different API options like labels, icons, progress indicators, and data forwarding.

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

```yaml
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
```

```yaml
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
```

```yaml
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 in the browser
```

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

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

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

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

--------------------------------

### Configure Download Job

Source: https://github.com/bnomei/kirby-janitor/wiki/Panel-Field:-Download-File

Use this configuration to set up a job that triggers a file download. The 'download' URL must be from the same domain as your Kirby installation.

```php
return [
    'bnomei.janitor.jobs' => [
        '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',
            ];
        },
    ],
];
```

--------------------------------

### Install Kirby3-Janitor via Git Submodule

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Installation

Add the plugin as a Git submodule to your Kirby project.

```bash
git submodule add https://github.com/bnomei/kirby3-janitor.git site/plugins/kirby3-janitor
```

--------------------------------

### Example Janitor API URL with Secret

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Secret-and-CRON

An example of how to construct a Janitor API URL that includes the secret key for authentication.

```url
https://devkit.bnomei.com/plugin-janitor/backupzip/e9fe51f94eadabf54
```

--------------------------------

### Custom Command: Deploy Site Logic

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Example of a custom Kirby CLI command for deployment. It utilizes 'Janitor::ARGS' to automatically receive arguments like page, file, and user. Returns data to the Panel button for status updates and actions.

```php
<?php
// site/commands/deploy.php

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

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

        // Perform work …
        $ok = true; // your logic here

        // CLI output (visible in terminal, suppressed by --quiet in Panel)
        $cli->success('Deployed ' . ($page?->title() ?? 'site'));

        // Return data to the Panel button
        janitor()->data($cli->arg('command'), [
            'status'  => $ok ? 200 : 500,
            'message' => $ok ? 'Deploy succeeded' : 'Deploy failed',
            'reload'  => true,   // reload the Panel view after success
        ]);
    },
];
```

--------------------------------

### Get Data Returned from a Command

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Demonstrates how to execute a Kirby CLI command and retrieve its associated data using the janitor helper. Ensure the command is registered or accessible.

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

--------------------------------

### Create a Custom Kirby CLI Command

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Define a custom command in `site/commands` or via a custom plugin. This example command processes a page and its data, then outputs a success message to the CLI and structured data to Janitor.

```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'),
        ]);
    }
];

```

--------------------------------

### Trigger Public Webhook Commands

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Examples of triggering Janitor commands via the public webhook using `wget`, `curl`, or the Kirby CLI. URL-encode arguments when necessary.

```bash
# Trigger backupzip via CRON with wget
wget "https://example.com/plugin-janitor/e9fe51f94eadabf54/janitor%3Abackupzip" --delete-after

# With URL-encoded arguments
curl -s "https://example.com/plugin-janitor/e9fe51f94eadabf54/janitor%3Athumbs%20--site" > /dev/null

# Using Kirby CLI in a CRON scheduler
cd /path/to/kirby && vendor/bin/kirby janitor:backupzip
```

--------------------------------

### Janitor CLI Output Formatting (JSON) and File Output

Source: https://github.com/bnomei/kirby-janitor/wiki/CLI

Execute a job, format the output as JSON, and redirect it to a file. The example shows looting coins and saving the result.

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

```bash
cat heist-1573147345.json
```

--------------------------------

### Trigger Janitor Command with wget or curl

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Use `wget` or `curl` to trigger Janitor commands via webhook, similar to the example URLs. The `--delete-after` option for `wget` and redirecting output for `curl` are shown.

```bash
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
```

--------------------------------

### Janitor CLI Maintenance Commands

Source: https://github.com/bnomei/kirby-janitor/wiki/CLI

Control Kirby's maintenance mode and start a REPL session using Janitor CLI commands.

```bash
janitor --tinker
```

```bash
janitor --down
```

```bash
janitor --up
```

--------------------------------

### Trigger Janitor Command via Webhook URL

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Example URLs for triggering Janitor commands via webhook. The first URL calls a command directly, while the second demonstrates how to include URL-encoded arguments.

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

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

--------------------------------

### Schedule Kirby CLI Command in Cron

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Example of how to schedule a Kirby CLI command, specifically a Janitor command, in a cron job. Ensure you `cd` to the project root before executing the command.

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

--------------------------------

### Remove Cache Entry with `janitor:trash`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Removes a single entry from a cache, either by specifying the page or an explicit key. The blueprint example automatically injects the current page for removal.

```bash
# Terminal
vendor/bin/kirby janitor:trash --page "page://vf0xqIlpU0ZlSorI"
vendor/bin/kirby janitor:trash --name pages --key "home.en.html"
```

```yaml
# Blueprint (button removes the cache entry for the current page)
fields:
  trash_this_page:
    type: janitor
    command: 'janitor:trash'   # --page injected automatically
    label: Remove this page from cache
    icon: trash
```

--------------------------------

### Janitor Button Configuration for Maintenance Mode

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Example YAML configuration for a Janitor button that toggles maintenance mode. It includes a command to execute, a cooldown period, and dynamic labels and icons based on the site's maintenance status.

```yaml
  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") }}'
```

--------------------------------

### Implement 'touchfile' Job in Config

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-with-File-or-User-Blueprints

Register the 'touchfile' job in `config.php`. This job takes a filename and updates its modification timestamp.

```php
<?php
return [
    // other options...
    'bnomei.janitor.jobs' => [
        'touchfile' => function (Kirby\Cms\Page $page = null, string $data = null) {
            $file = $page->file($data);
            if ($file) {
                touch($file->root());
            }
            return [
                'status' => $file ? 200 : 404,
                'label' => $file ? $file->modified() : $data,
            ];
        },
    ],
];
```

--------------------------------

### Render All Pages for Thumbnail Jobs

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Renders every page or a query-filtered subset to create `media/*.job` files for thumbnail generation. Can also be rendered via HTTP.

```bash
# Render full site
vendor/bin/kirby janitor:render
```

```bash
# Render only children of a specific page
vendor/bin/kirby janitor:render --query "page('projects').children()"
```

```bash
# Render via HTTP (useful when PHP CLI can't bootstrap Kirby fully)
vendor/bin/kirby janitor:render --remote https://example.com
```

```yaml
# Blueprint
fields:
  render_pages:
    type: janitor
    command: 'janitor:render'
    label: Render pages to create missing thumb jobs
```

--------------------------------

### Open a URL in the Panel with `janitor:open`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Navigates the Panel to a specified URL. Can optionally open the URL in a new tab if `intab: true` is set.

```yaml
fields:
  open_user:
    type: janitor
    command: 'janitor:open --data {{ user.panel.url }}'
    intab: true
    label: Open Current User
    icon: open
```

--------------------------------

### Janitor CLI Help and Usage

Source: https://github.com/bnomei/kirby-janitor/wiki/CLI

Display the help message for the Janitor CLI, showing available commands, options, and arguments.

```bash
janitor --help

Usage: janitor 
[-f format, --format format (default: label)] 
[-h, --help] 
[-k kirby, --kirby kirby (default: /)] 
[-l, --list] 
[-v, --verbose] 
[-t, --tinker] 
[-d, --down]
[-u, --up]
[-q, --quiet] 
[job]
...
```

--------------------------------

### Set Default Icon for Janitor Field

Source: https://github.com/bnomei/kirby-janitor/wiki/Panel-Field-Option:-Icon

Use the 'icon' option to specify a default icon for the Janitor field. This example uses Kirby's 'refresh' icon.

```yaml
janitor:
  type: janitor
  icon: refresh
```

--------------------------------

### Trigger a Browser Download with `janitor:download`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

In the Panel, instructs the browser to download the URL provided via `--data`. On the CLI, it delegates the download to `wget`.

```yaml
fields:
  download_export:
    type: janitor
    command: 'janitor:download --data {{ site.index.files.first.url }}'
    label: Download First File
    icon: download
```

--------------------------------

### Implement 'clipboard' Job in Config

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-with-File-or-User-Blueprints

Register the 'clipboard' job in `config.php`. This job returns data intended for clipboard copying, such as an email address.

```php
<?php
return [
    // other options...
    'bnomei.janitor.jobs' => [
        'clipboard' => function (Kirby\Cms\Page $page = null, string $data = null) {
             return [
                'status' => 200,
                'label' => 'Fetched. Click to Copy.',
                'clipboard' => $data, // the email address from {{ user.email }}
            ];
        },
    ],
];
```

--------------------------------

### Blueprint Field: Open User Panel URL

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Add a button to open the current user's Panel URL in a new browser tab. Use 'intab: true' to enable this behavior.

```yaml
fields:
  open_user_panel:
    type: janitor
    command: 'janitor:open --data {{ user.panel.url }}'
    intab: true
    label: Open current user in Panel
    icon: open
```

--------------------------------

### Janitor CLI Backup Job

Source: https://github.com/bnomei/kirby-janitor/wiki/CLI

Create a zip backup of accounts and content using the 'backupzip' job. The backup file is saved to `site/backups` with a timestamp.

```bash
janitor backupzip
```

--------------------------------

### Create ZIP Backup with `janitor:backupzip`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Zips the `accounts` and `content` directories into a timestamped ZIP file in `site/backups/`. Supports filtering by date and specifying a custom output path.

```bash
# Full backup
vendor/bin/kirby janitor:backupzip

# Only files changed in the last day, custom output path
vendor/bin/kirby janitor:backupzip \
  --date "since 1 day ago" \
  --output /var/backups/kirby-daily.zip
```

```php
<?php
// Trigger from a webhook and stream the file to the client
// site/config/config.php
return [
    'bnomei.janitor.secret' => 'e9fe51f94eadabf54',
    'bnomei.janitor.public.commands' => ['janitor:backupzip'],

    'routes' => [[
        'pattern' => 'webhook/(:any)/backup',
        'action'  => function (string $secret) {
            if (!Bnomei\Janitor::matchesSecret(janitor()->option('secret'), $secret)) {
                Kirby\Http\Header::status(401);
                die();
            }
            janitor()->command('janitor:backupzip --quiet');
            $path = janitor()->data('janitor:backupzip')['path'];
            if (F::exists($path)) {
                Kirby\Http\Header::download([
                    'mime' => F::mime($path),
                    'name' => F::filename($path),
                ]);
                readfile($path);
                die();
            }
        },
    ]],
];
```

--------------------------------

### Restrict Janitor Commands in Role Blueprints

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Restrict Janitor command permissions within Kirby role blueprints. Admins have all permissions by default. This example shows how to deny specific commands for an 'Editor' role.

```yaml
title: Editor
permissions:
  bnomei.janitor:
    commands.*: true
    commands.janitor.download: false
    commands.janitor.backupzip: false
```

--------------------------------

### Configure Webhook Endpoint for Backup and Download

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Sets up a custom webhook endpoint in Kirby's config to trigger a backup command and handle file downloads. Requires a secret for authentication and specifies public commands.

```php
<?php

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

    '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
                    }
                }
            }
        ],
    ],
];
```

--------------------------------

### Register Custom Janitor Jobs in Plugin

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-Jobs-from-Classes

Define custom Janitor jobs within your Kirby plugin. This example shows how to register a simple closure-based job ('cheat') and a job class ('invasion') under the 'jobs' option.

```php
// use kirby load()-helper or composer to load your custom class
load([
    'Space\Invaders\InvasionJob' => __DIR__ . '/classes/space/invaders/InvasionJob.php',
]);

Kirby::plugin('space/invaders', [
   'options' => [
        'jobs' => [
            'cheat' => function(Kirby\Cms\Page $page = null, string $data = null) {
                // update add more aliens based on data
                kirby()->impersonate();
                $page->increment('aliens', intval($data));

                // then reload
                return [
                    'status' => 200,
                    'reload' => true, // will trigger JS location.reload in panel
                ];
            },
            'invasion' => 'Space\Invaders\InvasionJob',
        ],
   ],
   // ... rest of your plugin
]);
```

--------------------------------

### Blueprint Usage: Custom Deploy Command

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Blueprint configuration to trigger the custom 'deploy' command from a Panel button. Includes command, label, icon, and feedback messages.

```yaml
# blueprint usage
fields:
  deploy:
    type: janitor
    command: 'deploy'
    label: Deploy
    icon: upload
    progress: Deploying…
    success: Deployed!
    error: Deploy failed
```

--------------------------------

### Configure Open URL Job

Source: https://github.com/bnomei/kirby-janitor/wiki/Panel-Field:-Open-URL

Use this configuration to make Janitor open a specified URL in the same browser window when the job is executed. Ensure the job returns a status of 200 and an 'href' key with the desired URL.

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

--------------------------------

### Blueprint Field: Generate Backup ZIP

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Configure a button to generate a backup ZIP file. Options include setting cooldown, label, icon, disabling autosave, allowing clicks with unsaved changes, and adding a confirmation dialog.

```yaml
fields:
  backup:
    type: janitor
    command: 'janitor:backupzip'
    cooldown: 5000
    label: Generate Backup ZIP
    icon: archive
    autosave: false
    unsaved: true
    confirm: Create a backup now?
```

--------------------------------

### Allow List for Janitor Commands

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Configure an explicit allow list for Janitor commands. Setting this to `[]` means no commands are allowed unless explicitly listed. `null` allows all commands not in the deny list.

```php
return [
    'bnomei.janitor.commands.allow' => [
        'janitor:pipe',
        'clear:cache',
    ],
];
```

--------------------------------

### Define Callback Jobs via `janitor:job`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Define custom tasks as PHP closures in `site/config/config.php` to be executed via the `janitor:job` command. The closure receives the relevant Kirby object and optional data.

```php
<?php
// site/config/config.php

return [
    'my.custom.task' => function ($model, $data = null): array {
        // $model is the Kirby object the button was pressed on
        return [
            'status'  => 200,
            'message' => 'Hello from ' . $model->title() . ($data ? ' – ' . $data : ''),
        ];
    },
];
```

```yaml
# blueprint usage
fields:
  run_task:
    type: janitor
    command: 'janitor:job --key my.custom.task --data optional-extra'
    label: Run Custom Task
```

--------------------------------

### Define File Touch Job in Blueprint

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-with-File-or-User-Blueprints

Configure a file blueprint to trigger a 'touchfile' Janitor job. The filename is passed to the job via the 'data' prop.

```yaml
title: Touch File

fields:
  janitor_touchfile:
    type: janitor
    label: Touch Job
    process: Touch Job...
    job: touchfile
    data: '{{ file.filename }}'
```

--------------------------------

### Configure Clipboard Copy Job

Source: https://github.com/bnomei/kirby-janitor/wiki/Panel-Field:-Copy-to-Clipboard

Define a job in Kirby Janitor's configuration to return data for clipboard copying. The 'clipboard' key in the response array holds the value to be copied, and 'label' updates the UI text.

```php
return [
    'bnomei.janitor.jobs' => [
        'clipboard' => function (Kirby\Cms\Page $page = null, string $data = null) {
            return [
                'status' => 200,
                'label' => 'Fetched. Click to Copy.',
                'clipboard' => !empty($data) ? $data : 'Janitor',
            ];
        },
    ],
];
```

--------------------------------

### Call Kirby CLI Command with Parameters

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Use this to call core or custom Kirby CLI commands with parameters. The `janitor()->command()` helper simplifies parameter formatting, especially for values with spaces or quotes. Alternatively, `Bnomei\Janitor::parseCommand()` can be used to manually parse command strings.

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

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

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

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

--------------------------------

### Copy Text to Clipboard with `janitor:clipboard`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Forwards the `--data` value to the browser clipboard when used in the Panel, or to `pbcopy` on macOS CLI.

```yaml
fields:
  copy_url:
    type: janitor
    command: 'janitor:clipboard --data {{ page.url }}'
    label: Copy Page URL
    icon: copy
    progress: Copied!
```

--------------------------------

### Define Janitor Callback in Config

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Instead of a command, you can define a callback function in your Kirby configuration files (e.g., `site/config/config.php`). This callback can be triggered using the `janitor:job` command.

```php
<?php

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

```

--------------------------------

### Configure Janitor Secret from .env

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Use a callback in `site/config/config.php` to load the Janitor secret from a `.env` file, which can be managed by the kirby3-dotenv plugin. This provides a more secure way to handle secrets.

```dotenv
# whatever key and value you like
MY_JANITOR_SECRET=e9fe51f94eadabf54
```

```php
<?php

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

--------------------------------

### Configure Command Authorization

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Restrict Panel API and webhook command access using global deny lists, explicit allow lists in `config.php`, or per-role permissions in blueprints.

```php
<?php
// site/config/config.php

return [
    // Global deny list — these commands are never allowed via Panel/webhook
    'bnomei.janitor.commands.deny' => [
        'janitor:download',
        'janitor:backupzip',
    ],

    // Explicit allow list — null = all allowed (minus deny); [] = nothing allowed
    'bnomei.janitor.commands.allow' => [
        'janitor:flush',
        'janitor:pipe',
        'my.custom.command',
    ],
];
```

--------------------------------

### Implement a Custom Janitor Job Class

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-Jobs-from-Classes

Create a PHP class that extends `Bnomei\JanitorJob` to define a custom Janitor job. Implement the `job()` method to return the job's status and label.

```php
<?php

namespace Space\Invaders;

class InvasionJob extends \Bnomei\JanitorJob
{
    /**
     * @return array
     */
    public function job(): array
    {
        $page = $this->page();
        $data = $this->data();
        return [
            'status' => 200,
            'label' =>  $page->title()->value() . ' vs. ' . str_repeat('👾', intval($data)),
        ];
    }
}
```

--------------------------------

### Schedule Composer Janitor Task via CRON

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Secret-and-CRON

Add a command to your CRON scheduler to execute a Composer script, such as `backupzip`, for automated Janitor tasks. Ensure you `cd` to your Kirby project root first.

```bash
cd /path/to/my/kirby/project/root && composer backupzip
```

--------------------------------

### Check Site Maintenance Status with `site.isUnderMaintenance()`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

The `site.isUnderMaintenance()` method returns a Kirby `Field` indicating if the site is in maintenance mode (i.e., if `.maintenance` exists in the Kirby root). Useful with `ecco()` in blueprints.

```php
<?php
if (site()->isUnderMaintenance()->isTrue()) {
    echo 'Site is down for maintenance';
}
```

--------------------------------

### Janitor CLI Output Formatting (Table)

Source: https://github.com/bnomei/kirby-janitor/wiki/CLI

Display the output of a job in a table format. This is useful for human-readable summaries.

```bash
janitor --format table whistle
```

--------------------------------

### Trigger Janitor Backupzip via CRON with wget

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Secret-and-CRON

Use `wget` to trigger the `backupzip` janitor job via its URL, including the secret for authentication. The `--delete-after` option removes the downloaded file immediately.

```bash
wget https://devkit.bnomei.com/plugin-janitor/backupzip/e9fe51f94eadabf54 --delete-after
```

--------------------------------

### Define User Copy Email Job in Blueprint

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-with-File-or-User-Blueprints

Configure a user blueprint to trigger a 'clipboard' Janitor job. The user's email is passed to the job via the 'data' prop.

```yaml
title: Copy E-Mail

fields:
  janitor_cpemail:
    type: janitor
    label: Copy E-Mail
    job: clipboard
    data: '{{ user.email }}'
```

--------------------------------

### Process Thumbnail Jobs with `janitor:thumbs`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Reads existing `.job` files from the media directory and generates the actual image files. Supports full site or current page processing.

```bash
# Full site
vendor/bin/kirby janitor:thumbs --site
```

```bash
# Only the current page (--page injected automatically when run from Panel)
vendor/bin/kirby janitor:thumbs --page "page://abc123"
```

```yaml
# Blueprint
fields:
  gen_thumbs_site:
    type: janitor
    command: 'janitor:thumbs --site'
    label: Generate All Thumbs
```

--------------------------------

### Blueprint Command Authorization

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Define command permissions for specific user roles within blueprint files. `commands.*: true` allows all, while specific commands can be explicitly allowed or denied.

```yaml
# site/blueprints/users/editor.yml — per-role permissions
title: Editor
permissions:
  bnomei.janitor:
    commands.*: true
    commands.janitor.download: false
    commands.janitor.backupzip: false
```

--------------------------------

### Backup Page Tree with `janitor:undertaker`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Archives a single page and its sub-pages to a timestamped ZIP file. Intended to be called from a `page.delete:before` hook.

```php
<?php
// site/config/config.php
return [
    'hooks' => [
        'page.delete:before' => function (Kirby\Cms\Page $page) {
            undertaker($page); // global helper provided by the plugin
        },
    ],
];
```

```bash
# Terminal
vendor/bin/kirby janitor:undertaker --page "page://abc123" --user "user://xyz"
```

--------------------------------

### Call a Method on the Current Model with `janitor:call`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Calls a named method directly on the page, file, user, or site object. Can pass data to the method.

```yaml
fields:
  call_publish:
    type: janitor
    command: 'janitor:call --method publish'
    label: Publish
```

```yaml
  call_with_data:
    type: janitor
    command: 'janitor:call --method repeatAfterMe --data {{ user.id }}'
    label: Call with Data
```

```bash
# Terminal
vendor/bin/kirby janitor:call --method whoAmI --page "page://abc123"
```

--------------------------------

### Enable Thumbs on Upload

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Thumbs-on-Upload

Set the 'bnomei.janitor.thumbsOnUpload' option to true in your Kirby config to enable automatic thumbnail generation on file uploads.

```php
<?php
return [
    // other options
    'bnomei.janitor.thumbsOnUpload' => true,
];

```

--------------------------------

### Configure Public Webhook Route

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Set up a secret-protected public route in `config.php` to allow external callers to trigger specific Janitor commands. Ensure the commands are listed in `public.commands`.

```php
<?php
// site/config/config.php
return [
    'bnomei.janitor.secret' => 'e9fe51f94eadabf54',
    'bnomei.janitor.public.commands' => [
        'janitor:backupzip',
        'janitor:thumbs',
        'janitor:flush',
    ],
];
```

--------------------------------

### Configure Maintenance Mode Check Callback

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Customize the maintenance mode check by providing a callback in `site/config/config.php`. This callback determines whether maintenance mode should be enforced, allowing for conditional activation based on user roles or other criteria.

```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...
];
```

--------------------------------

### Store and Retrieve Command Output with `janitor()->data()`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Utilize `janitor()->data()` to store output from commands for retrieval by the Panel or calling PHP code. Supports various data types for notifications, reloads, and more.

```php
<?php
// Inside a command's closure — store data:
janitor()->data($cli->arg('command'), [
    'status'       => 200,
    'message'      => 'Done!',
    'reload'       => true,          // reload Panel view
    'notification' => ['success', 'All thumbs generated!'],
    'clipboard'    => 'text to copy',
    'open'         => 'https://example.com',
    'download'     => 'https://example.com/file.zip',
    'label'        => 'New Button Label',
    'icon'         => 'check',
    'color'        => 'var(--color-green-600)',
    'backgroundColor' => 'var(--color-green-200)',
    'log'          => 'debug info → console.log()',
    'warn'         => 'warning → console.warn()',
    'error'        => 'error → console.error()',
]);

// From calling PHP code — retrieve data:
$result = janitor()->data('my-command-name');
```

--------------------------------

### Extend Jobs with External Definitions

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-Custom-Jobs

Load additional job definitions from other plugins or configurations using the `jobs-extends` option. This allows for modular job management.

```php
'bnomei.janitor.jobs-extends' => ['bvdputte.kirbyqueue.queues']
```

--------------------------------

### Set up Janitor CLI Alias

Source: https://github.com/bnomei/kirby-janitor/wiki/CLI

Define aliases for the Janitor CLI to easily execute commands. The `janitor2g` alias increases the memory limit to 2GB for memory-intensive tasks.

```bash
cd your/project/folder/root
alias janitor='php site/plugins/kirby3-janitor/janitor'
alias janitor2g='php -d memory_limit=2G site/plugins/kirby3-janitor/janitor'
janitor --help
```

--------------------------------

### Configure Button for Draft Pages

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-Custom-Jobs

Set up a Janitor button in a blueprint to work with page drafts. The `data` field is used to pass the page ID, which is then used to retrieve the page object within the job closure.

```yaml
janitor:
  type: janitor
  label: Awesome
  progress: Awesome...
  job: buttonOnADraftOrPage
  data : '{{ page.id }}'
```

--------------------------------

### Run Commands Programmatically with `janitor()->command()`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Execute any CLI command directly from PHP code and retrieve its response data. Supports simple calls, dynamic argument construction, and direct use of the low-level `CLI::command()`.

```php
<?php
// In a hook, model method, or controller

// Simple call
janitor()->command('janitor:flush --name pages --quiet');

// Call with dynamic arguments built as a string
janitor()->command('uuid --page some/page/id --quiet');
$result = janitor()->data('uuid');
// $result => ['status' => 200, 'message' => 'page://82h2nkal12ls']

// Use the low-level CLI::command() directly with parsed args
[$name, $args] = Bnomei\Janitor::parseCommand('janitor:backupzip --quiet');
Kirby\CLI\CLI::command($name, ...$args);
$backup = janitor()->data('janitor:backupzip');
// $backup['path'] => '/path/to/site/backups/1700000000.zip'
```

--------------------------------

### Configure Janitor Job with Confirmation

Source: https://github.com/bnomei/kirby-janitor/wiki/Panel-Field-Option:-Confirm

Use the 'confirm' option within your janitor configuration to display a confirmation dialog before the job runs. This is useful for actions that should not be performed accidentally.

```yaml
janitor:
  type: janitor
  label: Take out the trash
  progress: Taking out the trash...
  job: meAndMyTrash
  confirm: "Do you really want to take out the trash now?"
```

--------------------------------

### Custom File Upload Hook for Thumbs

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Thumbs-on-Upload

Implement a custom hook to generate specific thumbnail sizes on file upload. This is useful for headless CMS or when precise control over thumbnail dimensions is needed. Ensure the file is resizable before attempting to generate thumbs.

```php
<?php
return function($file) {
    if($file->isResizable()) {
        $widths = option('thumbs.srcset.default', [320, 1200]);
        foreach($widths as $width) {
            try {
                $resizedImage = $file->resize($width)->save();
            }
            catch (Exception $e) {
                throw new Exception($e->getMessage());
            }
        }
    }
}

```

--------------------------------

### Blueprint Field: Copy Page Title to Clipboard

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Create a button that copies the current page's title to the clipboard using the 'janitor:clipboard' command. Supports Kirby's query language for dynamic data.

```yaml
fields:
  copy_title:
    type: janitor
    command: 'janitor:clipboard --data {{ page.title }}'
    label: 'Copy "{{ page.title }}" to Clipboard'
    icon: copy
    progress: Copied!
```

--------------------------------

### Define a Custom Job as a Closure

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-Custom-Jobs

Register a new job by defining a closure within the Kirby configuration. This closure receives the page object and custom data, returning a status and label.

```php
'bnomei.janitor.jobs' => [
    'aweSomeItCouldBe' => 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,
        ];
    },
]
```

--------------------------------

### Blueprint Field: Toggle Maintenance Mode

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Implement a button to toggle the site's maintenance mode. The label and icon dynamically update based on the site's maintenance status.

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

--------------------------------

### Pipe Data to Response Key with `janitor:pipe`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Use `janitor:pipe` to map `--data` values to any Janitor response key. This acts as a generic bridge for forwarding information.

```yaml
fields:
  show_field_value:
    type: janitor
    command: 'janitor:pipe --data {{ page.sele }} --to message'
    label: Show selected value

  open_via_pipe:
    type: janitor
    command: 'janitor:pipe --data {{ user.panel.url }} --to open'
    intab: true
    label: Open User (via pipe)
```

--------------------------------

### Call a Custom Job from PHP

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-Custom-Jobs

Execute a registered custom job using the `janitor()` helper function. You can call it with just the job key or provide a page object and custom data.

```php
$success = janitor('aweSomeItCouldBe'); // boolean

// or with context page and data
$json = janitor('aweSomeItCouldBe', $page, 'ルパン三世', true);
// array [status=>200, label=>title and data]
```

--------------------------------

### Deny List for Janitor Commands

Source: https://github.com/bnomei/kirby-janitor/blob/master/README.md

Configure a global deny list for commands that should never be dispatched through Janitor's Panel API. This prevents specific commands from being accessible via the panel.

```php
return [
    'bnomei.janitor.commands.deny' => [
        'janitor:download',
        'janitor:backupzip',
    ],
];
```

--------------------------------

### Janitor CLI Render Thumbs Job

Source: https://github.com/bnomei/kirby-janitor/wiki/CLI

Pre-generate all thumbs for content using the 'render' job. This can be a time-consuming process.

```bash
janitor render
```

--------------------------------

### Janitor CLI Clean Cache with Verbose Output

Source: https://github.com/bnomei/kirby-janitor/wiki/CLI

Clear the cache and display verbose output, including the Kirby instance loader information.

```bash
janitor --verbose cleanCache
```

--------------------------------

### Add a Panel Button for a Custom Job

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-Custom-Jobs

Configure a panel button in your Kirby blueprint to trigger a custom Janitor job. Specify the job key and any progress text.

```yaml
janitor:
  type: janitor
  label: Awesome
  progress: Awesome...
  job: aweSomeItCouldBe
```

--------------------------------

### Toggle Maintenance Mode with `janitor:maintenance`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Creates or removes a `.maintenance` file in the Kirby root to enable/disable maintenance mode. Supports forcing down or up states and custom checks.

```bash
vendor/bin/kirby janitor:maintenance          # toggle
```

```bash
vendor/bin/kirby janitor:maintenance --down   # force down
```

```bash
vendor/bin/kirby janitor:maintenance --up     # force up
```

```php
<?php
// site/config/config.php — custom check (e.g. allow logged-in admins through)
return [
    'bnomei.janitor.maintenance.check' => function (): bool {
        return kirby()->users()->current()?->role()->isAdmin() !== true;
    },
];
```

```yaml
# Blueprint — dynamic label & icon reflect current state
fields:
  toggle_maintenance:
    type: janitor
    command: 'janitor:maintenance --user {{ user.uuid }}'
    cooldown: 5000
    label: 'Maintenance: {{ site.isUnderMaintenance.ecco("DOWN","UP") }}'
    icon: '{{ site.isUnderMaintenance.ecco("cancel","circle") }}'
```

--------------------------------

### Add Janitor Scripts to composer.json

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Secret-and-CRON

Define custom Composer scripts for Janitor tasks like `backupzip` and `thumbs` within your project's `composer.json` file.

```json
{
  "scripts": {
    "backupzip": [
      "php site/plugins/kirby3-janitor/janitor backupzip"
    ],
    "thumbs": [
      "php site/plugins/kirby3-janitor/janitor thumbs"
    ]
  }
}
```

--------------------------------

### Resolve UUID or ID to Kirby Model with `Janitor::resolveModel()`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Convert UUIDs (e.g., `page://...`, `file://...`) or plain IDs into their corresponding Kirby model objects using `Janitor::resolveModel()`. Supports pages, files, users, and the site.

```php
<?php
use Bnomei\Janitor;

$page = Janitor::resolveModel('page://82h2nkal12ls');
$file = Janitor::resolveModel('file://abc123');
$user = Janitor::resolveModel('editor@example.com');
$site = Janitor::resolveModel('site://');
```

--------------------------------

### Trigger Janitor Backupzip via CRON with curl

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Secret-and-CRON

Use `curl` to trigger the `backupzip` janitor job via its URL, including the secret for authentication. Output is redirected to `/dev/null` to discard it.

```bash
curl -s https://devkit.bnomei.com/plugin-janitor/backupzip/e9fe51f94eadabf54 > /dev/null
```

--------------------------------

### Extend Janitor Jobs Configuration

Source: https://github.com/bnomei/kirby-janitor/wiki/HowTo:-Jobs-from-Classes

Configure your Kirby site to include jobs from other plugins or custom locations by adding their namespaces to the 'bnomei.janitor.jobs-extends' option in your config.php.

```php
return [
    'bnomei.janitor.jobs-extends' => [
        'space.invaders.jobs', // name of plugin option
    ],
    // rest of config
];
```

--------------------------------

### Configure Janitor Secret in config.php

Source: https://github.com/bnomei/kirby-janitor/wiki/Setup:-Secret-and-CRON

Set a secret key in your Kirby site's `config.php` file to authenticate API calls to the Janitor plugin without needing Kirby API authentication.

```php
'bnomei.janitor.secret' => 'e9fe51f94eadabf54',
```

--------------------------------

### Blueprint Field: Clear Pages Cache

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Use the 'janitor' field type in blueprints to create a Panel button for clearing the pages cache. Configure command, label, icon, and feedback messages.

```yaml
fields:
  flush_pages_cache:
    type: janitor
    command: 'janitor:flush --name pages'
    label: Clear Pages Cache
    icon: trash
    progress: Clearing…
    success: Cache cleared!
    error: Something went wrong
    cooldown: 3000
```

--------------------------------

### Resolve Kirby Query Language with `Janitor::query()`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Evaluate template strings containing `{{ … }}` tokens against a Kirby model using `Janitor::query()`. This allows dynamic string generation based on model properties.

```php
<?php
use Bnomei\Janitor;

$page  = kirby()->page('projects/my-project');
$label = Janitor::query('Title: {{ page.title }} — by {{ user.name }}', $page);
// => "Title: My Project — by John Doe"
```

--------------------------------

### Add Panel Button to Clean Cache

Source: https://github.com/bnomei/kirby-janitor/wiki/Example:-Clean-cache-with-Panel-button

Add this field to any Kirby blueprint to create a button in the Panel for cleaning the cache. This utilizes the plugin's built-in `cleanCache` job.

```yaml
  janitor:
    type: janitor
    label: Clean Cache
    progress: Cleaning Cache...
    job: cleanCache
```

--------------------------------

### Flush Cache with `janitor:flush`

Source: https://context7.com/bnomei/kirby-janitor/llms.txt

Clears an entire Kirby cache by its name. The default cache to be flushed is 'pages'.

```bash
# Terminal
vendor/bin/kirby janitor:flush
vendor/bin/kirby janitor:flush --name images
```

```yaml
# Blueprint
fields:
  flush_images:
    type: janitor
    command: 'janitor:flush --name images'
    label: Flush Image Cache
    icon: trash
    success: Cache cleared!
```