0 follower

CDbFixtureManager

Package	system.test
Inheritance	class CDbFixtureManager » CApplicationComponent » CComponent
Implements	IApplicationComponent
Since	1.1
Source Code	framework/test/CDbFixtureManager.php

CDbFixtureManager manages database fixtures during tests.

A fixture represents a list of rows for a specific table. For a test method, using a fixture means that at the beginning of the method, the table has and only has the rows that are given in the fixture. Therefore, the table's state is predictable.

A fixture is represented as a PHP script whose name (without suffix) is the same as the table name (if schema name is needed, it should be prefixed to the table name). The PHP script returns an array representing a list of table rows. Each row is an associative array of column values indexed by column names.

A fixture can be associated with an init script which sits under the same fixture directory and is named as "TableName.init.php". The init script is used to initialize the table before populating the fixture data into the table. If the init script does not exist, the table will be emptied.

Fixtures must be stored under the basePath directory. The directory may contain a file named "init.php" which will be executed once to initialize the database. If this file is not found, all available fixtures will be loaded into the database.

Public Properties

Hide inherited properties

Property	Type	Description	Defined By
basePath	string	the base path containing all fixtures.	CDbFixtureManager
behaviors	array	the behaviors that should be attached to this component.	CApplicationComponent
connectionID	string	the ID of the database connection.	CDbFixtureManager
dbConnection	CDbConnection	Returns the database connection used to load fixtures.	CDbFixtureManager
fixtures	array	Returns the information of the available fixtures.	CDbFixtureManager
initScript	string	the name of the initialization script that would be executed before the whole test set runs.	CDbFixtureManager
initScriptSuffix	string	the suffix for fixture initialization scripts.	CDbFixtureManager
isInitialized	boolean	Checks if this application component has been initialized.	CApplicationComponent
schemas	array	list of database schemas that the test tables may reside in.	CDbFixtureManager

Public Methods

Hide inherited methods

Method	Description	Defined By
__call()	Calls the named method which is not a class method.	CComponent
__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
checkIntegrity()	Enables or disables database integrity check.	CDbFixtureManager
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
getDbConnection()	Returns the database connection used to load fixtures.	CDbFixtureManager
getEventHandlers()	Returns the list of attached event handlers for an event.	CComponent
getFixtures()	Returns the information of the available fixtures.	CDbFixtureManager
getIsInitialized()	Checks if this application component has been initialized.	CApplicationComponent
getRecord()	Returns the specified ActiveRecord instance in the fixture data.	CDbFixtureManager
getRows()	Returns the fixture data rows.	CDbFixtureManager
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
init()	Initializes this application component.	CDbFixtureManager
load()	Loads the specified fixtures.	CDbFixtureManager
loadFixture()	Loads the fixture for the specified table.	CDbFixtureManager
prepare()	Prepares the fixtures for the whole test.	CDbFixtureManager
raiseEvent()	Raises an event.	CComponent
resetTable()	Resets the table to the state that it contains no fixture data.	CDbFixtureManager
truncateTable()	Removes all rows from the specified table and resets its primary key sequence, if any.	CDbFixtureManager
truncateTables()	Truncates all tables in the specified schema.	CDbFixtureManager

Property Details

basePath property

public string $basePath;

the base path containing all fixtures. Defaults to null, meaning the path 'protected/tests/fixtures'.

connectionID property

public string $connectionID;

the ID of the database connection. Defaults to 'db'. Note, data in this database may be deleted or modified during testing. Make sure you have a backup database.

dbConnection property read-only

public CDbConnection getDbConnection()

Returns the database connection used to load fixtures.

fixtures property read-only

public array getFixtures()

Returns the information of the available fixtures. This method will search for all PHP files under basePath. If a file's name is the same as a table name, it is considered to be the fixture data for that table.

initScript property

public string $initScript;

the name of the initialization script that would be executed before the whole test set runs. Defaults to 'init.php'. If the script does not exist, every table with a fixture file will be reset.

initScriptSuffix property

public string $initScriptSuffix;

the suffix for fixture initialization scripts. If a table is associated with such a script whose name is TableName suffixed this property value, then the script will be executed each time before the table is reset.

schemas property

public array $schemas;

list of database schemas that the test tables may reside in. Defaults to array(''), meaning using the default schema (an empty string refers to the default schema). This property is mainly used when turning on and off integrity checks so that fixture data can be populated into the database without causing problem.

Method Details

checkIntegrity() method

public void checkIntegrity(boolean $check)
$check	boolean	whether to enable database integrity check

Source Code: framework/test/CDbFixtureManager.php#236 (show)


public function checkIntegrity($check)
{
    foreach($this->schemas as $schema)
        $this->getDbConnection()->getSchema()->checkIntegrity($check,$schema);
}

