$sanitizer

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.

Show $var?     Show args?       Only hookable?    

Common

NameReturnSummary 
$sanitizer->htmlClass(string $value)
string

Sanitize string to ASCII-only HTML class attribute value

 
$sanitizer->htmlClasses($value)
string array

Sanitize string to ASCII-only space-separated HTML class attribute values with no duplicates

 

Numbers

NameReturnSummary 
$sanitizer->bit($value)
int

Sanitize to a bit, returning only integer 0 or 1

 
$sanitizer->date($value)
string int null

Sanitize a date or date/time string, making sure it is valid, and return it

 
$sanitizer->digits(string $value)
string

Sanitize string to contain only ASCII digits (0-9)

 
$sanitizer->float($value)
float string

Sanitize to floating point value

 
$sanitizer->getNumberTools()
WireNumberTools

Get instance of WireNumberTools

 
$sanitizer->int(mixed $value)
int

Sanitized an integer (unsigned, unless you specify a negative minimum value)

 
$sanitizer->intArray($value)
array

Sanitize array or CSV string to array of unsigned integers (or signed integers if specified $min is less than 0)

 
$sanitizer->intArrayVal($value)
array

Sanitize array to be all unsigned integers with no conversions

 
$sanitizer->intSigned(mixed $value)
int

Sanitize to signed integer (negative or positive)

 
$sanitizer->intUnsigned(mixed $value)
int

Sanitize to unsigned (0 or positive) integer

 
$sanitizer->max($value)
int float

Sanitize to have a maximuim value

 
$sanitizer->min($value)
int float

Sanitize to have a minimum value

 
$sanitizer->range($value)
int float

Sanitize value to be within the given min and max range

 

Strings

NameReturnSummary 
$sanitizer->alpha(string $value)
string

Sanitize to ASCII alpha (a-z A-Z)

 
$sanitizer->alphanumeric(string $value)
string

Sanitize to ASCII alphanumeric (a-z A-Z 0-9)

 
$sanitizer->attrName(string $value)
string

Sanitize to an ASCII-only HTML attribute name

 
$sanitizer->camelCase(string $value)
string

Convert string to be all camelCase

 
$sanitizer->chars(string $value)
string

Sanitize string value to have only the given characters

 
$sanitizer->date($value)
string int null

Sanitize a date or date/time string, making sure it is valid, and return it

 
$sanitizer->digits(string $value)
string

Sanitize string to contain only ASCII digits (0-9)

 
$sanitizer->email(string $value)
string

Sanitize and validate an email address

 
$sanitizer->emailHeader(string $value)
string

Returns a value that may be used in an email header

 
$sanitizer->entities(string $str)
string

Entity encode a string for output

 
$sanitizer->entities1(string $str)
string

Entity encode a string and don’t double encode it if already encoded

 
$sanitizer->entitiesA($value)
array string int float bool

Entity encode with support for [A]rrays and other non-string values

 
$sanitizer->entitiesA1($value)
array string int float bool

Same as entitiesA() but does not double encode

 
$sanitizer->entitiesMarkdown(string $str)
string

Entity encode while translating some markdown tags to HTML equivalents

 
$sanitizer->fieldName(string $value)
string

Sanitize consistent with names used by ProcessWire fields and/or PHP variables

 
$sanitizer->fieldSubfield(string $value)
string

Sanitize as a field name but with optional subfield(s) like “field.subfield”

 
$sanitizer->filename(string $value)
string

Name filter for ProcessWire filenames (basenames only, not paths)

 
$sanitizer->getTextTools()
WireTextTools

Get instance of WireTextTools

 
$sanitizer->httpUrl(string $value)
string

URL with http or https scheme required

 
$sanitizer->hyphenCase(string $value)
string

Convert string to be all hyphenated-lowercase (aka kabab-case, hyphen-case, dash-case, etc.)

 
$sanitizer->kebabCase(string $value)
string

Alias of hyphenCase()

 
$sanitizer->line(string $value)
string

Sanitize any string of text to single line, no HTML, and no specific max-length (unless given)

 
$sanitizer->lines(string $value)
string

Sanitize input string as multi-line text, no HTML tags, and no specific max length (unless given)

 
$sanitizer->markupToLine(string $value)
string

Convert a string containing markup or entities to be a single line of plain text

 
$sanitizer->markupToText(string $value)
string

Convert a string containing markup or entities to be plain text

 
$sanitizer->match(string $value, string $regex)
string

Validate that given value matches regex pattern.

 
$sanitizer->maxBytes(string $value)
string

Limit bytes used by given string to max specified

 
$sanitizer->maxLength($value)
array float int string

Limit length of given value to that specified

 
$sanitizer->minLength(string $value)
string

Validate or sanitize a string to have a minimum length

 
$sanitizer->name(string $value)
string

Sanitize in "name" format (ASCII alphanumeric letters/digits, hyphens, underscores, periods)

 
$sanitizer->names($value)
string array

Sanitize a string or array containing multiple names

 
$sanitizer->pageName(string $value)
string

Sanitize as a ProcessWire page name

 
$sanitizer->pageNameTranslate(string $value)
string

Name filter for ProcessWire Page names with transliteration

 
$sanitizer->pageNameUTF8(string $value)
string

