# Trait yii\test\FixtureTrait

Implemented by | yii\console\controllers\FixtureController, yii\faker\FixtureController
Available since version | 2.0
Source Code | https://github.com/yiisoft/yii2/blob/master/framework/test/FixtureTrait.php

FixtureTrait provides functionalities for loading, unloading and accessing fixtures for a test case.

By using FixtureTrait, a test class will be able to specify which fixtures to load by overriding the fixtures() method. It can then load and unload the fixtures using loadFixtures() and unloadFixtures(). Once a fixture is loaded, it can be accessed like an object property, thanks to the PHP `__get()` magic method. Also, if the fixture is an instance of yii\test\ActiveFixture, you will be able to access AR models through the syntax `$this->fixtureName('model name')`.

For more details and usage information on FixtureTrait, see the guide article on fixtures.

## Public Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
fixtures() | Declares the fixtures that are needed by the current test case. | yii\test\FixtureTrait
getFixture() | Returns the named fixture. | yii\test\FixtureTrait
getFixtures() | Returns the fixture objects as specified in globalFixtures() and fixtures(). | yii\test\FixtureTrait
globalFixtures() | Declares the fixtures shared required by different test cases. | yii\test\FixtureTrait
initFixtures() | Initialize the fixtures. | yii\test\FixtureTrait
loadFixtures() | Loads the specified fixtures. | yii\test\FixtureTrait
unloadFixtures() | Unloads the specified fixtures. | yii\test\FixtureTrait

## Protected Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
createFixtures() | Creates the specified fixture instances. | yii\test\FixtureTrait

## Method Details

Hide inherited methods

createFixtures() protected method

Creates the specified fixture instances.

All dependent fixtures will also be created. Duplicate fixtures and circular dependencies will only be created once.

protected yii\test\Fixture[] createFixtures ( array $fixtures )
$fixtures | array | The fixtures to be created. You may provide fixture names or fixture configurations. If this parameter is not provided, the fixtures specified in globalFixtures() and fixtures() will be created.
return | yii\test\Fixture[] | The created fixture instances
throws | yii\base\InvalidConfigException | if fixtures are not properly configured

Source code

                    protected function createFixtures(array $fixtures)
    {
        // normalize fixture configurations
        $config = [];  // configuration provided in test case
        $aliases = [];  // class name => alias or class name
        foreach ($fixtures as $name => $fixture) {
            if (!is_array($fixture)) {
                $class = ltrim($fixture, '\\');
                $fixtures[$name] = ['class' => $class];
                $aliases[$class] = is_int($name) ? $class : $name;
            } elseif (isset($fixture['class'])) {
                $class = ltrim($fixture['class'], '\\');
                $config[$class] = $fixture;
                $aliases[$class] = $name;
            } else {
                throw new InvalidConfigException("You must specify 'class' for the fixture '$name'.");
            }
        }
        // create fixture instances
        $instances = [];
        $stack = array_reverse($fixtures);
        while (($fixture = array_pop($stack)) !== null) {
            if ($fixture instanceof Fixture) {
                $class = get_class($fixture);
                $name = isset($aliases[$class]) ? $aliases[$class] : $class;
                unset($instances[$name]);  // unset so that the fixture is added to the last in the next line
                $instances[$name] = $fixture;
            } else {
                $class = ltrim($fixture['class'], '\\');
                $name = isset($aliases[$class]) ? $aliases[$class] : $class;
                if (!isset($instances[$name])) {
                    $instances[$name] = false;
                    $stack[] = $fixture = Yii::createObject($fixture);
                    foreach ($fixture->depends as $dep) {
                        // need to use the configuration provided in test case
                        $stack[] = isset($config[$dep]) ? $config[$dep] : ['class' => $dep];
                    }
                }
                // if the fixture is already loaded (ie. a circular dependency or if two fixtures depend on the same fixture) just skip it.
            }
        }
        return $instances;
    }

fixtures() public method

Declares the fixtures that are needed by the current test case.

The return value of this method must be an array of fixture configurations. For example,

    [
        // anonymous fixture
        PostFixture::class,
        // "users" fixture
        'users' => UserFixture::class,
        // "cache" fixture with configuration
        'cache' => [
             'class' => CacheFixture::class,
             'host' => 'xxx',
        ],
    ]

Note that the actual fixtures used for a test case will include both globalFixtures() and fixtures().

public array fixtures ( )
return | array | The fixtures needed by the current test case

Source code

                    public function fixtures()
    {
        return [];
    }

getFixture() public method

Returns the named fixture.

public yii\test\Fixture|null getFixture ( $name )
$name | string | The fixture name. This can be either the fixture alias name, or the class name if the alias is not used.
return | yii\test\Fixture|null | The fixture object, or null if the named fixture does not exist.

Source code

                    public function getFixture($name)
    {
        if ($this->_fixtures === null) {
            $this->_fixtures = $this->createFixtures(array_merge($this->globalFixtures(), $this->fixtures()));
        }
        $name = ltrim($name, '\\');
        return isset($this->_fixtures[$name]) ? $this->_fixtures[$name] : null;
    }

getFixtures() public method

Returns the fixture objects as specified in globalFixtures() and fixtures().

public yii\test\Fixture[] getFixtures ( )
return | yii\test\Fixture[] | The loaded fixtures for the current test case

Source code

                    public function getFixtures()
    {
        if ($this->_fixtures === null) {
            $this->_fixtures = $this->createFixtures(array_merge($this->globalFixtures(), $this->fixtures()));
        }
        return $this->_fixtures;
    }

globalFixtures() public method

Declares the fixtures shared required by different test cases.

The return value should be similar to that of fixtures(). You should usually override this method in a base class.

See also fixtures().

public array globalFixtures ( )
return | array | The fixtures shared and required by different test cases.

Source code

                    public function globalFixtures()
    {
        return [];
    }

initFixtures() public method (available since version 2.0.12)

Initialize the fixtures.

public void initFixtures ( )

Source code

                    public function initFixtures()
    {
        $this->unloadFixtures();
        $this->loadFixtures();
    }

loadFixtures() public method

Loads the specified fixtures.

This method will call yii\test\Fixture::load() for every fixture object.

public void loadFixtures ( $fixtures = null )
$fixtures | yii\test\Fixture[]|null | The fixtures to be loaded. If this parameter is not specified, the return value of getFixtures() will be used.

Source code

                    public function loadFixtures($fixtures = null)
    {
        if ($fixtures === null) {
            $fixtures = $this->getFixtures();
        }
        /* @var $fixture Fixture */
        foreach ($fixtures as $fixture) {
            $fixture->beforeLoad();
        }
        foreach ($fixtures as $fixture) {
            $fixture->load();
        }
        foreach (array_reverse($fixtures) as $fixture) {
            $fixture->afterLoad();
        }
    }

unloadFixtures() public method

Unloads the specified fixtures.

This method will call yii\test\Fixture::unload() for every fixture object.

public void unloadFixtures ( $fixtures = null )
$fixtures | yii\test\Fixture[]|null | The fixtures to be loaded. If this parameter is not specified, the return value of getFixtures() will be used.

Source code

                    public function unloadFixtures($fixtures = null)
    {
        if ($fixtures === null) {
            $fixtures = $this->getFixtures();
        }
        /* @var $fixture Fixture */
        foreach ($fixtures as $fixture) {
            $fixture->beforeUnload();
        }
        $fixtures = array_reverse($fixtures);
        foreach ($fixtures as $fixture) {
            $fixture->unload();
        }
        foreach ($fixtures as $fixture) {
            $fixture->afterUnload();
        }
    }