Once a ProcessWire site is live, the production database is not a deployable artifact. It is the source of truth for content, users, roles, module settings, and module-owned data.

Deploy code from Git. Apply reviewed migrations to the production database. Preserve production data, uploads, configuration, and secrets. If an AI coding agent is involved, write these boundaries down in AGENTS.md and enforce them with scripts rather than relying on the agent to infer what “deploy” means.

I arrived at this rule through a real incident.

The incident

I was rebuilding a ProcessWire site locally with an AI coding agent. The data model had changed substantially, the development site contained useful demo content, and the production site had little activity. I asked the agent to deploy the new version and replace the old data.

Technically, the operation succeeded:

• the code was deployed;
• the new schema appeared;
• the development database was imported;
• development uploads replaced production uploads;
• the public pages worked.

But a database is not just “content”. The import also replaced production-only module configuration, users, roles, support tickets, AI conversations, and records stored in custom module tables. SMTP happened to survive because its configuration matched in both environments. Other settings did not.

Backups existed, so the incident was recoverable. The site also had almost no real activity. On a busy site, the same operation could have destroyed orders, form submissions, member accounts, unpublished editorial work, audit history, or messages created during the deployment window.

The important lesson was not “the AI made a mistake”. The deployment process allowed an ambiguous instruction to become a destructive database operation. That is a systems problem.

Why ProcessWire needs an explicit deployment model

ProcessWire's file layout is deliberately clear: /wire/ contains the core, while /site/ contains site-specific templates, modules, configuration, and assets. The official documentation also identifies site/config.php as the site configuration file and site/assets/ as writable runtime storage.

That filesystem separation is useful, but a mature ProcessWire project has another boundary that is easier to miss:

Deployment ownership map

• Git release — templates, hooks, module code, and frontend assets. Source of truth: the repository.
• Database structure — fields, templates, fieldgroups, and module schemas. Source of truth: reviewed migrations.
• Production database — pages, users, roles, settings, submissions, and module-owned tables. Source of truth: production.
• Runtime configuration — database credentials, hostnames, and environment flags. Source of truth: the production runtime.
• Secrets — SMTP, API, and OIDC credentials. Source of truth: a secret store or protected runtime files.
• Writable assets — uploads, generated files, logs, sessions, and backups. Source of truth: production storage.

The initial launch is special. If production is empty, cloning a reviewed development database may be reasonable. After the first real user, form submission, editor change, or module configuration, that direction must stop.

Production may flow to development through a protected and preferably sanitized snapshot. Development must not flow back as a whole database.

This is the same problem described in ProcessWire's own article introducing migrations: once the live server receives content while features continue to be developed locally, the databases diverge and changes must be merged rather than replaced.

Use releases for code and migrations for change

A production release should be an immutable Git commit, preferably accompanied by a tag. Build the deployable file list from that commit—not from the current working directory.

A release manifest should include only public runtime code and static assets. It should explicitly exclude:

• .git/ and CI configuration;
• AGENTS.md and development documentation;
• site/config.php and environment-specific config;
• database dumps, credentials, and private keys;
• site/assets/files, caches, logs, sessions, and backups;
• tests, fixtures, local tooling, and editor configuration.

ProcessWire fields and templates live in the database, so code deployment alone is not always sufficient. Represent structural changes as idempotent, versioned migrations. A migration may use ProcessWire's API, a migration module, or a project-specific CLI script. The important properties are the same:

1. it has a preview or audit mode;
2. it is safe to run more than once;
3. it changes only named structures or records;
4. it preserves unknown production configuration;
5. large transformations are bounded and resumable;
6. destructive steps require a fresh verified backup and rollback data;
7. successful application is recorded.

ProcessWire has community options such as ProcessDbMigrate and migration modules, but no tool removes the need to classify production data correctly.

A backup is not verified until it can be restored

“The backup command returned zero” is not enough.

For every production release:

1. create a timestamped database backup outside the document root;
2. verify its size and checksum;
3. verify compressed-stream integrity;
4. periodically restore it into an isolated database;
5. keep a backup of the exact files being replaced;
6. record the rollback path before changing production.

This matters because backup tools can produce syntactically valid-looking files that fail only during restoration. Test the recovery path, not merely the backup button.

The official ProcessWire upgrade guide likewise recommends backing up both files and database and testing upgrades on a development or staging site first.

Add a fail-closed deployment guard

Documentation is necessary, but an executable invariant is better.

Before deployment, create a private snapshot containing no secret values:

• row counts for protected tables;
• page counts by template;
• stable page IDs by template;
• installed module names;
• names and configured/empty state of module configuration keys;
• intended Git commit;
• production hostname;
• verified backup metadata.

After code deployment and migrations, take the same measurements and compare them. Block completion if:

• a protected table disappeared or lost rows;
• a pre-existing page ID disappeared;
• a template or installed module disappeared;
• a module configuration key disappeared;
• a configured value became empty;
• the host or release commit does not match.

Stable IDs matter. Row counts alone can miss a replacement database containing the same number of different records.

Some legitimate migrations intentionally remove obsolete data. That should be an exceptional workflow requiring a change ID, a table-by-table impact report, a tested restore, and a second explicit approval. A generic “deploy everything” instruction must never authorize it.

What to tell an AI coding agent

An AI agent is fast enough to turn an ambiguous sentence into a complete deployment before a human notices the ambiguity. Give it a narrower contract.

The repository instructions should state:

• development and production paths and hostnames;
• production is read-only unless a production change is explicitly requested;
• commit, push, deploy, migrate, publish, and replace data are separate actions;
• “deploy” means code-only unless named migrations are included;
• a development database must never overwrite a launched production database;
• production users, content, module configuration, custom tables, and uploads must be preserved;
• secrets must not be read, printed, hashed, copied locally, or committed;
• every mutation needs a fresh verified backup and exact rollback path;
• migrations run in preview first and must be bounded/idempotent;
• a data decrease is a blocker, not a warning;
• if scope is ambiguous, stop after read-only investigation;
• destructive approval is two-phase: impact report first, explicit confirmation of that report second;
• maintenance is not removed and success is not reported while checks fail.

The open AGENTS.md format is useful here because it gives multiple coding agents a predictable repository-level instruction file. Its documentation explicitly recommends including build commands, testing, security concerns, and deployment details, and supports more specific nested files where needed.

I prepared a reusable template and attached it to this post as ProcessWire-AGENTS-production-safety-template.zip. The archive contains a single AGENTS.md file. Download it, replace the placeholders, and commit it to the root of your project. Do not deploy it into the public document root.

A practical release checklist

Before maintenance

• Select an immutable Git commit.
• Review the diff and release manifest.
• List every migration and classify its risk.
• Create and verify database and file backups.
• Create the protected data snapshot.
• Write the rollback command/path.

During maintenance

• Deploy only manifest files.
• Preserve production config, secrets, uploads, logs, sessions, and backups.
• Run migrations in preview, then apply.
• Run the fail-closed comparison.
• Stop on any unexplained decrease.

Before reopening

• Test origin and CDN routes.
• Test authentication and representative member workflows.
• Verify email delivery readiness and background jobs.
• Inspect new logs without exposing secrets.
• Record commit, manifest checksum, migration results, backups, and rollback.
• Remove maintenance only when every blocker is resolved.

Final principle

The database is not “the backend version of the code”. On a live ProcessWire site it is accumulated production state.

AI does not change this rule. AI makes it more important to encode the rule in files, scripts, permissions, and fail-closed checks—because the agent can execute a bad assumption much faster than a human can recognize it.

References

• ProcessWire file and directory structure
• ProcessWire: migrating to production
• ProcessWire upgrade best practices
• ProcessWire file permissions and protecting site/config.php
• ProcessWire: Introduction to the Migrations module
• ProcessDbMigrate module directory entry
• AGENTS.md open format

ProcessWire-AGENTS-production-safety-template.zip

Recently I spent a few days making my ProcessWire site run in a Docker container, and - as I could not find any good tutorial for this - it sounded like a good idea to write one. 

$ docker run --name database -e MYSQL_ROOT_PASSWORD=rootdbpassword -d mariadb

docker run --rm --link database:mysql -p 8881:80 nazarpc/phpmyadmin

docker run -d --name phpmyadmin --link database:mysql -p 8881:80 nazarpc/phpmyadmin

$config->dbHost = 'mysql';

bash-3.2$ ls -l . config
.:
total 16
-rw-rw-rw-   1 jean-luc  staff  1163 21 aoû 12:09 Dockerfile
drwxr-xr-x  17 jean-luc  staff   578 17 aoû 12:48 ProcessWire
drwxr-xr-x   7 jean-luc  staff   238 21 aoû 12:07 config
drwxr-xr-x   7 jean-luc  staff   238 20 aoû 18:46 site

config:
total 160
-rw-rw-rw-  1 jean-luc  staff    160 20 aoû 18:28 msmtprc
-rw-rw-rw-  1 jean-luc  staff  72518 20 aoû 18:56 php.ini

• `ProcessWire` contains the version of ProcessWire that we want to use for this site;  
  It can be retrieved from github with a link like https://github.com/ryancramerdesign/ProcessWire/archive/{version}.zip`  
  For example, the 2.6.13 dev version can be obtained by the link https://github.com/ryancramerdesign/ProcessWire/archive/7d37db8d6b4ca6a132e50aff496a70e48fcd2284.zip
• `site`: our site-specific files
• `Dockerfile`: the dockerfile for building the image (see below)
• `config`: a directory containing specific configuration files copied to the docker image (see below)

FROM php:5.6-apache

RUN    apt-get update \
&& apt-get install -y libfreetype6-dev libjpeg62-turbo-dev libmcrypt-dev libpng12-dev zziplib-bin msmtp\
&& a2enmod rewrite \
&& a2enmod ssl \
&& docker-php-ext-install mysqli pdo_mysql iconv mcrypt zip \
&& docker-php-ext-configure gd --with-freetype-dir=/usr/include/ --with-jpeg-dir=/usr/include/ \
&& docker-php-ext-install gd 

