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

Show $var?             Show args?        

Common

NameReturnSummary 
$sanitizer->fieldSubfield(string $value)
stringSanitize as a field name but with optional subfield(s) like “field.subfield” 
$sanitizer->getTextTools()
WireTextToolsGet instance of WireTextTools 
$sanitizer->sanitize(mixed $value)
string int array float nullCall a sanitizer method indirectly where method name can contain combined/combo methods 
$sanitizer->truncate(string $str)
stringTruncate string to given maximum length without breaking words 

Numbers

NameReturnSummary 
$sanitizer->bit($value)
intSanitize to a bit, returning only integer 0 or 1 
$sanitizer->date($value)
string int nullSanitize a date or date/time string, making sure it is valid, and return it 
$sanitizer->float($value)
floatSanitize to floating point value 
$sanitizer->int(mixed $value)
intSanitized an integer (unsigned, unless you specify a negative minimum value) 
$sanitizer->intArray($value)
arraySanitize array or CSV string to array of unsigned integers (or signed if specified $min is less than 0) 
$sanitizer->intSigned(mixed $value)
intSanitize to signed integer (negative or positive) 
$sanitizer->intUnsigned(mixed $value)
intSanitize to unsigned (0 or positive) integer 
$sanitizer->max($value)
int floatSanitize value to be at least the given $min value 
$sanitizer->min($value)
int floatSanitize value to be at least the given $min value 
$sanitizer->range($value)
int floatSanitize value to be within the given min and max range 

Strings

NameReturnSummary 
$sanitizer->alpha(string $value)
stringSanitize to ASCII alpha (a-z A-Z) 
$sanitizer->alphanumeric(string $value)
stringSanitize to ASCII alphanumeric (a-z A-Z 0-9) 
$sanitizer->camelCase(string $value)
stringConvert string to be all camelCase 
$sanitizer->chars(string $value)
stringSanitize string value to have only the given characters 
$sanitizer->date($value)
string int nullSanitize a date or date/time string, making sure it is valid, and return it 
$sanitizer->digits(string $value)
stringSanitize string to contain only ASCII digits (0-9) 
$sanitizer->email(string $value)
stringSanitize and validate an email address 
$sanitizer->emailHeader(string $value)
stringReturns a value that may be used in an email header 
$sanitizer->entities(string $str)
stringEntity encode a string for output 
$sanitizer->entities1(string $str)
stringEntity encode a string and don’t double encode it if already encoded 
$sanitizer->entitiesMarkdown(string $str)
stringEntity encode while translating some markdown tags to HTML equivalents 
$sanitizer->fieldName(string $value)
stringSanitize consistent with names used by ProcessWire fields and/or PHP variables 
$sanitizer->filename(string $value)
stringName filter for ProcessWire filenames (basenames only, not paths) 
$sanitizer->httpUrl(string $value)
stringURL with http or https scheme required 
$sanitizer->hyphenCase(string $value)
stringConvert string to be all hyphenated-lowercase (aka kabab-case, hyphen-case, dash-case, etc.) 
$sanitizer->kebabCase(string $value)
stringAlias of hyphenCase() 
$sanitizer->markupToLine(string $value)
stringConvert a string containing markup or entities to be a single line of plain text 
$sanitizer->markupToText(string $value)
stringConvert a string containing markup or entities to be plain text 
$sanitizer->match(string $value, string $regex)
stringValidate that given value matches regex pattern. 
$sanitizer->maxBytes(string $value)
stringLimit bytes used by given string to max specified 
$sanitizer->maxLength($value)
array bool float int stringLimit length of given value to that specified 
$sanitizer->minLength(string $value)
stringValidate or sanitize a string to have a minimum length 
$sanitizer->name(string $value)
stringSanitize in "name" format (ASCII alphanumeric letters/digits, hyphens, underscores, periods) 
$sanitizer->names($value)
string arraySanitize a string or array containing multiple names 
$sanitizer->pageName(string $value)
stringSanitize as a ProcessWire page name 
$sanitizer->pageNameTranslate(string $value)
stringName filter for ProcessWire Page names with transliteration 
$sanitizer->pageNameUTF8(string $value)
stringSanitize and allow for UTF-8 characters in page name 
$sanitizer->pagePathName(string $value)
stringSanitize a page path name 
$sanitizer->pagePathNameUTF8(string $value)
stringSanitize a UTF-8 page path name (does not perform ASCII/UTF8 conversions) 
$sanitizer->pascalCase(string $value)
stringConvert string to PascalCase (like camelCase, but first letter always uppercase) 
$sanitizer->path(string $value)
bool stringValidate the given path, return path if valid, or false if not valid 
$sanitizer->purify(string $str)
stringPurify HTML markup using HTML Purifier 
$sanitizer->removeMB4($value)
string array mixedRemoves 4-byte UTF-8 characters (like emoji) that produce error with with MySQL regular “UTF8” encoding 
$sanitizer->removeNewlines(string $str)
stringRemove newlines from the given string and return it 
$sanitizer->removeWhitespace(string $str)
stringRemove or replace all whitespace from string 
$sanitizer->selectorValue($value)
stringSanitizes a string value that needs to go in a ProcessWire selector 
$sanitizer->snakeCase(string $value)
stringConvert string to be all snake_case (lowercase and underscores) 
$sanitizer->string($value)
stringSanitize value to string 
$sanitizer->text(string $value)
stringSanitize short string of text to single line without HTML 
$sanitizer->textarea(string $value)
stringSanitize input string as multi-line text without HTML tags 
$sanitizer->trim(string $str)
stringTrim of all known UTF-8 whitespace types (or given chars) from beginning and ending of string 
$sanitizer->unentities(string $str)
stringRemove entity encoded characters from a string. 
$sanitizer->url(string $value)
stringSanitize and validate given URL or return blank if it can’t be made valid 