Enables or disables database integrity check. This method may be used to temporarily turn off foreign constraints check.

getDbConnection() method

public CDbConnection getDbConnection()
{return}	CDbConnection	the database connection

Source Code: framework/test/CDbFixtureManager.php#95 (show)


public function getDbConnection()
{
    if($this->_db===null)
    {
        $this->_db=Yii::app()->getComponent($this->connectionID);
        if(!$this->_db instanceof CDbConnection)
            throw new CException(Yii::t('yii','CDbTestFixture.connectionID "{id}" is invalid. Please make sure it refers to the ID of a CDbConnection application component.',
                array('{id}'=>$this->connectionID)));
    }
    return $this->_db;
}

Returns the database connection used to load fixtures.

getFixtures() method

public array getFixtures()
{return}	array	the information of the available fixtures (table name => fixture file)

Source Code: framework/test/CDbFixtureManager.php#206 (show)


public function getFixtures()
{
    if($this->_fixtures===null)
    {
        $this->_fixtures=array();
        $schema=$this->getDbConnection()->getSchema();
        $folder=opendir($this->basePath);
        $suffixLen=strlen($this->initScriptSuffix);
        while($file=readdir($folder))
        {
            if($file==='.' || $file==='..' || $file===$this->initScript)
                continue;
            $path=$this->basePath.DIRECTORY_SEPARATOR.$file;
            if(substr($file,-4)==='.php' && is_file($path) && substr($file,-$suffixLen)!==$this->initScriptSuffix)
            {
                $tableName=substr($file,0,-4);
                if($schema->getTable($tableName)!==null)
                    $this->_fixtures[$tableName]=$path;
            }
        }
        closedir($folder);
    }
    return $this->_fixtures;
}

getRecord() method

public CActiveRecord getRecord(string $name, string $alias)
$name	string	the fixture name
$alias	string	the alias for the fixture data row
{return}	CActiveRecord	the ActiveRecord instance. False is returned if there is no such fixture row.

Source Code: framework/test/CDbFixtureManager.php#346 (show)


public function getRecord($name,$alias)
{
    if(isset($this->_records[$name][$alias]))
    {
        if(is_string($this->_records[$name][$alias]))
        {
            $row=$this->_rows[$name][$alias];
            $model=CActiveRecord::model($this->_records[$name][$alias]);
            $key=$model->getTableSchema()->primaryKey;
            if(is_string($key))
                $pk=$row[$key];
            else
            {
                foreach($key as $k)
                    $pk[$k]=$row[$k];
            }
            $this->_records[$name][$alias]=$model->findByPk($pk);
        }
        return $this->_records[$name][$alias];
    }
    else
        return false;
}

Returns the specified ActiveRecord instance in the fixture data.

getRows() method

public array getRows(string $name)
$name	string	the fixture name
{return}	array	the fixture data rows. False is returned if there is no such fixture data.

Source Code: framework/test/CDbFixtureManager.php#332 (show)


public function getRows($name)
{
    if(isset($this->_rows[$name]))
        return $this->_rows[$name];
    else
        return false;
}

Returns the fixture data rows. The rows will have updated primary key values if the primary key is auto-incremental.

init() method

public void init()

Source Code: framework/test/CDbFixtureManager.php#82 (show)


public function init()
{
    parent::init();
    if($this->basePath===null)
        $this->basePath=Yii::getPathOfAlias('application.tests.fixtures');
    $this->prepare();
}

Initializes this application component.

load() method

public void load(array $fixtures)
$fixtures	array	fixtures to be loaded. The array keys are fixture names, and the array values are either AR class names or table names. If table names, they must begin with a colon character (e.g. 'Post' means an AR class, while ':Post' means a table name).

Source Code: framework/test/CDbFixtureManager.php#289 (show)


public function load($fixtures)
{
    $schema=$this->getDbConnection()->getSchema();
    $schema->checkIntegrity(false);

    $this->_rows=array();
    $this->_records=array();
    foreach($fixtures as $fixtureName=>$tableName)
    {
        if($tableName[0]===':')
        {
            $tableName=substr($tableName,1);
            unset($modelClass);
        }
        else
        {
            $modelClass=Yii::import($tableName,true);
            $tableName=CActiveRecord::model($modelClass)->tableName();
        }
        if(($prefix=$this->getDbConnection()->tablePrefix)!==null)
            $tableName=preg_replace('/{{(.*?)}}/',$prefix.'\1',$tableName);
        $this->resetTable($tableName);
        $rows=$this->loadFixture($tableName);
        if(is_array($rows) && is_string($fixtureName))
        {
            $this->_rows[$fixtureName]=$rows;
            if(isset($modelClass))
            {
                foreach(array_keys($rows) as $alias)
                    $this->_records[$fixtureName][$alias]=$modelClass;
            }
        }
    }

    $schema->checkIntegrity(true);
}