EXPOSE 80
EXPOSE 443

# Add a specific php.ini file
COPY config/php.ini /usr/local/etc/php/

# Configure the mail sent utility msmtp (http://msmtp.sourceforge.net) and make it readable only by www-data
COPY config/msmtprc /usr/local/etc/php/
RUN chmod 600 /usr/local/etc/php/msmtprc \
&& chown www-data:www-data /usr/local/etc/php/msmtprc

# Remove all default site files in /var/www/html
RUN rm -fR /var/www/html/*

# Copy ProcessWire core files
COPY ProcessWire/wire /var/www/html/wire
COPY ProcessWire/index.php /var/www/html/index.php
COPY ProcessWire/htaccess.txt /var/www/html/.htaccess

# Copy site-specific files
COPY site /var/www/html/site

# Make www-data the owner of site-specific files
RUN chown -R www-data:www-data /var/www/html/site

VOLUME /var/www/html/site

account celedev-webmaster
tls on
tls_certcheck off
auth on
host smtp.celedev.com
port 587
user webmaster@celedev.com
from webmaster@celedev.com
password thepasswordofwebmasteratceledevdotcom

sendmail_path = /usr/bin/msmtp -C /usr/local/etc/php/msmtprc --logfile /var/log/msmtp.log -a celedev-webmaster -t

docker build -t php-5.6-pw-celedev .

docker run --name celedev-data php-5.6-pw-celedev echo "Celedev site data-only container"

docker run --name celedev-site -p 8088:80 --link database:mysql --volumes-from celedev-data -d php-5.6-pw-celedev

docker run --name celedev-site -p 8088:80 --link database:mysql -v /Users/jean-luc/web/test-docker:/hostdir --volumes-from celedev-data -d php-5.6-pw-celedev

bash-3.2$ docker images
REPOSITORY            TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
php-5.6-pw-celedev    latest              2aaeb241c2e2        3 hours ago         1.149 GB
nazarpc/phpmyadmin    latest              e25cd4fd48b3        8 days ago          521 MB
mariadb               latest              dd208bafcc33        2 weeks ago         302.2 MB
debian                latest              9a61b6b1315e        5 weeks ago         125.2 MB

bash-3.2$ docker ps -a
CONTAINER ID        IMAGE                 COMMAND                  CREATED             STATUS                    PORTS                                         NAMES
68cc5d976f0d        php-5.6-pw-celedev    "apache2-foreground"     20 hours ago        Up 20 hours               443/tcp, 0.0.0.0:8088->80/tcp                 celedev-site
0729fe6d6752        php-5.6-pw-celedev    "echo 'Celedev site d"   20 hours ago        Exited (0) 20 hours ago                                                 celedev-data
e3e9e3a4715c        mariadb               "/docker-entrypoint.s"   3 days ago          Up 3 days                 3306/tcp                                      database

bash-3.2$ docker run --rm -it --volumes-from celedev-data -v /Users/jean-luc/web/test-docker:/hostdir debian /bin/bash

root@2973c5af3eaf:/# cd /var/www/html/
root@2973c5af3eaf:/var/www/html# tar cvf /hostdir/backup.tar site
root@2973c5af3eaf:exit

bash-3.2$

bash-3.2$ docker tag 2aaeb241c2e2 php-5.6-pw-celedev:0.11

bash-3.2$ docker images
REPOSITORY            TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
php-5.6-pw-celedev    latest              2aaeb241c2e2        3 hours ago         1.149 GB
php-5.6-pw-celedev    0.11                2aaeb241c2e2        3 hours ago         1.149 GB
nazarpc/phpmyadmin    latest              e25cd4fd48b3        8 days ago          521 MB
mariadb               latest              dd208bafcc33        2 weeks ago         302.2 MB

bash-3.2$ docker save php-5.6-pw-celedev:0.11 | gzip > php-5.6-pw-celedev-0.11.tar.gz 

I just finished creating a simple Contact-Form for a client's website so i thought it would be really helpfull to share it with the community.

The contact form uses:

• Google recaptcha for validating the user is not a robot (https://github.com/google/recaptcha)
• Valitron validation library for validating the form fields (https://github.com/vlucas/valitron)
• Twitter Bootstrap 3.0.0 for form HTML

The contact-form is located inside a contact-page, so the bare minimum you need in order to setup your own is:

1. contact.php (template file used by your contact-page)
2.  _contact-controller.php (file used as a controller for your contact-form functionality like send email, validate fields etc)
3. 2 extra lines inside your composer.json file

So, let's start:

First you need to update your composer.json file adding 2 lines inside the require object:

"vlucas/valitron": "^1.2",
"google/recaptcha": "~1.1"

Here is a sample composer.json file:

{
  "name": "processwire/processwire",
  "type": "library",
  "description": "ProcessWire CMS/CMF",
  "keywords": [ "cms","cmf", "content management system" ],
  "homepage": "https://processwire.com",
  "authors": [
    {
      "name": "Ryan Cramer",
      "email": "ryan@processwire.com",
      "homepage": "https://processwire.com",
      "role": "Developer"
    }
  ],
  "require": {
    "php": ">=5.3.8",
    "ext-gd": "*",
    "vlucas/valitron": "^1.2",
    "google/recaptcha": "~1.1"
  },
  "autoload": {
    "files": [ "wire/core/ProcessWire.php" ]
  },
  "minimum-stability": "dev"
}

open console and navigate to processwire root folder (where composer.json file is)
on this step i assume you have already setup composer for your project, otherwise google it 
run the following command:

composer update

this will create a vendor folder (if it does not already exist) and download valitron and google recaptcha libraries.

Then open your contact-page template file(usually named contact.php inside your templates directory) and add the following:
* Note: The form below uses bootstrap 3.0.0 css, so if you are using something else you need to make the appropriate changes.

<?php namespace ProcessWire;
include('_contact-controller.php')
?>
<div class="container">
	<div class="row">
		<div class=" col-md-4">
            <h2>Contact Form</h2>

            <?php if($session->flashMessage):?>
            <div class="alert <?=!$session->sent && (!$v->validate() || !$resp->isSuccess()) ? 'alert-danger' : 'alert-success'?>" role="alert">
              <?php echo $session->flashMessage;?>
            </div>
            <?php endif;?>

            <form id="contact-form" method="post">
                <div class="form-group <?=$v->errors('name') ? 'has-error' : ''?>">
                    <label for="name">Name</label>
                    <input class="form-control" name="name" id="name" type="text" value="<?=$sanitizer->text($input->post->name)?>">
                </div>
                <div class="form-group <?=$v->errors('email') ? 'has-error' : ''?>">
                    <label for="email">Email</label>
                    <input class="form-control" name="email" id="email" type="text" value="<?=$sanitizer->text($input->post->email)?>">
                </div>
                <div class="form-group <?=$v->errors('message') ? 'has-error' : ''?>">
                    <label for="message">Message</label>
                    <textarea class="form-control" name="message" id="message"><?=$sanitizer->text($input->post->message)?></textarea>
                </div>
                <div class="form-group">

                    <!-- Google Recaptcha code START -->
                    <div class="g-recaptcha" data-sitekey="<?=$googleSiteKey?>"></div>
                    <script type="text/javascript"
                            src="https://www.google.com/recaptcha/api.js">
                    </script>
                    <!-- Google Recaptcha code END -->

                </div>
                <button type="submit" class="btn btn-primary">SEND</button>
            </form>
      	</div>
    </div>
</div>
<?php
    //here we remove the flash-message because it is already shown above the form.
    $session->remove('flashMessage');
    //reset 'sent' variable for future submit
	$session->sent = false;
?>

Next create a file inside you templates directory with name: _contact-controller.php:
and set the required variables($googleSiteKey, $contactFormRecipient, $contactPageID)

<?php
namespace ProcessWire;

/**
*    here we include Valitron & Google recaptcha libraries
*    make sure the path is correct in your template
*/
include(dirname(__FILE__) . "/../../vendor/vlucas/valitron/src/Valitron/Validator.php");
include(dirname(__FILE__) . '/../../vendor/google/recaptcha/src/ReCaptcha/ReCaptcha.php');

/**
*    here we add the form field values to Valitron
*/
$v = new \Valitron\Validator(array(
        'name' => $sanitizer->text($input->post->name),
        'email' => $sanitizer->email($input->post->email),
        'message' => $sanitizer->text($input->post->message),
    )
);

/**
*    validation rules set for each form field
*    For more details on Valitron/Validator usage visit: 
*    https://github.com/vlucas/valitron
*/
$v->rule('required', ['name', 'email', 'message']);
$v->rule('lengthMin', 'name', 5);
$v->rule('email', 'email');

/**
*    set Google recaptcha site-key & secret-key
*    create a new key from: https://www.google.com/recaptcha/admin
*/
$googleSiteKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$googleSecretKey = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY';

/**
*    set the email of the contact form recipient(usually the website owner)
*/
$contactFormRecipient = 'your@company.com';

/**
*    set the id of contact-page in order to redirect there when the form is sent
*/
$contactPageID = '1045';

//here we check whether the 'name' field exists inside post variables (which means the form is posted)
if ($input->post->name) {

    //if fields validation passes
    if ($v->validate()) {

        $reCaptcha = new \ReCaptcha\ReCaptcha($googleSecretKey);
        $resp = $reCaptcha->verify($input->post->{'g-recaptcha-response'}, $_SERVER["REMOTE_ADDR"]);

        //if google-recaptcha validation passes
        if ($resp->isSuccess()) {
        
            //This is the HTML message
            $message = '
                <html>
                    <head>
                        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
                        <title>Contact Form | ' . $input->post->name . '</title>
                    </head>
                    <body>
                        <p>' . $input->post->message . '</p>
                    </body>
                </html>';

            //here we send the form to $contactFormRecipient
            wireMail($contactFormRecipient, $input->post->email, "Contact Form | " . $input->post->name, $message);
            
            //here we set a flash-message to notify the user that the form was successfully sent
            $session->flashMessage = 'Thank you for your message! We will get in touch with you shortly.';
            
            //save in session that the form is sent
			$session->sent = true;

            //finally redirect user to contact-page
            $session->redirect($pages->get($contactPageID)->url);
        } else {
            //self explain
            $session->flashMessage = 'Error while validating you are not a robot!';
        }
    }
}
?>

