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]](images/note.png)
|
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. |
These filters are added to these column types automatically.
| 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 |
|
|
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. |
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.
<?php
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.
(Click on each to see its description.)
(Click on each to see its description.)