ProcessWire Weekly #246

Latest core updates: ProcessWire 3.0.125

In the latest post at the processwire.com blog Ryan introduces the latest development version of ProcessWire, 3.0.125. This time around the main focus has been on various improvements to the built-in $sanitizer feature, but we've also got some updates to the $input API variable, built-in translation functions, and also to the API documentation.

New syntax options for $sanitizer

As of this week there are some new syntax options for $sanitizer. These include the sanitize() method, which is basically a way to ask $sanitizer to process given input using one or more sanitizer methods:

// Single sanitizer method:
$value = $sanitizer->sanitize($value, 'text');

// Multiple sanitizer methods, separated by a comma:
$value = $sanitizer->sanitize($value, 'text, entities');

// Text sanitizer methods accept an additional number for max length:
$value = $sanitizer->sanitize($value, 'text80');

Note that in some cases the number after the sanitizer method name can also mean something else. This is probably best explained through the newly added $sanitizer->min() and $sanitizer->max() methods (more about these in a bit), which are the first ones to put this feature in action:

// Make sure that the value is an integer between 1 and 80:
$value = $sanitizer->sanitize($value, 'min1, max80');

Now, part of the reason why these new syntax options exist is that they can be represented as a single string. This allows us to use another alternative syntax, which seems particularly interesting in terms of front-end (template file) use:

// Make sure that the value is entity-encoded text with max length of 60
$value = $sanitizer->text60_entities($value);

As always, you can find more details about these new syntax options from the blog post mentioned earlier.

New $sanitizer methods

In addition to the new syntax options, this week we also have a number of new $sanitizer methods:

• $sanitizer->range($value, $min, $max)
• $sanitizer->min($value, $min) and $sanitizer->max($value, $max)
• $sanitizer->bit()
• $sanitizer->maxLength($value, $maxLength)
• $sanitizer->maxBytes($value, $maxBytes)
• $sanitizer->sanitize($value, $method)
• $sanitizer->validate($value, $method, $fallback = null)
• $sanitizer->valid($value, $method)

Most of these are probably self-explanatory, but $sanitizer->validate() and $sanitizer->valid() are quite special: by default sanitizer attempts to convert an original value to a valid one, but if you pass that value and a sanitizer method to one of these, they'll instead check if the value is valid. If provided sanitizer method (or methods) would change the value, it's not valid.

$sanitizer->validate() returns either the original value or the value from provided $fallback parameter, while $sanitizer->valid() returns true for valid values, and false for invalid values.

Upgrades to the $input API variable

We briefly hinted at this one last week, but there are a couple of upgrades to the $input API variable this week as well. First of all, familiar methods (get, post, and cookie) now accept more than one parameter. Previously they only accepted a single parameter, which was the name of the parameter to fetch, but now you can also provide a second parameter, which can be one of the following:

1. Single string, such as text, for a sanitizer method to run the value through. If you provide an additional number at the end ('text42'), it is used as the max length, like explained earlier.
2. A comma separated list of sanitizers, such as 'int,min1,max10'. Usual rules regarding the max length (or other applicable parameter in the case of min and max sanitizers) apply.
3. An array of accepted values – or, in other words, a whitelist: [ 'red', 'blue', 'green' ]. If you use this option, the return value can only be one of those provided via the array.

These methods also support a third parameter, which would be the fallback value:

// Return an integer from GET param "quantity", or 1 if no param provided
$quantity = $input->get('quantity', 'int', 1);

Finally, by appending opening and closing square brackets ([]) to the end of the parameter name you can force $input methods to always return an array:

// Return value from GET param "colors" as an array
$value = $input->get('colors[]');

Other updates for this week: new way to use static translation functions, and some documentation improvements

This week the static translation function __() was updated with a new, advanced feature, allowing it to behave as a getter or setter for (currently) two options: entityEncode and translations. These are covered in the new documentation page for the __() function, but entityEncode essentially triggers a mode in which __() will entity encode the output, and translations can be used to provide default values for untranslated strings.

This feature is triggered by providing boolean true as the first parameter to the __() function:

// Get the value of the entityEncode option:
$val = __(true, 'entityEncode');

// Set the value of the entityEncode option:
__(true, 'entityEncode', true);

Other updates made this week have focused mainly on the documentation. Our official documentation is automatically generated from the PHPDoc comments included in the core code, and 3.0.125 includes numerous updates to these. The API documentation section of our website also has some entirely new sections, such as those documenting our procedural functions.

For more details, use cases, and code samples regarding this week's core updates, be sure to check out Ryan's blog post. Thanks!

New module: Page Hit Counter – simple page view tracking

Page Hit Counter is a new module from David Karich of FlipZoom Media. As the name suggests, this module adds a simple hit or view counter to ProcessWire pages. It's particularly handy for cases where you want to keep track of page views, prefer to store that data locally, and don't want to use a full-featured analytics applications, such as Google Analytics or Matomo.

The tracking code used by this module is quite lightweight at around 320 bytes (gzipped), and the module is GDPR compliant, since no personal data – including IP addresses – get stored.

Although the module is relatively simple, there are quite a few configuration settings to tweak if your needs are more advanced: you can choose which templates to track, enable IP address filtering, filter out bots, define the lifetime of session cookies, choose if view counters should be displayed on the page tree, and exclude select roles (for authenticated users) altogether.

Overall this is a really nice module if you just want to track page views, without all the hassle – and possible legal ramifications – involved with a full-blown analytics application. You can give this module a try by grabbing it directly from the Page Hit Counter GitHub repository, or install it using the built-in module installer.

Big thanks to David for sharing his work with the community – this module is a great addition, and we're really happy to have it available!

Site of the week: Roar Visuals – Digital Content Agency

Our latest site of the week belongs to Roar Visuals – a digital content agency based in Winterthur, Switzerland. They are a team of three, but work with a wide group of professional filmers, photographers, and influencers to create stunning content for their clients. Services provided by Roar Visuals include social media consulting and conception, film, photography, influencer campaigns, and sound design.

The website of Roar Visuals is, unsurprisingly, truly gorgeous: the home page is essentially one big showcase of their work, with a brief introduction to the team, slightly longer summaries of the services they provide, and contact details. The rest of the site follows a similar pattern, focusing on specific work samples: there are images of the project, often accompanied by video content and a brief credits section, and sometimes a few notes about the project.

Overall this is a really simple yet stunningly beautiful showcase website, with loads of focus given to the audiovisual representation of various projects Roar Visuals has been involved with. The front-end implementation and overall layout of the site was developed using the UIkit front-end framework, behind the scenes assets are combined and minified using the AIOM+ module, and third party services – YouTube and Vimeo – are used for the embedded videos.

Our congratulations to both Roar Visuals and the company behind the implementation, Egli Online Services, for this stunning new website. This is some absolutely brilliant work, keep it up folks!

Stay tuned for our next issue

That's it for the 246th issue of ProcessWire Weekly. We'll be back with more news, updates, and content Saturday, 2nd of February. As always, ProcessWire newsletter subscribers will get our updates a few days later.

Thanks for staying with us, once again. Hope you've had a great and productive week, and don't forget to check out the ProcessWire forums for more interesting topics. Until next week, happy hacking with ProcessWire!