Versions
Look up a class, method, property or event

CActiveDataProvider

Package system.web
Inheritance class CActiveDataProvider » CDataProvider » CComponent
Implements IDataProvider
Since 1.1
Source Code framework/web/CActiveDataProvider.php
CActiveDataProvider implements a data provider based on ActiveRecord.

CActiveDataProvider provides data in terms of ActiveRecord objects which are of class modelClass. It uses the AR CActiveRecord::findAll method to retrieve the data from database. The criteria property can be used to specify various query options.

CActiveDataProvider may be used in the following way:
$dataProvider=new CActiveDataProvider('Post', array(
    'criteria'=>array(
        'condition'=>'status=1',
        'order'=>'create_time DESC',
        'with'=>array('author'),
    ),
    'countCriteria'=>array(
        'condition'=>'status=1',
        // 'order' and 'with' clauses have no meaning for the count query
    ),
    'pagination'=>array(
        'pageSize'=>20,
    ),
));
// $dataProvider->getData() will return a list of Post objects

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
countCriteria CDbCriteria Returns the count query criteria. CActiveDataProvider
criteria CDbCriteria Returns the query criteria. CActiveDataProvider
data array Returns the data items currently available. CDataProvider
id string Returns the ID that uniquely identifies the data provider. CDataProvider
itemCount integer Returns the number of data items in the current page. CDataProvider
keyAttribute string the name of key attribute for modelClass. CActiveDataProvider
keys array Returns the key values associated with the data items. CDataProvider
model CActiveRecord the AR finder instance (eg Post::model()). CActiveDataProvider
modelClass string the primary ActiveRecord class name. CActiveDataProvider
pagination CPagination|false Returns the pagination object. CDataProvider
sort CSort Returns the sorting object. CActiveDataProvider
totalItemCount integer Returns the total number of data items. CDataProvider

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__construct() Constructor. CActiveDataProvider
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__unset() Sets a component property to be null. CComponent
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
getCountCriteria() Returns the count query criteria. CActiveDataProvider
getCriteria() Returns the query criteria. CActiveDataProvider
getData() Returns the data items currently available. CDataProvider
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getId() Returns the ID that uniquely identifies the data provider. CDataProvider
getItemCount() Returns the number of data items in the current page. CDataProvider
getKeys() Returns the key values associated with the data items. CDataProvider
getPagination() Returns the pagination object. CDataProvider
getSort() Returns the sorting object. CActiveDataProvider
getTotalItemCount() Returns the total number of data items. CDataProvider
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
raiseEvent() Raises an event. CComponent
setCountCriteria() Sets the count query criteria. CActiveDataProvider
setCriteria() Sets the query criteria. CActiveDataProvider
setData() Sets the data items for this provider. CDataProvider
setId() Sets the provider ID. CDataProvider
setKeys() Sets the data item keys for this provider. CDataProvider
setPagination() Sets the pagination for this data provider. CDataProvider
setSort() Sets the sorting for this data provider. CDataProvider
setTotalItemCount() Sets the total number of data items. CDataProvider

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
calculateTotalItemCount() Calculates the total number of data items. CActiveDataProvider
fetchData() Fetches the data from the persistent data storage. CActiveDataProvider
fetchKeys() Fetches the data item keys from the persistent data storage. CActiveDataProvider
getModel() Given active record class name returns new model instance. CActiveDataProvider

Property Details

countCriteria property (available since v1.1.14)
public CDbCriteria getCountCriteria()
public void setCountCriteria(CDbCriteria|array $value)

Returns the count query criteria.

criteria property
public CDbCriteria getCriteria()
public void setCriteria(CDbCriteria|array $value)

Returns the query criteria.

keyAttribute property
public string $keyAttribute;

the name of key attribute for modelClass. If not set, it means the primary key of the corresponding database table will be used.

model property (available since v1.1.3)
public CActiveRecord $model;

the AR finder instance (eg Post::model()). This property can be set by passing the finder instance as the first parameter to the constructor. For example, Post::model()->published().

modelClass property
public string $modelClass;

the primary ActiveRecord class name. The getData() method will return a list of objects of this class.

sort property
public CSort getSort(string $className='CSort')
public void setSort(mixed $value)

Returns the sorting object.

Method Details

