$sanitizer API variable / Sanitizer class

Provides methods for sanitizing and validating user input, preparing data for output, and more.

Sanitizer is useful for sanitizing input or any other kind of data that you need to match a particular type or format. The Sanitizer methods are accessed from the $sanitizer API variable and/or sanitizer() API variable/function. For example:

$cleanValue = $sanitizer->text($dirtyValue); 

You can replace the text() call above with any other sanitizer method. Many sanitizer methods also accept additional arguments—see each individual method for details.

Sanitizer and input

Sanitizer methods are most commonly used with user input. As a result, the methods in this class are also accessible from the $input->get, $input->post and $input->cookie API variables, in the same manner that they are here. This is a useful shortcut for instances where you don’t need to provide additional arguments to the sanitizer method. Below are a few examples of this usage:

// get GET variable 'id' as integer
$id = $input->get->int('id');

// get POST variable 'name' as 1-line plain text
$name = $input->post->text('name');

// get POST variable 'comments' as multi-line plain text
$comments = $input->post->textarea('comments'); 

In ProcessWire 3.0.125 and newer you can also perform the same task as the above with one less -> level like the example below:

$comments = $input->post('comments','textarea'); 

This is more convenient in some IDEs because it’ll never be flagged as an unrecognized function call. Though outside of that it makes little difference how you call it, as they both do the same thing.

See the $input API variable for more details on how to call sanitizers directly from $input.

Adding your own sanitizers

You can easily add your own new sanitizers via ProcessWire hooks. Hooks are commonly added in a /site/ready.php file, or from a Module, though you may add them wherever you want. The following example adds a sanitizer method called zip() which enforces a 5 digit zip code:

$sanitizer->addHook('zip', function(HookEvent $event) {
  $sanitizer = $event->object;
  $value = $event->arguments(0); // get first argument given to method
  $value = $sanitizer->digits($value, 5); // allow only digits, max-length 5
  if(strlen($value) < 5) $value = ''; // if fewer than 5 digits, it is not a zip
  $event->return = $value;
});

// now you can use your zip sanitizer
$dirtyValue = 'Decatur GA 30030';
$cleanValue = $sanitizer->zip($dirtyValue);
echo $cleanValue; // outputs: 30030

Additional options (3.0.125 or newer)

In ProcessWire 3.0.125+ you can also combine sanitizer methods in a single call. These are defined by separating each sanitizer method with an understore. The example below runs the value through the text sanitizer and then through the entities sanitizer:

$cleanValue = $sanitizer->text_entities($dirtyValue);

If you append a number to any sanitizer call that returns a string, it is assumed to be maximum allowed length. For example, the following would sanitize the value to be text of no more than 20 characters:

$cleanValue = $sanitizer->text20($dirtyValue); 

The above technique also works for any user-defined sanitizers you’ve added via hooks. We like this strategy for storage of sanitizer calls that are executed at some later point, like those you might store in a module config. It essentially enables you to define loose data types for sanitization. In addition, if there are other cases where you need multiple sanitizers to clean a particular value, this strategy can do it with a lot less code than you would with multiple sanitizer calls.

Most methods in the Sanitizer class focus on sanitization rather than validation, with a few exceptions. You can convert a sanitizer call to validation call by calling the validate() method with the name of the sanitizer and the value. A validation call simply implies that if the value is modified by sanitization then it is considered invalid and thus it’ll return a non-value rather than a sanitized value. See the Sanitizer::validate() and Sanitizer::valid() methods for usage details.

Click any linked item for full usage details and examples. Hookable methods are indicated with the icon. In addition to those shown below, the Sanitizer class also inherits all the methods and properties of: Wire.

• Common
• Numbers
• Strings
• Arrays
• Pages
• Constants
• Files
• Validate
• Other

Additional methods and properties

In addition to the methods and properties above, Sanitizer also inherits the methods and properties of these classes:

• Wire