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
Name | Return | Summary | |
---|---|---|---|
$sanitizer->htmlClass() $sanitizer->htmlClass(string $value) $sanitizer->htmlClass(string $value) | string | Sanitize string to ASCII-only HTML class attribute value | |
$sanitizer->htmlClasses() $sanitizer->htmlClasses($value) $sanitizer->htmlClasses($value, bool $getArray = false) | string array | Sanitize string to ASCII-only space-separated HTML class attribute values with no duplicates |
Numbers
Strings
Arrays
Pages
Constants
Name | Return | Summary | |
---|---|---|---|
Sanitizer::translate const | 2 | Constant used for the $beautify argument of name sanitizer methods to indicate transliteration may be used. |
Files
Name | Return | Summary | |
---|---|---|---|
$sanitizer->filename() $sanitizer->filename(string $value) $sanitizer->filename(string $value, $beautify = false, int $maxLength = 128) | string | Name filter for ProcessWire filenames (basenames only, not paths) | |
$sanitizer->validateFile() $sanitizer->validateFile(string $filename) $sanitizer->validateFile(string $filename, array $options = []) | bool array null | Validate and sanitize a file using FileValidator modules |
Validate
Name | Return | Summary | |
---|---|---|---|
$sanitizer->email() $sanitizer->email(string $value) $sanitizer->email(string $value, array $options = []) | string | Sanitize and validate an email address | |
$sanitizer->httpUrl() $sanitizer->httpUrl(string $value) $sanitizer->httpUrl(string $value, array $options = []) | string | URL with http or https scheme required | |
$sanitizer->url() $sanitizer->url(string $value) $sanitizer->url(string $value, $options = []) | string | Sanitize and validate given URL or return blank if it can’t be made valid | |
$sanitizer->valid() $sanitizer->valid($value) $sanitizer->valid($value, string $method = 'text', bool $strict = false) | bool | Is given value valid? (i.e. unchanged by given sanitizer method) | |
$sanitizer->validate() $sanitizer->validate($value) $sanitizer->validate($value, string $method = 'text', $fallback = null) | null mixed | Validate that value remains unchanged by given sanitizer method, or return null if not |
Other
Additional methods and properties
In addition to the methods and properties above, Sanitizer also inherits the methods and properties of these classes:
API reference based on ProcessWire core version 3.0.236