__construct() method
public void __construct(mixed $modelClass, array $config=array ( ))
$modelClass mixed the model class (e.g. 'Post') or the model finder instance (e.g. Post::model(), Post::model()->published()).
$config array configuration (name=>value) to be applied as the initial property values of this class.
Source Code: framework/web/CActiveDataProvider.php#82 (show)
public function __construct($modelClass,$config=array())
{
    if(
is_string($modelClass))
    {
        
$this->modelClass=$modelClass;
        
$this->model=$this->getModel($this->modelClass);
    }
    elseif(
$modelClass instanceof CActiveRecord)
    {
        
$this->modelClass=get_class($modelClass);
        
$this->model=$modelClass;
    }
    
$this->setId(CHtml::modelName($this->model));
    foreach(
$config as $key=>$value)
        
$this->$key=$value;
}

Constructor.

calculateTotalItemCount() method
protected integer calculateTotalItemCount()
{return} integer the total number of data items.
Source Code: framework/web/CActiveDataProvider.php#223 (show)
protected function calculateTotalItemCount()
{
    
$baseCriteria=$this->model->getDbCriteria(false);
    if(
$baseCriteria!==null)
        
$baseCriteria=clone $baseCriteria;
    
$count=$this->model->count($this->getCountCriteria());
    
$this->model->setDbCriteria($baseCriteria);
    return 
$count;
}

Calculates the total number of data items.

fetchData() method
protected array fetchData()
{return} array list of data items
Source Code: framework/web/CActiveDataProvider.php#172 (show)
protected function fetchData()
{
    
$criteria=clone $this->getCriteria();

    if((
$pagination=$this->getPagination())!==false)
    {
        
$pagination->setItemCount($this->getTotalItemCount());
        
$pagination->applyLimit($criteria);
    }

    
$baseCriteria=$this->model->getDbCriteria(false);

    if((
$sort=$this->getSort())!==false)
    {
        
// set model criteria so that CSort can use its table alias setting
        
if($baseCriteria!==null)
        {
            
$c=clone $baseCriteria;
            
$c->mergeWith($criteria);
            
$this->model->setDbCriteria($c);
        }
        else
            
$this->model->setDbCriteria($criteria);
        
$sort->applyOrder($criteria);
    }

    
$this->model->setDbCriteria($baseCriteria!==null ? clone $baseCriteria null);
    
$data=$this->model->findAll($criteria);
    
$this->model->setDbCriteria($baseCriteria);  // restore original criteria
    
return $data;
}

Fetches the data from the persistent data storage.

fetchKeys() method
protected array fetchKeys()
{return} array list of data item keys.
Source Code: framework/web/CActiveDataProvider.php#208 (show)
protected function fetchKeys()
{
    
$keys=array();
    foreach(
$this->getData() as $i=>$data)
    {
        
$key=$this->keyAttribute===null $data->getPrimaryKey() : $data->{$this->keyAttribute};
        
$keys[$i]=is_array($key) ? implode(',',$key) : $key;
    }
    return 
$keys;
}

Fetches the data item keys from the persistent data storage.

getCountCriteria() method (available since v1.1.14)
public CDbCriteria getCountCriteria()
{return} CDbCriteria the count query criteria.
Source Code: framework/web/CActiveDataProvider.php#125 (show)
public function getCountCriteria()
{
    if(
$this->_countCriteria===null)
        return 
$this->getCriteria();
    return 
$this->_countCriteria;
}

Returns the count query criteria.

getCriteria() method
public CDbCriteria getCriteria()
{return} CDbCriteria the query criteria
Source Code: framework/web/CActiveDataProvider.php#103 (show)
public function getCriteria()
{
    if(
$this->_criteria===null)
        
$this->_criteria=new CDbCriteria;
    return 
$this->_criteria;
}

Returns the query criteria.

getModel() method (available since v1.1.14)
protected CActiveRecord getModel(string $className)
$className string active record class name.
{return} CActiveRecord active record model instance.
Source Code: framework/web/CActiveDataProvider.php#163 (show)
protected function getModel($className)
{
    return 
CActiveRecord::model($className);
}

Given active record class name returns new model instance.

getSort() method
public CSort getSort(string $className='CSort')
$className string the sorting object class name. Parameter is available since version 1.1.13.
{return} CSort the sorting object. If this is false, it means the sorting is disabled.
Source Code: framework/web/CActiveDataProvider.php#148 (show)
public function getSort($className='CSort')
{
    if((
$sort=parent::getSort($className))!==false)
        
$sort->modelClass=$this->modelClass;
    return 
$sort;
}

Returns the sorting object.

setCountCriteria() method (available since v1.1.14)
public void setCountCriteria(CDbCriteria|array $value)
$value CDbCriteria|array the count query criteria. This can be either a CDbCriteria object or an array representing the query criteria.
Source Code: framework/web/CActiveDataProvider.php#138 (show)
public function setCountCriteria($value)
{
    
$this->_countCriteria=$value instanceof CDbCriteria $value : new CDbCriteria($value);
}

