sfFilesystemFixturesPlugin
==========================

The `sfFilesystemFixturesPlugin` is a symfony plugin that provides support for
defining sets of data files with which to populate the directory structure of
a symfony project. The plugin works in much the same way as the symfony
database fixtures system does, but in relation to files rather than database
records.

This plugin works with either Doctrine or Propel.

Installation
------------

* Install the plugin (via a package):

        $ symfony plugin:install -s alpha sfFilesystemFixturesPlugin

* Install the plugin (via a Subversion checkout):

        $ svn co http://svn.symfony-project.com/plugins/sfFilesystemFixturesPlugin/branches/0.1 plugins/sfFilesystemFixturesPlugin
        
* Enable the plugin in `config/ProjectConfiguration.class.php`:

        class ProjectConfiguration extends sfProjectConfiguration
        {
          public function setup()
          {
            $this->enablePlugins(array(
              'sfFilesystemFixturesPlugin',
            ));
          }
        }

Usage
-----

The plugin will search the data directory (usually `data`) for a sub-directory
called `fs_fixtures` and recursively copy the directories and files found
within it to your main symfony project directory. By default, files will not
be overwritten if they already exist.

In addition the plugin will search the data directory for a sub-directory that
follows the naming convention:

    fs_fixtures_<environment name>

If found, everything in this directory will be loaded also. For example, when
running in the `dev` environment, fixtures will be loaded from
`data/fs_fixtures_dev`.

The plugin treats these 'filesystem fixtures' as a part of the model layer of
the application, and by default will load them at the same time as normal
fixtures are loaded. 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:

    >> fs-fixtures  Including fs fixtures from "/path/to/project/data/fs_fixtures"
    >> fs-fixtures  Including fs fixtures from "/path/to/project/data/fs_fixtures_dev"

You may see some messages repeated depending on the task being run.

Tasks
-----

The plugin comes with 2 tasks:

    $ symfony
    ...
    fs-fixtures
      :clean                       Removes existing filesystem fixture data
      :load                        Loads filesystem fixture data
    ...

These tasks are fairly self explanatory, the `fs-fixtures:load` task loads
fixtures, and the `fs-fixtures:clean` task removes them.

Usage information for `fs-fixtures:load`

    symfony fs-fixtures:load [--overwrite] [--application[="..."]] [--env="..."]

    Options:
     --overwrite    Overwrite existing files
     --application  The application name
     --env          The environment (default: dev)

    Description:
     The fs-fixtures:load task loads filesystem fixture data:

       ./symfony fs-fixtures:load

     Fixtures will also be loaded from the environment-specific directory if present.
    
Usage information for `fs-fixtures:clean`

    symfony fs-fixtures:clean [--remove-dirs] [--no-confirmation] [--application[="..."]] [--env="..."]

    Options:
     --remove-dirs      Remove directories if empty
     --no-confirmation  Do not prompt for confirmation
     --application      The application name
     --env              The environment (default: dev)

    Description:
     The fs-fixtures:clean task removes existing filesystem fixture data:

       ./symfony fs-fixtures:clean

     Fixtures from the environment-specific directory will also be removed if present.

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
`fs_fixtures_dev` directory will be loaded, which could be very bad in a
production environment.

* Fixtures are *always* loaded from the main `fs_fixtures` directory
regardless of the current environment.