$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->htmlClass(string $value)
stringSanitize string to ASCII-only HTML class attribute value 
$sanitizer->htmlClasses($value)
string arraySanitize string to ASCII-only space-separated HTML class attribute values with no duplicates 

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->digits(string $value)
stringSanitize string to contain only ASCII digits (0-9) 
$sanitizer->float($value)
float stringSanitize to floating point value 
$sanitizer->getNumberTools()
WireNumberToolsGet instance of WireNumberTools 
$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 integers if specified $min is less than 0) 
$sanitizer->intArrayVal($value)
arraySanitize array to be all unsigned integers with no conversions 
$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 to have a maximuim value 
$sanitizer->min($value)
int floatSanitize to have a minimum 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->attrName(string $value)
stringSanitize to an ASCII-only HTML attribute name 
$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->entitiesA($value)
array string int float boolEntity encode with support for [A]rrays and other non-string values 
$sanitizer->entitiesA1($value)
array string int float boolSame as entitiesA() but does not double encode 
$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->fieldSubfield(string $value)
stringSanitize as a field name but with optional subfield(s) like “field.subfield” 
$sanitizer->filename(string $value)
stringName filter for ProcessWire filenames (basenames only, not paths) 
$sanitizer->getTextTools()
WireTextToolsGet instance of WireTextTools 
$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->line(string $value)
stringSanitize any string of text to single line, no HTML, and no specific max-length (unless given) 
$sanitizer->lines(string $value)
stringSanitize input string as multi-line text, no HTML tags, and no specific max length (unless given) 
$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 arrayRemoves 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)
string int bool mixedSanitizes a string value that needs to go in a ProcessWire selector 
$sanitizer->selectorValueAdvanced($value)
bool mixed stringSanitize selector value for advanced text search operator (#=) 
$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->textdomain(string $value)
stringSanitize as language textdomain 
$sanitizer->trim(string $str)
stringTrim off all known UTF-8 whitespace types (or given chars) from beginning and ending of string 
$sanitizer->trunc(string $str)
stringTruncate string to given maximum length without breaking words and with no added visible extras 
$sanitizer->truncate(string $str)
stringTruncate string to given maximum length without breaking words 
$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 
$sanitizer->word(string $value)
stringReturn first word in given string 
$sanitizer->words($value)
stringGiven string return a new string containing only words 

Arrays

NameReturnSummary 
$sanitizer->array($value)
arraySanitize array or CSV string to array of values, optionally sanitized by given method
$sanitizer->arrayVal(mixed $value)
arraySimply sanitize value to array with no conversions 
$sanitizer->entitiesA($value)
array string int float boolEntity encode with support for [A]rrays and other non-string values 
$sanitizer->entitiesA1($value)
array string int float boolSame as entitiesA() but does not double encode 
$sanitizer->flatArray(array $value)
arrayGiven a potentially multi-dimensional array, return a flat 1-dimensional array 
$sanitizer->intArray($value)
arraySanitize array or CSV string to array of unsigned integers (or signed integers if specified $min is less than 0) 
$sanitizer->intArrayVal($value)
arraySanitize array to be all unsigned integers with no conversions 
$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 
$sanitizer->wordsArray($value)
arrayReturn 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)
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->getAll()
arrayGet all sanitizer method names and optionally types they return 
$sanitizer->getNumberTools()
WireNumberToolsGet instance of WireNumberTools 
$sanitizer->getTextTools()
WireTextToolsGet instance of WireTextTools 
$sanitizer->maxLength($value)
array bool float int stringLimit length of given value to that specified 
$sanitizer->purifier()
MarkupHTMLPurifierReturn a new HTML Purifier instance 
$sanitizer->sanitize(mixed $value)
string int array float nullCall a sanitizer method indirectly where method name can contain combined/combo methods 
$sanitizer->testAll(mixed $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.236

Latest news

  • ProcessWire Weekly #514
    In the 514th issue of ProcessWire Weekly we'll check out the latest blog post from Ryan, introduce two new third party modules — Page List Versions Counter and Fieldtype Fieldset Panel — and more. Read on!
    Weekly.pw / 16 March 2024
  • Invoices Site Profile
    The new invoices site profile is a free invoicing application developed in ProcessWire. It enables you to create invoices, record payments to them, email invoices to clients, print invoices, and more. This post covers all the details.
    Blog / 15 March 2024
  • Subscribe to weekly ProcessWire news

“ProcessWire is like a breath of fresh air. So powerful yet simple to build with and customise, and web editors love it too.” —Margaret Chatwin, Web developer