What exactly does the "search" method do in active record models?


Every model I generate using Gii, has a method named "search" and a validation rule with the "search" as scenario.

I’m wondering, what exactly does this method do and is it safe to remove it?

I swear I googled it but all the result I found were pointing to find() and findAll() methods :P



imagine: if without ‘safe’ on ‘search’ validator, you might be able to search ‘password’ or other invisible fields which you never want to do;

Have a look at this post.

It looks like you can use search to find all records that match the values you want to search on. In the example listed in the post, they have a form that allows somebody to search a database and the models are returned in the grid widget below. As to rootbeers point, you don’t want somebody to keep entering a password and hoping it returns a match, because then you know their login!

I’ve always used one of the find methods in my app.

But I’m sure you could do something like this:

$model = new Model();

$model->username = 'cnick79';

$dataProvider = $model->search();

Gii-generated ‘search’ method is one of the best things that yii offers you.

I strongly recommend you not to remove it.

CActiveDataProvider is a kind of query executor that you can give it to a CGridView or CListView.

It is not an array of objects like the one that ‘findAll()’ returns. It is an object that can return an array of objects according to the criteria that you specified. And you will not use it directly, but a CGridView or CListView will use it when it shows the items.

Further more, it will modify the search criteria regarding the order and the offset and limit dynamically according to the requests of sorting and pagination from the grid or the list.

You could examine how it is used in gii-generated CRUD.

‘index’ page uses CListView widget, and the widget uses a CActiveDataProvider instance that ‘search’ method has created.

And also the CGridView widget in ‘admin’ page uses a CActiveDataProvider instance that the same ‘search’ method has created.

CActiveDataProvider + (CGridView or CListView) is one of the most powerful tools that Yii has for you, and ‘search’ method in model is a vital part when you want to use it.

Please don’t miss it. :)

Your can customize ‘search’ method to satisfy your needs, or can have multiple ‘searchXxx’ methods for specific purposes. You can take the gii-generated one just as a skeleton or a template.

I’ve just written a wiki on this subject. Please take a look at it.

CGridView, CListView and CActiveDataProvider

It also deal with the gii-generated "search" function.

I hope it will be of some help to the ones relatively new to Yii. :)

I also want all of you to give me feedback to improve the wiki article. Comments, corrections and suggestions are welcome. :)

Thank you all for replying.

I think I have a better understanding of what this method does now.

it searches the loaded properties of current record in the database table, and returns a datastore containing matching records. so if I don’t use the returning datastore at all then I can safely remove the search method. is this correct?


“$this” in “search” method is an instance of the model, but it’s just a holder of the search parameters initially set to empty. It’s not the actual data in the database.

Um, No.

Maybe you are mixing up.

"search" method returns an instance of CActiveDataProvider, not an array of AR objects.

An instance of CActiveDataProvider does provide an array of AR objects.

But usually it’s not you that request it to return the result. Usually CGridView or CListView will do it for you.

If you are sure that you will not use CGridView or CListView for your current model, then I think it’s safe to remove “search” method.