Sets the count query criteria.

setCriteria() method
public void setCriteria(CDbCriteria|array $value)
$value CDbCriteria|array the query criteria. This can be either a CDbCriteria object or an array representing the query criteria.
Source Code: framework/web/CActiveDataProvider.php#115 (show)
public function setCriteria($value)
{
    
$this->_criteria=$value instanceof CDbCriteria $value : new CDbCriteria($value);
}

Sets the query criteria.

Total 5 comments

#7217 report it
c@cba at 2012/03/05 10:50am
Add `order` to the `$criteria` within the `search()` method of your model class

I tried to add the following to my search() method, to sort the results according to the column 'ordering':

$criteria=new CDbCriteria;
... // compare statements...
$criteria->order = 'ordering asc'; // <--- ADDED THIS, DIDN'T WORK
return new CActiveDataProvider(get_class($this), array(
    'criteria'=>$criteria,
));

The following did work:

$criteria=new CDbCriteria;
... // compare statements...
$criteria->order = 't.ordering asc'; // <--- CHANGED ordering TO t.ordering, WORKED
return new CActiveDataProvider(get_class($this), array(
    'criteria'=>$criteria,
));
#5444 report it
Rohit Duhan at 2011/10/12 02:04pm
Limit in Mssql

If you are trying to limit the dataProvider results with your criteria, make sure to set the pagination to false.

for example

   $dataProvider = new CActiveDataProvider('xxxxxx',array(
                    'criteria'=>array(                          
                      'condition'=>'yyyyy IS NULL',
                      'order'=>'id DESC',                          
                      'limit'=>5,
                    ),

You will have to use to set pagination to false to set the limit to 5, if not it won't work.

$dataProvider->setPagination(false);

#4208 report it
MetaYii at 2011/06/15 07:59pm
Using "with"

If you want to get a list of blog posts (Post model) including the author (Author model) and you use with('author') to refer to the relationship and get the data with eager loading (recommended), and then use the data provider in a CListView, for example, you'll have to do this in your partial view which renders the items:

<?= $data->post->author ?>

It is wrong if you do this:

<?= $data->author ?>
#2223 report it
Steve Friedl at 2010/11/28 12:06pm
First parameter can be a finder for model objects, but not an array of model objects

CActiveDataProvider normally takes a class name ('Post') plus some DB Criteria (either as an array, or an explicit CDbCriteria object), but it can also take a first param of a finder object, which implies both the model class and the criteria.

This finder object can be enhanced with named scopes and parameterized scopes (in any combination), as they merely refine the criteria without actually fetching anything from the database.

(These examples assume that 'published' and 'byAuthor' are scopes defined by the user in the 'Post' model file)

$dp = new CActiveDataProvider( Post::model() );    
$db = new CActiveDataProvider( Post::model()->published() );   // named scope
$db = new CActiveDataProvider( Post::model()->byAuthor($au) ); // parameterized scope
 
// BUT NOT THIS:
$db = new CActiveDataProvider( Post::model()->published()->findAll(); // NO NO NO

The last one is a common mistake, where the findAll() call actually queries the DB and turns the list of criteria into an actual array of model objects. CActiveDataProvider doesn't know what to do in this case, so it produces a failure:

Fatal error: Call to a member function getDbCriteria() on a non-object in (path)/framework/web/CActiveDataProvider.php on line 114

The solution is to remove any findXXX() methods.

Alternately, if you want a data provider populated with an array, use the CArrayDataProvider() which works that way.

#203 report it
edwaa at 2010/08/11 07:57pm
compare + static criteria

make sure you define your static (unchanging) criteria before you define your compare values.

This will work:

> $criteria=new CDbCriteria;
 
> $criteria->condition='isActive = 1';
 
> $criteria->compare('username',$this->username,true);
> $criteria->compare('name',$this->name,true);
> $criteria->compare('email',$this->email,true);
 
> return new CActiveDataProvider('User', array(
>   'criteria'=>$criteria,
> ));

This won't work:

> $criteria=new CDbCriteria;
 
> $criteria->compare('username',$this->username,true);
> $criteria->compare('name',$this->name,true);
> $criteria->compare('email',$this->email,true);
 
> $criteria->condition='isActive = 1';
 
> return new CActiveDataProvider('User', array(
>   'criteria'=>$criteria,
> ));

Leave a comment

Please to leave your comment.