Sanitize and allow for UTF-8 characters in page name

 
$sanitizer->pagePathName(string $value)
string

Sanitize a page path name

 
$sanitizer->pagePathNameUTF8(string $value)
string

Sanitize a UTF-8 page path name (does not perform ASCII/UTF8 conversions)

 
$sanitizer->pascalCase(string $value)
string

Convert string to PascalCase (like camelCase, but first letter always uppercase)

 
$sanitizer->path(string $value)
bool string

Validate the given path, return path if valid, or false if not valid

 
$sanitizer->purify(string $str)
string

Purify HTML markup using HTML Purifier

 
$sanitizer->removeMB4($value)
string array

Removes 4-byte UTF-8 characters (like emoji) that produce error with with MySQL regular “UTF8” encoding

 
$sanitizer->removeNewlines(string $str)
string

Remove newlines from the given string and return it

 
$sanitizer->removeWhitespace(string $str)
string

Remove or replace all whitespace from string

 
$sanitizer->selectorValue($value)
string int bool mixed

Sanitizes a string value that needs to go in a ProcessWire selector

 
$sanitizer->selectorValueAdvanced($value)
bool mixed string

Sanitize selector value for advanced text search operator (#=)

 
$sanitizer->snakeCase(string $value)
string

Convert string to be all snake_case (lowercase and underscores)

 
$sanitizer->string($value)
string

Sanitize value to string

 
$sanitizer->text(string $value)
string

Sanitize short string of text to single line without HTML

 
$sanitizer->textarea(string $value)
string

Sanitize input string as multi-line text without HTML tags

 
$sanitizer->textdomain(string $value)
string

Sanitize as language textdomain

 
$sanitizer->trim(string $str)
string

Trim off all known UTF-8 whitespace types (or given chars) from beginning and ending of string

 
$sanitizer->trunc(string $str)
string

Truncate string to given maximum length without breaking words and with no added visible extras

 
$sanitizer->truncate(string $str)
string

Truncate string to given maximum length without breaking words

 
$sanitizer->unentities(string $str)
string

Remove entity encoded characters from a string.

 
$sanitizer->url(string $value)
string

Sanitize and validate given URL or return blank if it can’t be made valid

 
$sanitizer->word(string $value)
string

Return first word in given string

 
$sanitizer->words($value)
string

Given string return a new string containing only words

 

Arrays

NameReturnSummary 
$sanitizer->array($value)
array

Sanitize array or CSV string to array of values, optionally sanitized by given method

$sanitizer->arrayVal(mixed $value)
array

Simply sanitize value to array with no conversions

 
$sanitizer->entitiesA($value)
array string int float bool

Entity encode with support for [A]rrays and other non-string values

 
$sanitizer->entitiesA1($value)
array string int float bool

Same as entitiesA() but does not double encode

 
$sanitizer->flatArray(array $value)
array

Given a potentially multi-dimensional array, return a flat 1-dimensional array

 
$sanitizer->intArray($value)
array

Sanitize array or CSV string to array of unsigned integers (or signed integers if specified $min is less than 0)

 
$sanitizer->intArrayVal($value)
array

Sanitize array to be all unsigned integers with no conversions

 
$sanitizer->minArray(array $data)
array

Minimize an array to remove empty values

 
$sanitizer->option($value)
string int null

Return $value if it exists in $allowedValues, or null if it doesn't

 
$sanitizer->options(array $values)
array

Return given values that that also exist in $allowedValues whitelist

 
$sanitizer->wordsArray($value)
array

Return array of all words in given value (excluding punctuation and other non-word characters)

 

Constants

NameReturnSummary 
Sanitizer::translate const2Constant used for the $beautify argument of name sanitizer methods to indicate transliteration may be used. 

Validate

NameReturnSummary 
$sanitizer->email(string $value)
string

Sanitize and validate an email address

 
$sanitizer->httpUrl(string $value)
string

URL with http or https scheme required

 
$sanitizer->url(string $value)
string

Sanitize and validate given URL or return blank if it can’t be made valid

 
$sanitizer->valid($value)
bool

Is given value valid? (i.e. unchanged by given sanitizer method)

 
$sanitizer->validate($value)
null mixed

Validate that value remains unchanged by given sanitizer method, or return null if not

 

Other

NameReturnSummary 
$sanitizer->bit($value)
int

Sanitize to a bit, returning only integer 0 or 1

 
$sanitizer->bool($value)
bool

Convert the given value to a boolean

 
$sanitizer->checkbox($value)
int bool string mixed null

Sanitize checkbox value

 
$sanitizer->getAll()
array

Get all sanitizer method names and optionally types they return

 
$sanitizer->getNumberTools()
WireNumberTools

Get instance of WireNumberTools

 
$sanitizer->getTextTools()
WireTextTools

Get instance of WireTextTools

 
$sanitizer->maxLength($value)
array float int string

Limit length of given value to that specified

 
$sanitizer->purifier()
MarkupHTMLPurifier

Return a new HTML Purifier instance

 
$sanitizer->sanitize(mixed $value)
string int array float null

Call a sanitizer method indirectly where method name can contain combined/combo methods

 
$sanitizer->testAll(mixed $value)
array

Run value through all sanitizers, return array indexed by sanitizer name and resulting value

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.252