3.7. Record Filters

Filters provide a way to automatically sanitize and validate the properties of a model record. The model system uses the independent Solar_Filter for its filters (click on the link to see the list of available filter classes).

The model automatically adds certain filters based on the database column definition, and you can add your own as well. When you save() a record object, these filters are applied in sequence (the automatic ones are applied last). If any of the validation filters fail, the save() will fail as well.

[Note] Filter, Sanitize, and Validate

These terms may have different meanings in other frameworks. In Solar, a "filter" is the generic term for sanitizing and/or validating data. To "sanitize" means to change the data as necessary to make it match a particular format or set of criteria. To "validate" means to check the if data matches a particular format or set of criteria, without changing the data itself. You can do both to any piece of data, in whatever order you like, depending on your needs.

3.7.1. Automatic Filters

These filters are added to these column types automatically.

Table 3.1. Filters Added Automatically In Models
Column Info Filters Added
boolean validateBool and sanitizeBool
char and varchar validateString, validateMaxLength for the defined column width, and sanitizeString
smallint, int, and bigint validateInt, validateRange for the lowest and highest allowed values of each integer type, and sanitizeInt.
numeric (fixed-point decimal) validateNumeric, validateSizeScope for the defines column size and scope, and sanitizeNumeric
float (double) validateFloat and sanitizeFloat
clob (none)
date validateIsoDate and sanitizeIsoDate
time validateIsoTime and sanitizeIsoTime
timestamp (datetime) validateIsoTimestamp and sanitizeIsoTimestamp
[Note] What about NOT NULL columns?

Because of the way Solar_Filter works, a particular piece of data is not defined as "required" until filtering actually occurs. This is because if a piece of data is missing, it won't be filtered, because there's nothing to filter. As such, NOT NULL columns are checked if they are present and not blank, but this is done programmatically as part of the filtering logic, not as a separate filter. You can still add validateNotBlank on your own to make sure properties, when present, are filled in.

3.7.2. Adding Filters

To add one or more filters to a model, edit the model _setup() method and call $this->_addFilter() with the record property name, the filter name, and the parameters (if any) for the filter.

class Vendor_Model_Foo extends Vendor_Sql_Model
    public function _setup()
        // validate that a username is only alphanumeric characters
        $this->_addFilter('user_handle', 'validateAlnum');
        // validate column 'user_email' is not blank, and is an email address
        $this->_addFilter('user_email', 'validateNotBlank');
        $this->_addFilter('user_email', 'validateEmail');
        // validate column 'foo' is at least 8 characters long,
        // and has at least one non-alphanumeric character
        $this->_addFilter('foo', 'validateMinLength', 8);
        $this->_addFilter('foo', 'validatePregMatch', '/[^a-zA-Z0-9]/');
        // make sure the column 'bar' is one of a list of approved values
        $this->_addFilter('bar', 'validateInList', array(
            'baz', 'dib', 'zim', 'gir',

Now when you save() a record from that model, those filters will be applied before inserting or updating to the database. If any of them fail, the save() will fail.