1. Code
  2. Yii

How to Program With Yii2: Validations

This post is part of a series called How to Program With Yii2.
How to Program With Yii2: Timestamp Behavior
How to Program With Yii2: Specialized Validations
Final product image
What You'll Be Creating

If you're asking, "what's Yii?" check out my earlier tutorial: Introduction to the Yii Framework, which reviews the benefits of Yii and includes an overview of what's new in Yii 2.0, released in October 2014.

In this Programming With Yii2 series, I'm guiding readers in use of the newly upgraded Yii2 Framework for PHP. In this tutorial, I'm going to introduce you to Yii2's validators. Validators simplify the code needed to validate input, i.e. verify conformance or non-conformance of data input, typically from users via web forms.

For these examples, we'll continue to leverage the Hello application codebase we've used in past tutorials. Use the GitHub links on this page to get the code.

Just a reminder, I do participate in the comment threads below. I'm especially interested if you have additional ideas or want to suggest topics for future tutorials. You can also reach me @reifman on Twitter. 

What Is a Validator?

If you're a web developer, you likely know that user input can't be trusted. For example, users can use SQL injection techniques to try to run queries that change or expose passwords. Someone once leveraged SQL injection against my open source PHPList installation and managed to discover one of my passwords (PHPList stored these in plain text). More commonly, you just want to ensure that the data that users provide conforms to the types, forms and ranges of your application.

Building validators in PHP by hand takes time. The Yii Framework provides a ton of baseline validation features so there's no need to build them from scratch. But, if you need some custom extensions, that's straightforward as well.

Validations are yet another reason why I think it always makes sense to build applications on a web framework such as Yii rather than vanilla PHP.

In earlier episodes, we've also talked a lot about Yii's code generator, Gii. One of the benefits of Gii is that it will write the appropriate validation rules for your models based on the SQL type definitions in the schema. This is a big time saver.

What Validations Does Yii Support?

Here's a list of the built in Yii validators and links to documentation:

How Yii Validation Works

Here's how Yii describes the flow of validation. Typically, you can use the default scenario and don't need to build your own. You'll generally need to rely on Gii to generate rules or write your own.

When the validate() method is called, it goes through the following steps to perform validation:

  1. Determine which attributes should be validated by getting the attribute list from yii\base\Model::scenarios() using the current scenario. These attributes are called active attributes.
  2. Determine which validation rules should be used by getting the rule list from yii\base\Model::rules() using the current scenario. These rules are called active rules
  3. Use each active rule to validate each active attribute which is associated with the rule. The validation rules are evaluated in the order they are listed.

According to the above validation steps, an attribute will be validated if and only if it is an active attribute declared in scenarios() and is associated with one or multiple active rules declared in rules().

Example of Model Validation Rules

Here's what a set of model validation rules may look like. I've taken these from the Meeting Planner application Place model:

As we implement our own validation examples further below, you'll learn what each of the definitions above represent.

Example of Displaying Errors

There are a couple of ways to access the errors returned by validation. 

Here's an example of getting the array of errors in the controller:

And here's an example of leveraging Yii's errorSummary function within ActiveForms:

Here's what it looks like:

Using Yii errorSummary to display form errors

Advanced Validation

In later episodes, I'll also give examples of making use of advanced validation features:

For now, let's begin walking through examples of the various kinds of built-in validators.

Basic Field Validators

Let's look at some of the basic field validators which are helpful to everyday form implementation.

Preparing a Model Using Migrations and Gii

As we've done in early episodes of this series, I'm going to create a migration:

I'll create a Sample model to create some example schema and validations using Gii. Here's the migration code:

Then, we'll run the migration:

Then, we'll use Yii's code generator to build a model:

Validation Yiis Gii Model Generator

And then CRUD files:

Validation Yiis Gii CRUD Generator

Gii generates these sample validation rules:

Now, let's use these to work with and walk through some of the basic validators.

Required Validator

The RequiredValidator ensures a value is present. You can see it in place above for rank, censorship and occurred.

Visit the Sample Create form generated by Gii, e.g. http://localhost:8888/hello/sample/create. Yii's ActiveForm JavaScript client-validation will present an error message even when you tab away from one of these fields.

Validators Required With JavaScript Client Side Validation

Safe Validator

The SafeValidator is not a true validator. It allows massive assignment of a posted web form to include an attribute. e.g. $model->attributes = $_POST['Comment']. Or, in the Gii created SampleController, you can see this code:

Without the safe rule in the Sample model (or another rule), the occurred value would not be assigned to the model attributes. This reduces the likelihood of an additional attack vector without deliberate code.

Default Value Validator

The DefaultValueValidator is not a true validator. It sets default values for empty fields.

Let's change the rule for occurred to set a default date value using the current date. We'll also remove the required validator to allow the default validator to fill the value.

When we create a new Sample and leave the occurred field blank, you can see the resulting view includes the current date filled in by the default value validator.

Validators Default Value


The FilterValidator is also not a true validator. It performs a transformation on a provided value. Most commonly, you might use this to trim whitespace off the ends of a string. 

FilterValidators are defined with inline function callbacks such as this custom validation function:

Since trim is a native PHP function, we can just declare our validation rule inline:

If you submit a form with pre-pending or trailing spaces on the thought field, the FilterValidator will remove them.

Now, let's look at some of the built-in type validators.

The Type Validators

Type validators ensure that user data conforms to specific types, often those specified in your database schema. Gii will generate these automatically.

String and Number Validator

The StringValidator ensures a value is a string. The NumberValidator ensures a value is numeric, e.g. integer or float. 

Here are sample rule definitions:

I'm also temporarily removing the required validation to see how string and number validations work independently.

Here's what the validation error messages will look like:

Validators Number and String

Goodness as high fails because it's not a number, whereas rank as 27 passes. Censorship is blank (NULL) and fails the string validation.

Boolean Validator

The BooleanValidator ensures a value is true or false. You can define the values for true and false. The defaults are integer 0 or 1. This validator may be more useful when the field is used with a drop-down selector, e.g. Yes / No.

Here's how I defined my rule for Boolean:

Here's the boolean validator error message:

Validators Boolean

Date Validator

The DateValidator ensures the value is a properly formatted date which can be customized with a format attribute. With Yii ActiveForm, this is currently a server side validation. Therefore, I also added back a required rule for the Occurred field.

Here are my rule definitions with the Date validator for the Occurred field:

Here's what it looks like when we submit the form:

Validators Date

What's Next?

Watch for upcoming tutorials in my Programming With Yii2 series as I continue diving into different aspects of the framework. In the next two episodes, I'll guide you through the remaining validators and show you how to build advanced extensions to Yii's validation framework.

You may also want to check out my Building Your Startup With PHP series, which is using Yii2's advanced template as I build a real world application.

I welcome feature and topic requests. You can post them in the comments below, ping me @reifman on Twitter, or email me at my Lookahead Consulting website.

If you'd like to know when the next Yii2 tutorial arrives, check my Tuts+ instructor page. It always includes all my articles immediately after they are published. 

Related Links

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.