Thats all!
You now have a simple contact-form working with captcha and field validation!
I would be more than happy to help anyone having problems on the setup.
 

• hundreds of fields
• tens of thousands of pages (let's focus on orders)
• listers (again, let's focus on my "Orders" lister)
• many filters on listers (my Orders lister has about 20 filters)

When you load a ListerPro lister page, it technically does 2 requests:

• first request is to build the interface
• second request (ajax) loads the results based on the filters, etc.

I noticed it became very slow over time, but I didn't look into it deeply until now.

Even though I have thousands of order pages, that's actually not the issue.

First, part of the issue is what type of page reference fields you are using, which I wrote a tutorial about, so make sure to view that as well. (also keep in mind TracyDebugger slows things down a lot here as well)

But even with that, it's still slow on the first request.  It would take 8-14 seconds to load a ListerPro page on the first request!

The issue?  Having too many filters (20 for example) combined with the fact my site has hundreds of fields means that generating that filters list is incredibly intensive.  That filters list is powered by the InputfieldSelector field.

I worked with DeepSeek and it came up with a simple solution: when rendering the field list (ie, the first dropdown in InputfieldSelector), don't show every single field as an option... instead only grab the fields that I have actually used.  This keeps the InputfieldSelector field working correctly, but eliminates a bunch of fields I wouldn't have wanted to use in my filters anyway.  So, we're sacrificing a little (unneeded) flexibility for extreme performance gain. Now my ListerPro page loads in less than a second!

Use this hook in ready.php:

if(wire('page')->process == 'ProcessPageListerPro' && !wire('config')->ajax && wire('input')->urlSegment1 !== 'config') {
  
    wire()->addHookBefore('InputfieldSelector::render', function($event) {
        $is = $event->object;
        
        // Don't interfere if limitFields was already explicitly configured
        $existing = $is->limitFields;
        if(!empty($existing)) return;
        
        // Parse field names from the current selector value
        $value = (string) $is->attr('value');
        if(!strlen($value)) return;
        
        $fieldNames = [];
        try {
            $selectors = wire(new \ProcessWire\Selectors($value));
            foreach($selectors as $s) {
                foreach($s->fields as $field) {
                    if(strpos($field, '.') !== false) {
                        list($field,) = explode('.', $field, 2);
                    }
                    $fieldNames[$field] = $field;
                }
            }
        } catch(\Exception $e) {
            return;
        }
        
        // Always include system fields (needed for the template row)
        foreach(['id','name','title','template','parent','status',
                 'created','modified','published','path','has_parent',
                 'created_users_id','modified_users_id','num_children',
                 'count','include','limit','sort','_custom'] as $f) {
            $fieldNames[$f] = $f;
        }
        
        if(count($fieldNames)) {
            $is->set('limitFields', array_values($fieldNames));
        }
    });
}

Let's say I have a repeater field called "order_line_items" and I want to create a page reference field called "order_line_item" that allows me to select a repeater item (which is a page) of the "order_line_items" repeater field.

Repeater pages are a bit different from regular pages in that their "parent" is a container admin page associated with the page in which it exists (dig into /admin/repeaters/order_line_items/ in your page tree to see what I mean).  So when you are configuring your page reference field, you can't really choose a Parent.  However when configuring your field, your instinct would be to choose the Template of "repeater_order_line_items".

Then because you need extra precision in what pages are actually available for selection (rather than all of them across all pages), your instinct will be to implement custom PHP code:

$wire->addHookAfter('InputfieldPage::getSelectablePages', function($event) {
  if($event->object->hasField == 'order_line_item') {
    $event->return = $event->pages->find('your selector here');
  }
});

The problem with that approach is that even though you have defined the custom PHP code and the select field correctly shows the selectable repeater pages in the select field, behind-the-scenes, ProcessWire has still loaded EVERY SINGLE REPEATER that has the "repeater_order_line_items" template (you can see this is TracyDebugger's pages loaded list)!  Your site will definitely be slower as a result, dramatically so if you have thousands or tens of thousands of repeater pages of that template.

I hit this issue years ago (2018) and I thought it was a bug.  I discussed it with Ryan and it's technically not a bug, but kind of the way ProcessWire works, which is beyond this tutorial.

While you can circumvent this using the PageAutocomplete field, I don't like the ergonomics of that field in certain situations.  I want the good-old select field.

The solution to this is to NOT select anything for the "Template" when configuring your field.  So in my example, I chose "repeater_order_line_items", but instead, it should be left blank.

Now the field will just rely on the code portion and all the unnecessary page loads will be eliminated.

Obviously you need to install pngquant (https://pngquant.org/) first and exec() can't be disabled.

$wire->addHookAfter('Pageimage::size', function(HookEvent $event) {
    $img = $event->return; // the resized Pageimage variation
    $path = $img->filename;
    
    // Only process PNGs
    if (strtolower(pathinfo($path, PATHINFO_EXTENSION)) !== 'png') return;
    
    // Skip if already optimized (optional marker file approach)
    $marker = $path . '.pngquant';
    if (file_exists($marker)) return;
    
    // Run pngquant (overwrites in place, quality 65-80)
    $cmd = sprintf(
        'pngquant --quality=65-80 --force --output %s -- %s 2>&1',
        escapeshellarg($path),
        escapeshellarg($path)
    );
    exec($cmd, $output, $returnCode);
    
    // Mark as optimized so we don't re-process on subsequent calls
    if ($returnCode === 0 || $returnCode === 99) {
        // 99 = quality target not met, kept original
        touch($marker);
    }
});

First of all I had no idea, which category would fit best ...

I'd like to share a little tool I've been working on to make the initial setup of ProcessWire even faster, especially when working on remote servers without SSH access.

What is it? kickstart.php is a modern, single-file installer/loader for ProcessWire. Instead of uploading thousands of files via FTP, you just upload this one file and it handles the rest.

Key Features:

• Version Selection: Choose between the master (stable) or dev branch directly from GitHub.

• Smart Multi-Language: Built-in support for English, German, Spanish, and French (with automatic browser language detection).

• Modern UI: Built with Tailwind CSS, AlpineJS, and smooth animations using Anime.js.

• Pre-flight Checks: Automatically checks for PHP version requirements and prevents overwriting existing installations.

• Automatic Cleanup: Removes the downloaded ZIP archive and temporary folders after extraction.

How to use it:

1. Upload kickstart.php to your webroot.

2. Open it in your browser.

3. Choose your version and click install.

4. Once finished, click the button to start the official ProcessWire installer.

I hope some of you find this useful for your workflow! Feedback and suggestions are always welcome.

Cheers, Markus

kickstart.php

Improved Version now available on GitHub: https://github.com/markusthomas/ProcessWireKickstart

I use .env files on every ProcessWire project to manage environment-specific configurations and settings. I've built a ProcessWire specific utility that makes using .env files a breeze. This post isn't intended to debate .env vs. config.php, use what you're comfortable with and prefer. That said, here are a few benefits to using .env files that may make it worth considering:

• Native support on web servers, including Apache, they are not served via http request by default
• True environment based secrets and settings management
• A standard file widely used and accepted as the method for managing secrets and sensitive values
• Able to store any value whether sensitive or not and access them globally

Building a dedicated solution came from a discussion here on the forums where I threw together a rough implementation that needed little polish for real world use. It makes use of phpdotenv.

This utility delivers the following:

• Easy use of and access to .env variables
• Caching the parsed .env for performance. This is a significant part of this utility and addresses a known need
• Automatic .env change recognition and re-caching
• Utilities to make working with environment variables feel ProcessWire native and a few extra nifty things

What it isn't:

• A module. It's not possible to make a module for this need because the information kept in a .env file needs to be available before ProcessWire boots.

Adding this to a new or existing project is very easy. It's designed to implement quickly and use immediately in your projects. Full documentation is provided in the Github repository.

Here are a few examples of using this tool:

<?php namespace ProcessWire;

use Env\Env;

if(!defined("PROCESSWIRE")) die();

$env = Env::load(__DIR__ . '/../');

// Make env available throughout the application
$config->env = $env;

$config->dbName = $env->get('DB_NAME');
$config->dbUser = $env->get('DB_USER');
$config->dbPass = $env->get('DB_PASS');

// Env::get() takes a second argument that is the fallback value if for any reason DEBUG doesn't exist 
$config->debug = $env->get('DEBUG', false);

// Conditional values. By default, if the condition is falsey, Env::if() returns null   
$config->adminEmail = $env->if('APP_ENV', 'production', 'you@youremail.com');

// A fourth argument will be returned if condition is false, truthy/falsey output can be env var names or specific values
$config->adminEmail = $env->if('APP_ENV', 'production', 'ADMIN_EMAIL', 'you@youremail.com');

// Conversely, you can also check if a condition is not met.
$config->adminEmail = $env->ifNot('APP_ENV', 'development', 'ADMIN_EMAIL');

// Use one env value to set multiple config properties
$config->advanced = $env->if('APP_ENV', 'production', false, 'ENABLE_ADVANCED'); // Never in production, change locally in env as needed
$config->adminEmail = $env->ifNot('APP_ENV', 'development', 'ADMIN_EMAIL'); // Never send an email in dev, always on staging/production

These helper methods make is very straightforward to implement a dynamic config file. This can be useful for using secure .env values while retaining the ability to commit and upload some types of changes to your config.php file without needing to touch .env values on the server.

You can also use Env::pushToConfig(). As long as you use the "screaming snake case" naming convention for your environment variable names, type and value recognition are handled automatically.

<?php

$env->pushToConfig($config, [
    'usePageClasses' => true,
    'templateCompile' => 'TEMPLATE_COMPILE',
    'debug' => ['DEBUG', false], // Fallback to false
    'advanced' => $env->if('APP_ENV', 'production', false, 'ENABLE_ADVANCED'),
    'adminEmail' => $env->ifNot('APP_ENV', 'development', 'ADMIN_EMAIL'),
    'httpHosts' => [
        'something.com',
      	'staging.something.com',
        'something.ddev.site'
    ],
]);

Using Env in your application files and templates can be very useful. In the above example we assigned the Env object to $config->env. This lets you access your .env variables globally and use some helpful methods.

<?php if ($config->env->eq('APP_ENV', 'development')): ?>
  <script src="/some/development/stuff.js"></script>
<?php endif ?>

<?php
if (!$config->env->exists('GOOGLE_API_KEY')) {
  $wire->error('A Google API key could not be loaded from the environment file.');
}

try {
  // Do something that could fail	
} catch (Exception $e) {
    $message = $config->env->if('APP_ENV', 'production', 'Oh no. Friendly message here', $e->getMessage());
}

This utility also automatically casts 'true' and 'false' values in .env files to booleans, and casts numbers to integers. It also includes several configuration options.

I have been using this tool in production and have been happy with it. Maybe you might find it helpful in your projects as well. If you like it, throw a star on the repo. If you run into any bugs, file an issue on Github. I may publish it as a composer package at some point.

Env utility for ProcessWIre on Github.

$m = new WireMail();
$m->from('foo@bar.com');
$m->to('xxx@yyy.com');
$m->subject('Hello there!');
$m->bodyHTML('<h1>This is great!</h1><p>I am an ugly mail...</p>');
$m->send();

But let's be honest - they look about as pretty as a website built with Microsoft FrontPage! 😅

🪄 Enter the Mail Pimp Hook!

Drop this magical hook into your /site/ready.php (or even better Site.module.php), and watch your emails transform from ugly ducklings into beautiful swans:

<?php
$wire->addHookBefore('WireMail::send', function(HookEvent $event) {
  // double check that we got a wiremail instance
  // this also tells the IDE what $mail is (to get IntelliSense)
  $mail = $event->object;
  if (!$mail instanceof WireMail) return;
  
  // get current mail body
  $html = $mail->get('bodyHTML');
  if (!$html) return;
  
  // get email layout markup
  $layoutFile = wire()->config->paths->templates . 'mails/default.html';
  if (!is_file($layoutFile)) return;
  
  // replace ##content## with actual mail content
  $html = str_replace(
    '##content##',
    $html,
    wire()->files->render($layoutFile)
  );
  
  // write new body to mail
  $mail->bodyHTML($html);
});

The HTML

Just create a beautiful MJML template at /site/templates/mails/default.mjml, put ##content## where your email content should go, convert it to HTML and BOOM! 💥 Every email gets automatically wrapped in your gorgeous template.

No more CSS wrestling matches, no more "Why does this look different in Outlook?" headaches. Just pure email beauty, automagically! ✨

Now your clients will think you spent days crafting those emails, when in reality, you're sipping coffee while your hook does all the heavy lifting. Work smarter, not harder! 🚀

#ProcessWire #EmailMagic #NoMoreUglyEmails

PS: This is the MJML template that I used:

<mjml>
  <mj-head>
    <mj-attributes>
      <mj-all font-family="Tahoma" />
      <mj-text line-height="140%" />
    </mj-attributes>
  </mj-head>
  <mj-body background-color="#efefef">
    <mj-section
      background-color="#ffffff"
      background-repeat="repeat"
      padding-bottom="30px"
      padding-top="30px"
      text-align="center"
    >
      <mj-column>
        <mj-image
          align="center"
          padding="25px"
          src="xxx"
          target="_blank"
          width="200px"
          alt="Logo"
        ></mj-image>
        <mj-text>##content##</mj-text>
      </mj-column>
    </mj-section>
    <mj-section>
      <mj-column>
        <mj-text
          font-size="10px"
          color="#a0a0a0"
          align="center"
        >
          powered by
          <a
            href="https://www.baumrock.com/"
            style="color: #158f66"
            >baumrock.com</a
          >
        </mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

VSCode has an extension to get a live preview and export MJML to HTML:

And here are some other free templates: https://mjml.io/templates

I use https://www.base64-image.de/ to add the logo to my mail template as src="data:image/jpeg;base64,/9j/4QAWRXhpZgAATU0AKgAAAA..." to avoid headaches with image paths, remote assets blocking etc.

The problem with this however if that you must be very careful because if you do not represent a field of that repeater (and represent it correctly with the correct form "name"), then ProcessWire will wipe out the data because it expects it to exist when saving!!!  This includes the "native" fields for a repeater item (which are "loaded", "sort" and "publish").  THOSE MUST ALSO BE REPRESENTED!

For fields in your repeater that are hidden however, they do not need to be represented, so you can ignore rendering those.

You have to be very careful here because you may one day decide to add a new field to a repeater and keep it as "Open", and forget this requirement and not add it to the your custom renderer.  Then if you wrote data to the field in some way, and then a user went to edit a page that contains that repeater field and they save, your data will get wiped out!

But sometimes I don't want to hunt around through Page List to find the page I want to copy, and instead I have found the page via the admin search and have it open in Page Edit. So I used this hook in /site/ready.php to add a "Clone this page" button to the bottom of the Settings tab.

// Add a clone button to the Settings tab of Page Edit if this page is allowed to be cloned
$wire->addHookAfter('ProcessPageEdit::buildFormSettings', function(HookEvent $event) {
	$wrapper = $event->return;
	$modules = $event->wire()->modules;
	$page = $event->process->getPage();
	/** @var ProcessPageClone $ppc */
	$ppc = $modules->get('ProcessPageClone');
	if($page && $ppc->hasPermission($page)) {
		/** @var InputfieldButton $f */
		$f = $modules->get('InputfieldButton');
		$f->value = 'Clone this page';
		$f->href = $event->wire()->config->urls->admin . 'page/clone/?id=' . $page->id;
		$wrapper->add($f);
	}
});

Maybe somebody else has this need and finds this useful.

The script hook is automatically injected before the </body> tag in your HTML. It periodically checks for any file or page updates in your system at the interval you specify. If the previous check time is older than the new check time (indicating changes), the page automatically refreshes.

~/site/ready.php

if ($wire->config->debug) {

    $wire->addHookAfter('Page::render', function (HookEvent $event) {
        $script = <<<HTML
        <script>
        const browserSync = {
            mtime: 0,
            init() {
                this.sync();
            },
            sync() {
                fetch('/browser-sync')
                .then(response => response.json())
                .then(data => {
                    if (!this.mtime) {
                        this.mtime = data.max;
                    } else {
                        if (data.max > this.mtime) {
                            location.reload();
                            }
                        }
                    });
                }
            };
            browserSync.init();
            setInterval(() => browserSync.sync(), 2500);
        </script>
        HTML;

        $event->return = str_replace('</body>', "{$script}</body>", $event->return);
    });

    $wire->addHook('/browser-sync', function (HookEvent $event) {

        $wire = $event->wire();
        $root = $wire->config->paths->root;
        $siteRoot = $wire->config->paths->site;
        $extensions = '*.{php,js,css}';

        $paths = [
            "{$root}src/{$extensions}", // custom composer package
            "{$root}src/src/{$extensions}", // custom composer package
            "{$siteRoot}{$extensions}", // ready.php, init.php, finished.php
            "{$siteRoot}classes/{$extensions}", // page classes
            "{$siteRoot}templates/{$extensions}",
            "{$siteRoot}templates/*/{$extensions}",
            "{$siteRoot}templates/*/*/{$extensions}",
            "{$siteRoot}templates/*/*/*/{$extensions}",
            "{$siteRoot}templates/*/*/*/*/{$extensions}",
        ];

        $files = [];
        foreach ($paths as $pattern) {
            // Try with GLOB_BRACE first
            $result = glob($pattern, GLOB_NOSORT | GLOB_BRACE);
            // If no results with GLOB_BRACE, try without it
            if (!$result) {
                $result = glob($pattern, GLOB_NOSORT) ?: [];
            }
            $files = array_merge($files, $result);
        }

        $filemtime = 0;
        foreach ($files as $file) {
            if (!is_file($file)) {
                continue;
            }
            try {
                $mtime = @filemtime($file);
                if ($mtime && $mtime > $filemtime) {
                    $filemtime = $mtime;
                }
            } catch (\Exception $e) {
                continue;
            }
        }

        $latest = $wire->pages->get('sort=-created|-modified');
        $latestTime = $latest->modified > $latest->created ? $latest->modified : $latest->created;
        
        header('Content-Type: application/javascript');
        echo json_encode([
            'max' => max($filemtime, $latestTime),
            'mtime' => $filemtime,
            'modified' => $latest->modified,
            'created' => $latest->created
        ]);
        exit;
    });
}

This development tool helps streamline your workflow by automatically refreshing the browser when you make changes to your files or content, eliminating the need for manual page refreshes during development.

The formatting expectation for the jQuery-UI datetime picker component is a string value that always has a negative value, a colon separator, and a positive value, indicated by "-x:+y".

The solution here is simple, but in case anyone else runs into this problem, it just takes the following form instead:

yearRange="-0:+2"

Simply include the negative sign in front of the zero! 🤦‍♂️

Before:

After:

<?php

public function init(): void
{
  wire()->addHookBefore('Inputfield::render', $this, 'changeFieldType');
}

public function changeFieldType(HookEvent $event): void
{
  $f = $event->object;
  $colorFields = [
    Site::field_col_primary,
    Site::field_col_secondary,
    Site::field_contrast_primary,
    Site::field_contrast_secondary,
  ];
  if (!in_array($f->name, $colorFields)) return;
  $f->attr('type', 'color');
}

So right before the text input is rendered we change its "type" property to "color" and the browser will render a default color picker 😎

It once more shows how versatile ProcessWire is. And maybe it helps someone... 🙂 

PS: Be advised that with that hack you only modify the optics of the field. The field will under the hood still be a regular text field, which means you'll not get any sanitisation or such from it and you might have to take care of that on your own. In my case it's a superuser-only settings page. So it is no issue at all.

<a download href="my-awesome-file.jpg">Download</a>

What I didn't realize until today is that you can actually specify a filename as a value for the download attribute like this which will automatically use that filename instead!:

<a download="my___awesome___file.jpg" href="my-awesome-file.jpg">Download</a>

This is incredibly convenient because it means if I want a user to download the same exact file 3 times but with specific filenames for each, I can just do this:

<a download="my___awesome___file-1.jpg" href="my-awesome-file.jpg">Download 1</a>
<a download="my___awesome___file-2.jpg" href="my-awesome-file.jpg">Download 2</a>
<a download="my___awesome___file-3.jpg" href="my-awesome-file.jpg">Download 3</a>

Furthermore, as you can see, I am using a triple underscore which ProcessWire cleans up and changes to a single underscore, as well as other changes (such as lowercasing everything) when uploading to a pagefile field.  I want my filenames to be exactly as I upload and I know there's ways to prevent ProcessWire from doing that, but using the download attribute in the way I described works perfectly for my use case.

Basically the hook just replaces render() with a modified version. The key modifications are to select all the items without limit:

		$items = $event->arguments(0);  //PageArray
		$itemSelector = $items->getSelectors(true);  // true returns the string rather than the object
		$noLimit = preg_replace('/,\s*limit=-?\d+/i', '', $itemSelector);

and then to modify the pager:

		$pagerNav = new PagerNav($object->totalItems, $object->itemsPerPage, $object->pageNum);
		$pagerNav->setLabels($objectOptions['previousItemLabel'], $objectOptions['nextItemLabel']);
		$pagerNav->setNumPageLinks($object->numPageLinks);
		$pager = $pagerNav->getPager();
		$allItems = $this->find($noLimit)->explode('title');
		$itemsPerPage = $object->itemsPerPage;
		foreach($pager as $key => $item) {
			if(!ctype_digit("$item->label")) continue;
			$index = (int) $item->label;
			$itemTitle = $allItems[($index - 1) * $itemsPerPage];
			$item->label = substr($itemTitle, 0, 2);
		}

If anyone wants the full hook code, let me know, but you will probably want to modify it for your own use anyway and the above are the key bits.

Something that looks like this:

Requirements:

1. Use the Fieldtype Cache to create a search index

For fast and easy search queries we will create a search index field. You can read more on this here: https://processwire.recipes/recipes/set-up-search-index-with-fieldtypecache/

1. First of all, go to Modules and install a Core module called FieldtypeCache.
2. Add a new field “search_cache” and select “Cache” as it’s type. Save the field.
3. On the Details tab choose the fields you want to make searchable. Save again.
4. Add “search_cache” to all templates you want to include in your search results.
5. Optional but recommended: use the “Regenerate Cache” option found from the Details tab of the field to make existing content instantly searchable.

In my case i only want to search inside body and title fields, so I included those fields in the settings of the search cache field:

2. Install the Pages2JSON module

We want to make ajax requests to the search template and those results should be returned in JSON format so that our java script can process the results inside the auto-complete dropdown. Therefore we make use of this module here:

https://processwire.com/modules/pages2-json/

In the module settings we define what data will be included in the JSON object that is returned. Remember that this is the data that we want to display in our auto-complete dropdown. So for my case I only want the title and the url field.

Now let's start:

1. Setting up the search template

Set up a template file called „search“. Then create a page using this template. On most ProcessWire installations this is already the case and this template exits in the file system. This template will handle the search queries and list all the results for us and that in two ways:

- you can send a search query and the search result page will list all the results (as you would expect)

- you can send an ajax search query and the result page will return the results as a json object to be processed within javascript and displayed in the frontend in real-time

search.php:

<?php
if($config->ajax) {
    // Return search results in JSON format
    $q = $sanitizer->selectorValue($input->get->q);
    $results = $pages->find('search_cache%=' . $q);; // Find all pages and save as $results
    header("Content-type: application/json"); // Set header to JSON
    echo $results->toJSON(); // Output the results as JSON via the toJSON function
    return $this->halt();
}
?>
<main>
  <div class="uk-container">
    <?php

    // look for a GET variable named 'q' and sanitize it
    $q = $sanitizer->selectorValue($input->get->q);

    // did $q have anything in it?
    if($q) {

      // Find pages that match the selector
      $matches = $pages->find('search_cache%=' . $q);

      // did we find any matches? ...
      if($matches->count) {

        echo "<h2>We found $matches->count results:</h2>";

        echo "<ul class='uk-list uk-list-square'>";

        foreach($matches as $match) {
          echo "<li><a href='$match->url'>$match->title</a>";
          echo "<div class='summary'>$match->summary</div></li>";
        }

        echo "</ul>";

      } else { ?>
    <h2>No results found.</h2>
    <div uk-grid class="uk-flex uk-flex-center">
      <div class="uk-width-1-1 uk-width-1-2@m">
        <?= $files->render('elements/_searchbox'); ?>
      </div>
    </div>
    <? }

    } else { ?>
    <h2>Search:</h2>
    <div uk-grid class="uk-flex uk-flex-center">
      <div class="uk-width-1-1 uk-width-1-2@m">
        <?= $files->render('elements/_searchbox');  ?>
      </div>
    </div>
    <? } ?>
  </div>
</main>

Explanation:

This part here at the top of the template handles the requests that are send via ajax. This is the important part for later on.

<?php

if($config->ajax) {
    // Return search results in JSON format
    $q = $sanitizer->selectorValue($input->get->q);
    $results = $pages->find('search_cache%=' . $q);; // Find all pages and save as $results
    header("Content-type: application/json"); // Set header to JSON
    echo $results->toJSON(); // Output the results as JSON via the toJSON function
    return $this->halt();
}
?>

What this does:

1. check if the current request is an ajax request
2. if so, search inside the search cache field
3. return the results in JSON format
4. then quit processing the rest of the template (we don’t want to render any markup in that case!)

Everything below this part is the normal search template logic. If you send a search request via a form somewhere on the website you want to be redirected to the result page and all the results will be listed on the page just like you would expect.

2. Make the search „work“

Create a template file called "_searchbox.php" (this file is also included in the search template code above, so adjust your paths/names accordingly).

To make search requests you want to include this search form anywhere on your page.

_searchbox.php:

<div class="search-wrapper uk-padding uk-text-center">
    <h4>Searchbox</h4>
    <form class="searchform uk-position-relative uk-flex" method="get" action="<?= $pages->get("template=search")->url ?>">
        <input class="uk-input" id="searchInput" name="q" type="search" aria-label="Suchen" autocomplete="off" placeholder="z.B. Bagger">
        <button class="uk-button uk-button-primary search-button" type="submit">
            <span class="uk-visible@s">Search</span>
        </button>
        <div id="suggestions" class="uk-box-shadow-medium">
        </div>
    </form>
</div>

With this simple search form you should now be able to do a basic search that leads you to a search result page.

3. Make the ajax-search „work“

Now comes the interesting part. We will add in a java script snippet into our just created _searchbox.php that sends ajax requests to the search template page while we are typing into the search intput field and it will display the results in a nice little dropdown. 

Feel free to adjust the code to your needs!

<script>
  document.addEventListener("DOMContentLoaded", () => {

    const searchForm = document.querySelector('.searchform');
    const searchUrl = searchForm.getAttribute('action');

    const searchInput = document.getElementById('searchInput');
    const suggestionsDiv = document.getElementById('suggestions');
    let selectedSuggestionIndex = -1;

    // close the auto-complete container when clicked outside the element
    document.addEventListener('click', function(event) {
      if (!suggestionsDiv.contains(event.target)) {
        suggestionsDiv.style.display = 'none';
      }
    });

    searchInput.addEventListener('input', () => {

      const searchText = searchInput.value.toLowerCase();

      // Immediately Invoked Function Expression (IIFE)
      (async () => {

        try {
          const response = await fetch(searchUrl+"?q="+searchText, {
            headers: {
              'X-Requested-With': 'XMLHttpRequest'
            }
          });

          if (response.status === 200) {
            const data = await response.json();
            showResults(data);
          }
          else {
            console.log(response.status);
            console.log(response.statusText);
          }

        } catch (error) {
          console.error(error);
        }
      })();

      function showResults(data) {

        // Show suggestions only if the input has at least two characters
        if (searchText.length >= 2) {

          const suggestionHTML = data.map(item => {
            // Highlight the matching characters using a <span> element with a CSS class
            const highlightedTitle = item.title.replace(
              new RegExp(searchText, 'gi'),
              match => `<span class="highlight">${match}</span>`
            );
            return `<li class="suggestion"><a href="${item.url}">${highlightedTitle}</a></li>`;
          }).join(''); // Array to string conversion

          suggestionsDiv.innerHTML = ''; // Clear the suggestions if input length is less than two characters

          // create list and append search results
          const suggestionList = document.createElement("ul");
          suggestionList.classList.add('suggestion-list', 'uk-list');
          suggestionList.innerHTML = suggestionHTML;

          suggestionsDiv.appendChild(suggestionList);

          selectedSuggestionIndex = -1;

          // show the results
          suggestionsDiv.style.display = "block";
        } else {
          suggestionsDiv.innerHTML = ''; // Clear the suggestions if input length is less than two characters
        }
      }

    });

    // Event listener for arrow key presses
    searchInput.addEventListener("keydown", function (event) {
      const suggestions = document.querySelectorAll(".suggestion");

      if (event.key === "ArrowDown") {
        event.preventDefault();
        selectedSuggestionIndex = Math.min(
          selectedSuggestionIndex + 1,
          suggestions.length - 1
        );
      } else if (event.key === "ArrowUp") {
        event.preventDefault();
        selectedSuggestionIndex = Math.max(selectedSuggestionIndex - 1, -1);
      } else if (event.key === "Enter") {
        event.preventDefault();

        if (selectedSuggestionIndex === -1) {
          searchForm.submit();
        }
        else {
          window.location = suggestions[selectedSuggestionIndex].querySelector('a').href;
        }
      }

      // Highlight the selected suggestion
      suggestions.forEach((suggestion, index) => {
        suggestion.classList.toggle(
          "selected",
          index === selectedSuggestionIndex
        );
      });
    });
  });

</script>

Keep in mind that you need some CSS styes to make it look good and actually work. These are my styles(in LESS format) but feel free to write you own stylesheet for this.

search.less:

.search-wrapper {
  position: relative;
  background: @secondary-blue;

  h4 {
    color: @primary-blue;
  }

  .highlight {
    color: @primary-red;
  }

}

#suggestions {
  display: none;
  position: absolute;
  top: 100%;
  left: 0;
  right: 0;
  z-index: 10;
  background: @white;

  .suggestion-list {
    margin: 0;

    li {
      transition: background-color 150ms ease-in-out;

      a {
        padding: 10px;
        display: block;
        text-align: left;

        &:hover,
        &:focus,
        &:active {
          text-decoration: none;
        }
      }

      &:hover,
      &:focus,
      &:active,
      &.selected {
        background: @secondary-blue;
      }
    }

    li + li {
      border-top: 1px solid @secondary-blue;

    }
  }
}

That's it!

Again feel free to adjust all of the code to your needs. If you have any suggestions how to achieve things a bit easier just let me know.

//  Force login after successful password reset
$this->addHookAfter('ProcessForgotPassword::renderMessage', function(HookEvent $event) {
    $msg = $event->arguments(0);
    $input = wire('input');
    $session = wire('session');
    $pages = wire('pages');
    $page = wire('page');
	$users = wire('users');

    $return = $event->return;
    // This uses the module's default text. 
    // Adapt to suit on multi-language sites or if you want it to work for admins too
    if(stripos($msg, 'success') !== false && $page->template->name !== 'admin') {
        $userid = $input->get('u', 'int');
		$user = $users->get($userid);
		// limit access to specific users or roles
        if(!$user->isSuperuser() && $user->hasRole('login-register')) {
            $session->forceLogin($user);
            $session->redirect($pages->get("name=mypage")->url);
        }
    }
    $event->return = $return;
});

I didn't know how to do it, and I didn't find any other posts with a similar need or solution. When looking into the code I even thought that my need was not possible yet without modifying a core file. So I asked Ryan if he was willing to make the process of adding languages to the $languages array hookable.

Turns out that this is not necessary! All you have to do is to grab the Iterator of the languages array and remove languages as you need:

// /site/ready.php

if($anyCondition) {
  // remove CZ language
  $languages->getIterator()->remove("name=cz");
}

 So simple 😍 Maybe it helps 🙂 

If you're someone with experience, feedback is welcome! If there are better or more efficient ways to do something, I would love being a student. Some of these may either address challenges that others have experienced as well or were inspired by the awesome community sharing their solutions. Kudos to all of the people out there helping all of us. If someone sees something that was solved elsewhere please share it in the comments to give credit.

I have to make a disclaimer- these have worked for me and while most of them are ready to copy/paste, a few of them are going to need customization or tweaking to make them work for your use case. I don't currently have the resources (time) to provide a lot of support. Some of these were slightly rewritten or adapted for the examples. If you run into issues, the best thing to do is research the solution so that you know exactly what is happening in your application. If you adapt something, fix a bug, or address an edge case, it would be great if you can come back and share that.

Be smart, if you're going to run hooks that modify or create data, run a DB backup first. This is the part where I say "I'm not responsible if your site blows up". I don't think that's possible, but do the right thing.

There are dozens of hooks in the project I am sharing these from, and to manage that I created a file structure to handle this because there were far too many to put in one file and keeping the init.php and ready.php files clean really makes a huge difference in maintainability. Being able to jump between files by filename is a supremely efficient way to work as well. The filenames don't matter, they're there to identify the files and make it easy to locate/switch between them.

Here's my approach to directory organization:

/site
- hooks
-- HookUtils
-- init
-- lazy_cron
-- ready
- init.php
- ready.php

The ready.php file contents:

<?php namespace ProcessWire;

if(!defined("PROCESSWIRE")) die();

/** @var ProcessWire $wire */

// Import all ready hooks
foreach (glob(__DIR__ . '/hooks/ready/*.php') as $hook) {
  require_once $hook;
}

The init.php file contents:

<?php namespace ProcessWire;

if(!defined("PROCESSWIRE")) die();

/** @var ProcessWire $wire */

// Import all init hooks
foreach (glob(__DIR__ . '/hooks/init/*.php') as $hook) {
  require_once $hook;
}

// Import all LazyCron hooks, import after init hooks as there may be dependencies
foreach (glob(__DIR__ . '/hooks/lazy_cron/*.php') as $hook) {
  require_once $hook;
}

Operational Hooks

Here are some favorites.

Sort items in a Repeater matrix when a page is saved

This one helped sort RM items by a date subfield to help the user experience when editing pages. This implementation is configured to only fire on a specific template but can be modified to fire everywhere if modified to check that a field exists on the page being saved first. This was adapted from an answer here in the PW forum but can't find the original post, so I'm going to include it. If you're having issues getting items to sort the way you want, check out this post about natural sorting, which also works elsewhere in ProcessWire.

Github Gist

Automatically add a new child page when a page with a specific template is created

This automatically creates a new child page and saves it when a page having a specific template is created. This also has the ability to show a message to the user in the admin when new page(s) have been created by this hook. It is also error safe by catching any potential exceptions which will show an informative error to the admin user and log the exception message. The messaging/logging operation is abstracted to a separate object to allow reuse if creating multiple pages.

Github Gist

Conditionally show the user a message while editing a page

This one shows a message on a page with a specific template under specific conditions. May be page status, field value, type of user, etc. Visual feedback when editing complex pages can be very helpful, especially when an operation may or may not take place depending on factors like the values of multiple fields. This can reduce the amount of explanations needed on each field or training required for users to use a ProcessWire application. In my case, a message is shown if the state of a page indicates that another operation that is triggered by other hooks will or will not run, which is something that the user doesn't directly trigger or may not be aware of.

Github Gist

Show the user a message when viewing the page tree

This is intended to display a message, warning, or error when the page tree is viewed, such as on login, but in this case executes any time the main page tree is viewed to provide consistent communication and awareness. In my case it displays if there is an activity page located under an "Uncategorized" page for an event. This is something that may be buried in the page hierarchy and not noticeable, but if an activity isn't categorized, then is isn't visible on the website, and if it's not visible on the website, people aren't seeing it or buying tickets. So having a persistent message can bring visibility to important but otherwise potentially unnoticed issues. Or you can just say hi and something nice.

Github Gist

Hook Enhancement - Fast user switching

Hooks can run on triggers that vary widely. Some can and should be identified as those that are triggered by the current user, others may be more autonomous like executing via cron. There may be other hooks that are executed by a user that isn't logged in. Depending on the type of action and your need to identify or track it, switching from the current user to another user created specifically to handle certain tasks can be very helpful. ProcessWire tracks a number of things that are attributed to users- log entries note the user, the user that creates pages is stored, the user that last updated the page is stored, etc. You may want to know who did what when, or only take action if the last user that touched something was X and not Y.

I created a separate user that has been provided only the specific permissions it needs to complete jobs that are triggered by hooks or crons. Creating a user with less permissions may also help prevent accidental behaviors, or at least help you be very intentional in determining what actions are delegated. Creating custom permissions is also useful. With a dedicated user I can see explicitly that the last update on some pages were made by an autonomous script that syncs information between the ProcessWire application and a third party platform.

Github Gist - Fast user switcher

Github Gist - Example of switching users in a hook

Fast, powerful, and very (very) easy custom admin buttons

I needed a way to add custom interactive buttons that had some specific requirements.

• Needs to be a button that can be clicked by the user and does something
• Can be conditionally shown to the user with an alternate message if that action is not available
• Needs to do something on the server and interact with ProcessWire

Here's what that looked like for my application. The green "Refresh Activity" button in the top right. That's a custom button and you don't have to author an Inputfield module to get it. When a user clicks that button, it sends a request to the server with GET variables that are recognized in a hook, actions are taken, then a nice message indicating success or failure is shown to the user.

To do this you'll need to install FieldtypeRuntimeOnly and create a new field. Following the documentation for that field, create a button with a URL to the current page with GET variables appended. Then create a hook that watches for the specific GET variable that executes if it's present. Shoutout to @Robin S for helping make short work of a potentially complex task.

Note that the field code contains JS that handles the URL on page load. Since the hook is looking for a GET variable in the URL, using the back button or refreshing the page will cause the action to run twice. The JS in that example removes the entry from the browser history and also removes the GET parameter after the page loads if it's present.

Github Gist - An example gist for the hook that handles the action

Github Gist - An example of the FieldtypeRuntimeOnly code that is displayed and interacted with by the user.

Automatically convert logged object or array data to JSON

If you're using the outstanding Logs JSON Viewer (yet another great one by @Robin S module, then this hook makes for a thoroughly enjoyable logging experience. Using array or stdClass data when logging your values helps store additional information in an organized way

Github Gist

<?php

$log->save('log_name_here', 'Regular string message'); // Remains a string

$log->save('log_name_here', ['gets' => 'converted', 'to' => 'json']);

$log->save('log_name_here', (object) ['is' => 'stdClass', 'object' => 'friendly']);

Use a separate field to store address data for a FieldtypeMapMarker field

This one is really simple, more just sharing an implementation and idea, but proved valuable for reducing data redundancy. I have a FieldtypeMapMarker field but the way that I needed to store address data was much better suited to using multiple fields for things like street, city, state, and zip code. I wanted those fields to be the "controlling" fields for the map marker field to prevent needing to edit 2 fields to keep updated, or accidental content diversion between them. On page save the value from the address fields are pulled and converted into a single string that is added to the FieldtypeMapMarker field's "address" property. I used a Custom Field (ProFields) for my address fields but this can be modified to suit your use case very easily.

Github Gist

You might also consider hiding the address input on the FieldtypeMapMarker field itself to reduce confusion since the values will be updated automatically anyway. You'll need to have this in a file that is appended to the Admin styles

/*
  You can find the appropriate class for the template you are applying this to in the <body> element when editing a page
  You can omit that if you want to apply this everywhere
*/

.ProcessPageEdit-template-your_template_name .InputfieldMapMarker.Inputfield_activity_location .InputfieldMapMarkerAddress,
.ProcessPageEdit-template-your_template_name .InputfieldMapMarker.Inputfield_activity_location .InputfieldMapMarkerToggle,
.ProcessPageEdit-template-your_template_name .InputfieldMapMarker.Inputfield_activity_location .InputfieldMapMarkerLat,
.ProcessPageEdit-template-your_template_name .InputfieldMapMarker.Inputfield_activity_location .InputfieldMapMarkerLng {
   display: none !important;
}

<?php
// Add this to your ready.php file or ready-firing hook to insert the file containing that CSS to your admin.

$config->styles->add("/path/to/your/custom/admin/css/file.css");

Not-A-Hook Bonus - Here's code for an interactive Google Map

Renders a Google Map using a FieldtypeMapMarker field, a separate address field, Alpine.js, and Tailwind. You'll need a Google Maps API key, a styled map ID from your Google Developer account, and the aforementioned fields. I wrote it using the latest Google Maps API. Saved you some time. You'll probably need to tweak it. I adapted this so if you find a bug please let me know and I'll update the gist.

Note- this makes use of the AlpineJS Intersect plugin to improve performance by only loading/initializing the map when a user scrolls close enough to it. If you don't want that, remove the x-intersect directive. If you want to see it in action, you can check it out here.

Github Gist

Hook Support Class - A static method class to translate a field into all languages automatically

If you use the Fluency translation module, this is a class that will help out with translating a field into all languages programmatically. Sharing this here because the next hook uses this as a dependency. I keep this in the HookUtils directory noted in the file structure above. Usage is demonstrated in the next hook.

Github Gist

Translate all translatable fields using Fluency on page save whether from UI or API.

This is useful for instances where you want a page translated automatically and especially helpful when you are creating pages programmatically. This requires the above hook support class, as well as Fluency connected to an API account. Here are things that must be kept in mind. Please read them, the code for the hook, and the code for the support class to ensure that it works to your needs.

• You should modify Fluency before using this, really. Change the value of CACHE_EXPIRY on line 19 in the TranslationCache file to WireCache::expireNever. Do this to prevent chewing through your API usage from month to month on repeat translations. This will become standard in the next release of Fluency.
• This is an expensive operation in terms of API usage, which is why you very much should modify the caching behavior. This hook does not make an effort to determine which fields have changed before translating because it doesn't really matter if the translation is already cached.
• First time translations of pages with a significant amount of fields/content may be slow, like noticeably slower first time page save because this operation is only as fast as the speed of the request/response loop between ProcessWire and the translation API. Later page saves will be much faster thanks to cached translations. This will not attempt to translate empty fields, so those won't cause any delays.
• This works with multi-language text/textarea/TinyMCE/CKEditor fields, RepeaterMatrix fields, and the newer Custom Fields (ProFields). Other fields haven't been tested, but it's definitely possible to adapt this to those needs.
• I prefer to target specific templates with hooks, you can add multiple but be mindful of your use case.
• Consider adding excluded fields to the array in the hook if it makes sense
• Consider adding a field to enable/disable translations from the UI, a checkbox field or something
• This hook is probably one of the uglier ones, sorry.
• If you run out of API usage on your account, you're going to see a big ugly exception error on screen. This is due to Fluency not handling an account overage error properly because the return type was not as expected. Will be fixed in the next version of the module
• This is one that may be tailored to my PW application, I think it's general enough to use as-is for your project, but testing is definitely required.
• Read all the code please.

Github Gist

ProcessWire Object Method & Property Hooks

The following are custom methods that add functionality to native ProcessWire objects.

Add a getMatrixChildren() method to RepeaterMatrixPage objects

RepeaterMatrix fields represent nesting depth as an integer on each RepeaterMatrixPage item. So top level is 0, first nested level is 1, second 2, etc. When looping through RM items, determining nesting requires working with that integer. It works, but adding adding some functionality helps out. This is infinitely nestable, so accessing children, children of children, children of children of children, and so on works. Fun for the whole family. This was inspired by a forum post, another one I can't find...

Github Gist

<?php

// Access nested RepeaterMatrix items as child PageArray objects
$page->repeater_matrix_field->first()->getMatrixChildren(); // => PageArray

?>
<!-- Assists with rendering nested RM items in templates Sponsors are nested under sponsorship levels in the RM field -->
<div>
  <?php foreach ($page->sponsors as $sponsorshipLevel): ?>
    <h2><?=$sponsorshipLevel->title?></h2>

    <?php if ($sponsorshipLevel->getMatrixChildren()->count()): ?>
      <ul>
        
        <?php foreach ($sponsorshipLevel->getMatrixChildren() as $sponsor): ?>
          <li>
            <img src="<?=$sponsor->image->url?>" alt="<?=$sponsor->image->description?>">
            <?=$sponsor->title?>
          </li>
        <?php endforeach ?>
        
      </ul>
    <?php endif ?>

  <?php endforeach ?>
</div>

Add a resizeAspectRatio() method to PageImage objects

Adds a simple way to quickly resize an image to a specific aspect ratio. Use cases include sizing images for Google Structured Data and formatting images for consistency in image carousels. Could be improved by accepting second argument to specify an image width, but didn't fit my use case.

Github Gist

<?php 

$page->image_field->resizeAspectRatio('square')->url; // Alias for 1:1
$page->image_field->resizeAspectRatio('video')->url; // Alias for 16:9
$page->image_field->resizeAspectRatio('17:10')->url; // Arbitrary values accepted

Add a responsiveAttributes() method to PageImage objects

Adds a very helpful method to generate image variations and accompanying 'srcset' and 'sizes' attributes for any image. Designed to be very flexible and is Tailwind ready. Responsive sizing can be as simple or complex as your needs require. Includes an optional 'mobile' Tailwind breakpoint that matches a custom tailwind.config.js value:  screens: { 'mobile': '320px'}. I added this breakpoint largely to further optimize images for small screens. The array of Tailwind breakpoints and size definitions can be edited to suit your specific setup if there are customizations

When sizing for Tailwind, the last media query generated will automatically be switched to "min-width" rather than "max-width" to prevent problems arising from restricting widths. Example, you can specify values only for 'sm' and 'md' and the 'md' size will have the media query correctly adjusted so that it applies to all breakpoints above it.

Github Gist

<--
    The responsiveAttributes() returns a renderable attribute string: srcset="{generated values}" sizes="{generated values}"
-->
<-- Create responsive images with arbitrary width and height at breakpoints -->
<img src="<?=$page->image->url?>"
     <?=$page->image->responsiveAttributes([
       [240, 125, '(max-width: 300px)'],
       [225, 125, '(max-width: 600px)'],
       [280, 165, '(max-width: 900px)'],
       [210, 125, '(max-width: 1200px)'],
       [260, 155, '(min-width: 1500px)'],
     ])?>
     width="240" height="125"
     alt="<?=$page->image->description?>"
>

<-- Heights can be selectively ommitted by setting the height value to null -->
<img src="<?=$page->image->url?>"
     <?=$page->image->responsiveAttributes([
       [240, 125, '(max-width: 300px)'],
       [225, null, '(max-width: 600px)'],
       [280, 165, '(max-width: 900px)'],
       [210, null, '(max-width: 1200px)'],
       [260, null, '(min-width: 1500px)'],
     ])?>
     width="240" height="125"
     alt="<?=$page->image->description?>"
>
  
<-- Create responsive images with only widths at breakpoints -->
<img src="<?=$page->image->url?>"
     <?=page->image->responsiveAttributes([
       [240, '(max-width: 300px)'],
       [225, '(max-width: 600px)'],
       [280, '(max-width: 900px)'],
       [210, '(max-width: 1200px)'],
       [260, '(min-width: 1500px)'],
     ])?>
     width="240"
     height="125"
     alt="<?=$page->image->description?>"
>
  
<-- Create custom sizes matched to Tailwind breakpoints -->
<img src="<?=$page->image->url?>"
     <?=$page->image->responsiveAttributes([
       'mobile' => [240, 125], // Custom tailwind directive
       'sm' => [225, 125],
       'md' => [280, 165],
       'lg' => [210, 125],
       'xl' => [260, 155],
     ])?>
     width="240" height="125"
     alt="<?=$page->image->description?>"
>
 
<!--
     Resizes width of image to fit Tailwind breakpoints, useful for full width images such as hero
     images, doesn't change height. Also accepts 'tw' as an alias for 'tailwind'
-->
<img src="<?=$page->image->url?>"
     <?=$page->image->responsiveAttributes('tailwind')?>
     width="240" height="125"
     alt="<?=$page->image->description?>"
>

Add PHP higher-order function methods to WireArray and WireArray derived objects

WireArray objects are incredibly powerful and have tons of utility, but there are situations where I find myself needing to work with plain PHP arrays. I'm a very big fan of PHP's array functions that are efficient and make for clean readable code. I found myself often reaching for $wireArrayThing->getArray() to work with data then using functions like array_map, array_filter, and array_reduce. These return arrays, but could easily be modified to return WireArray objects if that is more helpful.

Github Gist

<?php 

// The EventPage page class has a method that determines sold out status from more than one source of data/page fields
// which means that it isn't queryable using a ProcessWire selector. This returns a single integer calculated from ticket availability
// of all events from non-queryable data.
$totalEventsAvailable = $eventPages->reduce(
  fn ($total, $eventPage) => $count = $eventPage->isActive() ? $total++ : $total, 0
);

// Requires using a page class to determine status reliant on multiple data points not queryable via a selector. Knowing what the event
// page is for an activity can't be determined using a selector for activity pages.
$displayableActivities = $matches->filterToArray(
  fn ($activityPage) => $activityPage->eventPage()->isPublic() && $activityPage->isActive()
);

// Iterating over each Page in a PageArray and processing data for sorting/ordering before rendering on a search results page
// Executed within a page class
$results = $searchResults->mapToArray(function($page) {
  return (object) [
    'page' => $page,
    'summary' => $this->createResultSummary(page: $page, maxLength: 750),
    'keywordMatchCount' => $this->getQueryMatchCount(page: $page),
  ];
});

Add an image orientation method/property to PageImage objects

Get the portrait or landscape orientation of a PageImage.

Github Gist

<?php 

$page->image->orientation;
$page->image->orientation();

Add the ability to get all related pages for Page objects at once

Gets all of the related pages to a page at once by both page reference fields and links in fields. Transparently passes native arguments to Page methods for native behavior

Github Gist

<?php 

$page->allPageReferences();
$page->allPageReferences(true); // Optionally include all pages regardless of status
$page->allPageReferences('your_selector=here', 'field_name'); // Use with native Page::references() and Page::links() arguments

Add a saveWithoutHooks() convenience method to Page objects

The number of hooks in my most recent project was... a lot. There were many that hooked into the page save event and a lot of operations that happen in the background where pages needed to be modified and saved quietly to prevent clearing ProCache files or excessive DB operations through chained hooks. Being able to use a method to do this rather than passing options felt more deliberate and clear when working across hundreds of files and in critical areas of very expensive operations.

This method also accepts page save options, but in a way that hooks will always be disabled even if an option is accidentally passed enabling them. Furthermore, it also accepts a string as the first argument that, if debug mode is enabled, will dump a message to the bar via Tracy.

Github Gist

<?php 

// Adding a message can be very helpful during testing, especially when saving a page with/without hooks is conditionally based
// where the result of another operation determines how a page is saved
$page->saveWithoutHooks('updated event sync data hash, saved without hooks');

$page->saveWithoutHooks(['resetTrackChanges' => true]);

$page->saveWithoutHooks('message and options', ['resetTrackChanges' => true]);

These are a few that I've used to show some diversity in application. Hooking to ProcessWire events makes it possible to build beyond simple websites and implement truly custom behavior. Hope these may be useful to others. If you have any favorite hooks of your own, have corrections of those I've shared, or improvements, sharing them in the comments would be stellar.

Cheers!

// enable unchecking radio buttons
// http://stackoverflow.com/questions/6191621/jquery-check-uncheck-radio-button-onclick#answer-13575528
$page->addHookAfter('render', function ($event) {

    if ($this->page->template != 'admin') return;

    $js = <<< HTML
 <script>
 $(document).ready(function(){
    $("input:radio:checked").data("chk",true);
    $("input:radio").click(function(){
        $("input[name='"+$(this).attr("name")+"']:radio").not(this).removeData("chk");
        $(this).data("chk",!$(this).data("chk"));
        $(this).prop("checked",$(this).data("chk"));
    });
});
</script>
HTML;

This is quite handy for when you want to make a quick edit to a page. But as the request notes, it would speed things up if there was a "Save + Close" button in the modal.

Until the request is actioned in the core I thought I'd try implementing it in some custom code, and it's also an opportunity to show an easy way you can add custom JS and CSS to the ProcessWire admin.

The first step is to create the following files at /site/templates/admin-assets/admin-custom.js and /site/templates/admin-assets/admin-custom.css. The CSS is optional.

admin-custom.js

$(document).ready(function() {

	const $body = $('body');
	const is_modal = $body.hasClass('modal') || $body.hasClass('pw-iframe');

	if($body.hasClass('ProcessPageEdit') && is_modal) {
		const params = new URLSearchParams(window.location.search);
		const $save_button = $('#submit_save');
		if(params.has('quick_edit') && $save_button.length) {
			$save_button.parent().append('<button type="submit" name="submit_save" value="Save" class="ui-button uk-hidden" id="save-and-close">Save + Close</button>');
		}
	}

	if($body.hasClass('ProcessPageList') && !is_modal) {
		$(document).on('ajaxComplete', function() {
			$('.PageListActionEdit a:not([data-autoclose])').each(function() {
				$(this).attr('data-autoclose', '#save-and-close').attr('href', $(this).attr('href') + '&quick_edit=1');
			});
		});
	}

});

admin-custom.css

/* Avoid Tracy debugbar appearing on top of modal */
.ui-widget-overlay.ui-front { z-index:40000; }
.ui-dialog { z-index:40001; }
/* Place modal buttons on the left rather than the right */
.ui-dialog .ui-dialog-buttonpane .ui-dialog-buttonset { float:none; }

The second step is to add the following hook to /site/ready.php

One good thing about using a hook to AdminTheme::getExtraMarkup to add custom CSS is that the file gets loaded after any CSS files that are loaded by modules or the PW core, so you can override any CSS rules without needing to add extra specificity.

// Add custom JS and CSS to admin
$wire->addHookAfter('AdminTheme::getExtraMarkup', function(HookEvent $event) {
	$parts = $event->return;
	$config = $event->wire()->config;

	// JS file should exist at /site/templates/admin-assets/admin-custom.js
	$js_url = $config->urls->templates . 'admin-assets/admin-custom.js';
	$modified = filemtime(rtrim($config->paths->root, '/') . $js_url);
	$parts['head'] .= "<script type='text/javascript' src='$js_url?m=$modified'></script>";

	// CSS file should exist at /site/templates/admin-assets/admin-custom.css
	$css_url = $config->urls->templates . 'admin-assets/admin-custom.css';
	$modified = filemtime(rtrim($config->paths->root, '/') . $css_url);
	$parts['head'] .= "<link rel='stylesheet' href='$css_url?m=$modified'>";

	$event->return = $parts;
});

The end result:

The module uses https://fullcalendar.io/ for the calendar interface and when clicking an event it will open the page editor in a pw modal:

Opening the modal was a bit of a challenge, because PW unfortunately does not offer a good JS API to open modals. It only offers markup-based options to control the behaviour of the modal - at least as far as I could find out.

This is a problem, because all events in the calendar get loaded by fullcalendar and I only have the eventClick() callback where I need to fire my action. My solution is to create a fake element in the dom and trigger a click on that element:

      calendar.on("eventClick", (info) => {
        // create a fake link element in body
        let link = document.createElement("a");
        let $link = $(link);
        $link.attr(
          "href",
          ProcessWire.config.urls.admin + "page/edit/?id=" + info.event.id
        );
        $link.addClass("pw-modal");
        $link.attr("data-autoclose", "");
        $link.attr("data-buttons", "button.ui-button[type=submit]");
        $link.on("click", pwModalOpenEvent);
        $(document).on("pw-modal-closed", this.refresh.bind(this));
        $link.click();
        $link.remove();
      });

Maybe that helps anyone else looking for a solution to a similar problem.

If anybody knows a better way how to do it, please let me know!

PS: If you have input (feature requests) for the development of RockCalendar please let me know: https://processwire.com/talk/topic/30355-request-for-input-what-features-should-a-pw-calendar-module-have/

Open /wire/core/WireHooks.php, find the method "runHooks" and paste this at the very top of this method:

		$logfile = wire()->config->paths->root . 'hooks.txt';
		$tooOld = is_file($logfile) && filemtime($logfile) < time() - 5;
		if ($tooOld) unlink($logfile);
        $logData = get_class($object) . "::$method\n";
		file_put_contents($logfile, $logData, FILE_APPEND);

This will write a log of all hookable methods to hooks.txt and it will probably begin like this:

ProcessWire\FileCompiler::compile
ProcessWire\FileCompiler::compile
ProcessWire\FileCompiler::compile
ProcessWire\FileCompiler::compile
ProcessWire\Fields::load
ProcessWire\Fieldgroups::load
ProcessWire\Templates::load
ProcessWire\Fieldgroup::setQuietly
ProcessWire\Fieldgroup::callUnknown
(maaaany more lines)

And it will most likely end with "ProcessWire\ProcessWire::finished" 🙂 

Now you can play around with this logfile and view different pages. For example when opening a page for editing you will have a portion of this in the log (ProcessPageEdit::buildForm...):

ProcessWire\ProcessPageEdit::breadcrumb
ProcessWire\JqueryCore::use
ProcessWire\JqueryUI::use
ProcessWire\ProcessPageEdit::execute
ProcessWire\HutPage::setEditor
ProcessWire\ProcessPageEdit::buildForm
ProcessWire\ProcessPageEdit::buildFormContent
ProcessWire\Field::getInputfield
ProcessWire\Field::getInputfield
ProcessWire\Field::getInputfield
ProcessWire\Field::getInputfield
ProcessWire\Field::getInputfield
ProcessWire\Field::getInputfield
ProcessWire\Field::getInputfield
ProcessWire\Field::changed
ProcessWire\Field::changed
ProcessWire\Field::getInputfield
ProcessWire\Field::changed
ProcessWire\Field::getInputfield
ProcessWire\Field::getInputfield
ProcessWire\Field::getInputfield
ProcessWire\HutPage::viewable
ProcessWire\Pages::find
ProcessWire\PageFinder::find
ProcessWire\PageFinder::getQuery
ProcessWire\HutPage::addable
ProcessWire\ProcessPageEdit::buildFormChildren
ProcessWire\WireInputData::int
ProcessWire\WireInputData::callUnknown
ProcessWire\WireInputData::int
ProcessWire\WireInputData::callUnknown

You can also use grep to find the hooks you are looking for, for example:

cat hooks.txt | grep ProcessWire::

ProcessWire\ProcessWire::init
ProcessWire\ProcessWire::ready
ProcessWire\ProcessWire::finished
ProcessWire\ProcessWire::finished

This has helped me today to find the correct spot to hook into. Maybe it also helps anyone else. Have fun!

PS: Don't forget to remove this once you are done with inspecting, of course!