sfEnvironmentFixturesPlugin
The sfEnvironmentFixturesPlugin is a symfony plugin that provides support
for defining additional fixtures for each symfony environment.
The plugin does so in such a way that any symfony task which internally uses
the data-load task will function in the same way.
This plugin works with either Doctrine or Propel.
Installation
Install the plugin (via a package):
$ symfony plugin:install sfEnvironmentFixturesPlugin
Install the plugin (via a Subversion checkout):
$ svn co http://svn.symfony-project.com/plugins/sfEnvironmentFixturesPlugin/branches/1.0 plugins/sfEnvironmentFixturesPlugin
Enable the plugin in config/ProjectConfiguration.class.php:
class ProjectConfiguration extends sfProjectConfiguration
{
public function setup()
{
$this->enablePlugins(array(
'sfEnvironmentFixturesPlugin',
));
}
}
Usage
The plugin will search the data directory (usually data)
for a sub-directory that follows the naming convention:
fixtures_<environment name>
For example, when running in the dev environment, fixtures will be
loaded from data/fixtures_dev.
Simply place the fixture files in the corresponding directories and they
will be loaded any time the data-load task is invoked.
You should see output similar to the following:
>> doctrine Including data fixtures from "/path/to/project/data/fixtures"
>> fixtures Including data fixtures for environment "dev"
>> fixtures Including data fixtures from "/path/to/project/data/fixtures_dev"
>> doctrine Data was successfully loaded
You may see some messages repeated depending on the task being run.
Basic example
Consider the following file structure:
/path/to/project
...
/data
/fixtures
fixtures.yml
/fixtures_dev
fixtures.yml
...
With the main fixtures file containing:
# /path/to/project/data/fixtures/fixtures.yml
Fruit:
fruit_apple:
name: apple
fruit_banana:
name: banana
And the dev fixtures file containing:
# /path/to/project/data/fixtures_dev/fixtures.yml
Fruit:
fruit_orange:
name: orange
fruit_peach:
name: peach
Running the data-load task and specifying the dev environment
(using --env=dev) would give us the following data set:
+----+--------+
| id | name |
+----+--------+
| 1 | apple |
| 2 | banana |
| 3 | orange |
| 4 | peach |
+----+--------+
In this case fixtures are first loaded from the standard symfony directory,
followed by the fixtures directory for the dev environment.
If we were to specify the prod environment by using --env=prod we would
end up with a different set of data:
+----+--------+
| id | name |
+----+--------+
| 1 | apple |
| 2 | banana |
+----+--------+
In this case the dev fixtures are ignored and only the fixtures from the
standard symfony directory are loaded. However, if we had a fixtures_prod
directory, it's contents would also be loaded.
Running the data-load task without specifying an environment would give us
the following data set:
+----+--------+
| id | name |
+----+--------+
| 1 | apple |
| 2 | banana |
| 3 | orange |
| 4 | peach |
+----+--------+
This is because the default environment for tasks is dev.
Example with relationships
Now consider a more complex file structure:
/path/to/project
...
/data
/fixtures
/fruit
categories.yml
fruits.yml
/fixtures_dev
/fruit
fruits.yml
/fixtures_prod
/fruit
fruits.yml
...
With the main fixture files containing:
# /path/to/project/data/fixtures/fruit/categories.yml
Category:
category_citrus:
name: citrus
category_stone_fruit:
name: stone fruit
And:
# /path/to/project/data/fixtures/fruit/fruits.yml
Fruit:
fruit_apple:
name: apple
fruit_banana:
name: banana
The dev fixtures file containing:
# /path/to/project/data/fixtures_dev/fruit/fruits.yml
Fruit:
fruit_orange:
name: orange
Category: category_citrus
And the prod fixtures file containing:
# /path/to/project/data/fixtures_prod/fruit/fruits.yml
Fruit:
fruit_peach:
name: peach
Category: category_stone_fruit
Running the data-load task and specifying the dev environment
(using --env=dev) would give us the following data set:
+----+--------+-------------+
| id | name | category_id |
+----+--------+-------------+
| 1 | apple | NULL |
| 2 | banana | NULL |
| 3 | orange | 1 |
+----+--------+-------------+
In this case fixtures are first loaded from the standard symfony directory,
followed by the fixtures directory for the dev environment.
As you can see, even though the categories are stored in a different fixtures
directory to the orange, it is still able to reference the citrus category
using the category_citrus record label.
If we were to specify the prod environment by using --env=prod we would
end up with a different set of data:
+----+--------+-------------+
| id | name | category_id |
+----+--------+-------------+
| 1 | apple | NULL |
| 2 | banana | NULL |
| 3 | peach | 2 |
+----+--------+-------------+
Showing that the fixtures for the prod environment have been loaded instead.
This example also shows that the plugin is capable of reading fixtures from
sub-directories, just like the main symfony fixtures directory.
Important points
The default environment for the data-load task is dev, so unless you
specify an environment with the --env option, fixtures in the
fixtures_dev directory will be loaded, which could be very bad in a
production environment.
Fixtures are always loaded from the main fixtures directory regardless
of the current environment.
Environment-specific fixtures can still reference record labels from the
main fixture file, making references easy to set up.
It's a good idea to keep record labels unique across all fixtures. This will
avoid any confusion when specifying relationships in your fixtures.
Fixtures are loaded in a recursive manner similar to the main fixtures
directory, meaning you can have fixtures in sub-directories if you so desire.
Fixtures can still contain PHP code.
Erin Millard 