Arrays

NameReturnSummary 
$sanitizer->array($value)
arraySanitize array or CSV string to array of strings
$sanitizer->intArray($value)
arraySanitize array or CSV string to array of unsigned integers (or signed if specified $min is less than 0) 
$sanitizer->minArray(array $data)
arrayMinimize an array to remove empty values 
$sanitizer->option($value)
string int nullReturn $value if it exists in $allowedValues, or null if it doesn't 
$sanitizer->options(array $values)
arrayReturn given values that that also exist in $allowedValues whitelist 

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)
stringSanitize and validate an email address 
$sanitizer->httpUrl(string $value)
stringURL with http or https scheme required 
$sanitizer->url(string $value)
stringSanitize and validate given URL or return blank if it can’t be made valid 
$sanitizer->valid($value)
boolIs given value valid? (i.e. unchanged by given sanitizer method) 
$sanitizer->validate($value)
null mixedValidate that value remains unchanged by given sanitizer method, or return null if not 

Other

NameReturnSummary 
$sanitizer->bit($value)
intSanitize to a bit, returning only integer 0 or 1 
$sanitizer->bool($value)
boolConvert the given value to a boolean 
$sanitizer->checkbox($value)
int bool string mixed nullSanitize checkbox value 
$sanitizer->maxLength($value)
array bool float int stringLimit length of given value to that specified 
$sanitizer->purifier()
MarkupHTMLPurifierReturn a new HTML Purifier instance 
$sanitizer->testAll($value)
arrayRun 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.132

Twitter updates

  • New post: ProcessWire 3.0.131 adds support for partial/resumable downloads and http stream delivery, and contains several updates to our comments system, among other updates— More
    3 May 2019
  • New post: Quietly and without interruption this week, the ProcessWire.com website (and all subdomains) moved from a single static server to a load-balanced multi-server environment, giving us even more horsepower and redundancy than before— More
    19 April 2019
  • New post: With ProcessWire 3.0.130, this week we’ll take a detailed look at a few useful new API additions made in the last few weeks, along with examples of each—More
    12 April 2019

Latest news

  • ProcessWire Weekly #262
    The 262nd issue of ProcessWire Weekly will cover the latest module updates, both Pro modules and non-commercial ones. We've also got some highlights from the support forum, and a beautiful new site of the week. Read on!
    Weekly.pw / 18 May 2019
  • Lots of module updates
    In this post we take a quick look at the new version of ProFields Repeater Matrix, yet another new version of FormBuilder, and a new version of the GoogleClientAPI module.
    Blog / 17 May 2019
  • Subscribe to weekly ProcessWire news

I just love the easy and intuitive ProcessWire API. ProcessWire rocks!” —Jens Martsch, Web developer