Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
tree: bddd2626c1
Fetching contributors…

Cannot retrieve contributors at this time

241 lines (188 sloc) 8.047 kb
layout title
documentation
Validators

Validators

Validators help you to validate an input before persisting it to the database. In Propel, validators are rules describing what type of data a column accepts. Validators are referenced in the schema.xml file, using <validator> tags.

Validators are applied at the PHP level, they are not created as constraints on the database itself. That means that if you also use another language to work with the database, the validator rules will not be enforced. You can also apply multiple rule entries per validator entry in the schema.xml file.

Overview

In the following example, the username column is defined to have a minimum length of 4 characters:

{% highlight xml %}

{% endhighlight %}

Every column rule is represented by a <rule> tag. A <validator> is a set of <rule> tags bound to a column.

At runtime, you can validate an instance of the model by calling the validate() method:

{% highlight php %} <?php $user = new User(); $user->setUsername("foo"); // only 3 in length, which is too short... if ($user->validate()) { // no validation errors, so the data can be persisted $user->save(); } else { // Something went wrong. // Use the validationFailures to check what foreach ($objUser->getValidationFailures() as $failure) { echo $failure->getMessage() . "\n"; } } {% endhighlight %}

validate() returns a boolean. If the validation failed, you can access the array ValidationFailed objects by way of the getValidationFailures() method. Each ValidationFailed instance gives access to the column, the message and the validator that caused the failure.

Core Validators

Propel bundles a set of validatorts that should help you deal with the most common cases.

MatchValidator

The MatchValidator is used to run a regular expression of choice against the column. Note that this is a preg, not ereg (check the preg_match documentation for more information about regexps).

{% highlight xml %} <!-- allow strings that match the email address pattern --> {% endhighlight %}

NotMatchValidator

Opposite of MatchValidator, this validator returns false if the regex returns true

{% highlight xml %} <!-- disallow everything that's not a digit or minus --> {% endhighlight %}

MaxLengthValidator

When you want to limit the size of the string to be inserted in a column, use the MaxLengthValidator. Internally, it uses strlen() to get the length of the string. For instance, some database completely ignore the length of LONGVARCHAR columns; you can enforce it using a validator:

{% highlight xml %} {% endhighlight %}

Tip
If you have specified the size attribute in the <column> tag, you don't have to specify the value attribute in the validator rule again, as this is done automatically.

MinLengthValidator

{% highlight xml %} {% endhighlight %}

MaxValueValidator

To limit the value of an integer column, use the MaxValueValidator. Note that this validator uses a non-strict comparison ('less than or equal'):

{% highlight xml %} {% endhighlight %}

MinValueValidator

{% highlight xml %} {% endhighlight %}

Tip
You can run multiple validators against a single column.

{% highlight xml %} {% endhighlight %}

RequiredValidator

This validator checks the same rule as a required=true on the column at the database level. This, however, will give you a clean error to work with.

{% highlight xml %} {% endhighlight %}

UniqueValidator

To check whether the value already exists in the table, use the UniqueValidator:

{% highlight xml %} {% endhighlight %}

ValidValuesValidator

This rule restricts the valid values to a list delimited by a pipe ('|').

{% highlight xml %} {% endhighlight %}

TypeValidator

Restrict values to a certain PHP type using the TypeValidator:

{% highlight xml %} {% endhighlight %}

Adding A Custom Validator

You can easily add a custom validator. A validator is a class extending BasicValidator providing a public isValid() method. For instance:

{% highlight php %} <?php require_once 'propel/validator/BasicValidator.php';

/**

  • A simple validator for email fields. *
  • @package propel.validator */ class EmailValidator implements BasicValidator { public function isValid(ValidatorMap $map, $str) { return preg_match('/^([^@\s]+)@((?:[-a-z0-9]+.)+[a-z]{2,})$/i', $str) !== 0; } } {% endhighlight %}

The ValidatorMap instance passed as parameter gives you access to the rules attribute as defined in the <rule> tag. So $map->getValue() returns the value attribute.

Tip
Make sure that isValid() returns a boolean, so really true or false. Propel is very strict about this. Returning a mixed value just won't do.

To enable the new validator on a column, add a corresponding <rule> in your schema and use 'class' as the rule name.

{% highlight xml %} {% endhighlight %}

The class attribute of the <rule> tag should contain a path to the validator class accessible from the include_path, where the directory separator is replaced by a dot.

Jump to Line
Something went wrong with that request. Please try again.