Loads the specified fixtures. For each fixture, the corresponding table will be reset first by calling resetTable and then be populated with the fixture data. The loaded fixture data may be later retrieved using getRows and getRecord. Note, if a table does not have fixture data, resetTable will still be called to reset the table.

loadFixture() method

public array loadFixture(string $tableName)
$tableName	string	table name
{return}	array	the loaded fixture rows indexed by row aliases (if any). False is returned if the table does not have a fixture.

Source Code: framework/test/CDbFixtureManager.php#160 (show)


public function loadFixture($tableName)
{
    $fileName=$this->basePath.DIRECTORY_SEPARATOR.$tableName.'.php';
    if(!is_file($fileName))
        throw new CException('Could not load fixture file ' . $fileName);

    $rows=array();
    $schema=$this->getDbConnection()->getSchema();
    $builder=$schema->getCommandBuilder();
    $table=$schema->getTable($tableName);

    foreach(require($fileName) as $alias=>$row)
    {
        try {
            $builder->createInsertCommand($table,$row)->execute();
        } catch (CException $e) {
            throw new CException('Exception loading row ' . $alias . ' in fixture ' . $fileName, $e->getCode(), $e);
        }
        $primaryKey=$table->primaryKey;
        if($table->sequenceName!==null)
        {
            if(is_string($primaryKey) && !isset($row[$primaryKey]))
                $row[$primaryKey]=$builder->getLastInsertID($table);
            elseif(is_array($primaryKey))
            {
                foreach($primaryKey as $pk)
                {
                    if(!isset($row[$pk]))
                    {
                        $row[$pk]=$builder->getLastInsertID($table);
                        break;
                    }
                }
            }
        }
        $rows[$alias]=$row;
    }
    return $rows;
}

Loads the fixture for the specified table. This method will insert rows given in the fixture into the corresponding table. The loaded rows will be returned by this method. If the table has auto-incremental primary key, each row will contain updated primary key value. If the fixture does not exist, this method will return false. Note, you may want to call resetTable before calling this method so that the table is emptied first.

prepare() method

public void prepare()

Source Code: framework/test/CDbFixtureManager.php#112 (show)


public function prepare()
{
    $initFile=$this->basePath . DIRECTORY_SEPARATOR . $this->initScript;

    $this->checkIntegrity(false);

    if(is_file($initFile))
        require($initFile);
    else
    {
        foreach($this->getFixtures() as $tableName=>$fixturePath)
        {
            $this->resetTable($tableName);
            $this->loadFixture($tableName);
        }
    }
    $this->checkIntegrity(true);
}

Prepares the fixtures for the whole test. This method is invoked in init. It executes the database init script if it exists. Otherwise, it will load all available fixtures.

resetTable() method

public void resetTable(string $tableName)
$tableName	string	the table name

Source Code: framework/test/CDbFixtureManager.php#139 (show)


public function resetTable($tableName)
{
    $initFile=$this->basePath . DIRECTORY_SEPARATOR . $tableName . $this->initScriptSuffix;
    if(is_file($initFile))
        require($initFile);
    else
        $this->truncateTable($tableName);
}

Resets the table to the state that it contains no fixture data. If there is an init script named "tests/fixtures/TableName.init.php", the script will be executed. Otherwise, truncateTable will be invoked to delete all rows in the table and reset primary key sequence, if any.

truncateTable() method

public void truncateTable(string $tableName)
$tableName	string	the table name

Source Code: framework/test/CDbFixtureManager.php#249 (show)


public function truncateTable($tableName)
{
    $db=$this->getDbConnection();
    $schema=$db->getSchema();
    if(($table=$schema->getTable($tableName))!==null)
    {
        $db->createCommand('DELETE FROM '.$table->rawName)->execute();
        $schema->resetSequence($table,1);
    }
    else
        throw new CException("Table '$tableName' does not exist.");
}

Removes all rows from the specified table and resets its primary key sequence, if any. You may need to call checkIntegrity to turn off integrity check temporarily before you call this method.

truncateTables() method

public void truncateTables(string $schema='')
$schema	string	the schema name. Defaults to empty string, meaning the default database schema.

Source Code: framework/test/CDbFixtureManager.php#269 (show)


public function truncateTables($schema='')
{
    $tableNames=$this->getDbConnection()->getSchema()->getTableNames($schema);
    foreach($tableNames as $tableName)
        $this->truncateTable($tableName);
}

Truncates all tables in the specified schema. You may need to call checkIntegrity to turn off integrity check temporarily before you call this method.

CDbFixtureManager

Public Properties

Public Methods

Property Details

Method Details

See Also