Seeding

As most XELOS functions are dependent on the database and a certain set of configuration and data settings, we need to make sure to create a static setting before running the specific tests. This can be done by using Seeds. The framework as well as modules may provide a set of seeds in their configuration which can be loaded before test execution. In future releases seeding will also be supported during the creation of new module instances to provide users a basic instance configuration.

Seeds are located in the setup/seeds/[seed_name]/[seed_script].php of the system or the module, where [seedname] is the name of the specific seed (e.g. base) and [seed_script] is the specific script to load the required data. Each seed can consist of multiple scripts which will all be called during the seeding. For best readability we recommend using one script per model / table, e.g. user.php to fill the user model and policy.php to fill create the policy models.

Note

Please use one seed script per model. Do not modify or add data outside of your specific instance.

Helper for Writing Seeds

XELOS provides helper classes to facilitate the seeding process.

CSV Import

The CSV Import helper can be used to create models based on simple CSV files. The helper loads the CSV, loops through the rows and creates a new model per row. All columns are being set as property. Before and after callbacks give additional flexibility to call custom model functions or to perform manual property transformations. Finally, each model is being saved causing all of the model's implemented validations and submodel generations to be processed accordingly.

A simple CSV based seed could look as follows:

CSV File: /setup/seeds/base/data/user.csv

firstname;lastname;email
Daniel;Wilhelm;daniel@xelos.net
Stefan;Pasel;stefan@xelos.net

Seed Script: /setup/seeds/base/user.php

<?php
use XELOS\Framework\Lib\Installer\Seed\CsvImport;

// Initialize System Groups
// $seed_instance is automatically passed to the script from the seeding logic.
// It contains the specific instance object.

$seed = new CsvImport($seed_instance, 'user');
$seed->set_source(dirname(__FILE__).'/data/user.csv');
$seed->import();

Fake Import

The Fake Import class provides a wrapper to the Faker helper which can be used to generate automated test data. This is especially useful for example and / or load testing seed data.

Manual

You can also use manual database functions or other methods during the seeding process. E.g. using the auto_query function:

<?php
$XF->db->auto_query('insert', 'my_table', array(
    'firstname'=>'John',
    'lastname'=>'Wayne',
    'age'=>18
));

Run Seed

Seed Configuration

While the Seeds define the DATA for each module which can be used to prefill an instance of it, the seed configurations glues these "pieces" together in typical XELOS installation. As each installation consists of multiple instances of modules the configuration describes which modules should be installed and with which seed. It can therefore be seen as a template for setting up a predefined XELOS environment. Seed configurations are located in the system's /setup/seed/ folder as .yml file.

They currently support: * Create new instances * Seed with data * Set configuration parameters * Configure dependencies * Create the navigation * Include other seed configurations for inheritance

Example performance.yml

# Performance Seed Configuration
config:
  include: base
  default_seeds:
    - performance
  instances:
    dms:
      module: dms
      title: "Performance DMS"
    groups:
      module: groups
      title: "Projects"
      dependencies:
        comments:
          module: comments
          seed_per_group: true
        dms:
          module: dms
          seed_per_group: true

A configuration file gives the system setup instructions on which instances it whould install and with which settings and seeds.

Run Full Seeding

A full seeding is being done by executing a Seed Configuration file. This causes ALL DATA of the currently configured System to be DELETED.

To initialize the system with the base seed configuration (as described in the base.yml):

php xf seed:init base 

Run Single Instance Seeding

In some cases or for speeding up the writing of seeds you may just want to run the seeding process for a single instance. In this case your system should already have an existing instance which shall be seeded. In this case you can use the following command to truncate all tables of the instance and execute a certain seed (e.g. base) for the passed instance (e.g. my_dms_instance):

php xf seed:instance my_dms_instance base