Seed Data

The concept of "database seeding" is part of data migrations, something first used (?) by Ruby on Rails, and it is being used by other frameworks such as Laravel. It is a powerful and useful way for you to package data with your MODX extra.

MODX stores Elements (Templates, Snippets, and Plugins) as regular files inside your repository, but all other objects are treated as "seed data". Seed files are files (so they can still be edited and version-controlled), but they return arrays of data representing MODX object attributes.

composer.json

If you are going to use seed data in your project, you need to let Repoman know where to look for it. Define a node in your composer.json's "extra" node named "seeds_path":

    "extra": {
        "seeds_path": ["model/seeds/"]
    }

This is an array: you can define multiple sources of seed data. The values defined in the composer.json should reflect only the seed data that should be included in the production-ready package. When developing, you may need to augment or override the seeds with your own.

File Naming Convention

The syntax for naming your files containing seed data is this:

[ordering_prefix.]classname.[php|json]

For example, if you want to install a MODX page in your project, you would name your file modResource.php Each file may contain a single array representing one object, or it may contain an array of arrays representing a collection of objects.

Optionally, you can use an ordering prefix in your file names. This can help you keep your files organized and importantly, it can help enforce the order in which they are loaded (this is important in certain situations).

You can store seed data as JSON, but usually it is only used when you export existing data. JSON syntax errors are much harder to track down, so it is recommended to use PHP files for seed data.

Related Objects

Seed data can reference related objects, e.g. a modMenu object can contain a modAction object. xPDO handles the heavy lifting here of ensuring that the objects are properly linked in the database. This means you can easily load relational data without having to worry about hard-coding foreign key relations between your objects.

Repoman's graph function can help you see what object attributes are available to any given classname, and it also identifies all possible related objects.

php repoman graph modResource

See Sample Objects for examples of how to format various objects.

Using Test Data

Repoman lets you define multiple directories for seed data. This is useful if you want to keep one set of data on hand for production use and another set of data on hand for testing your extra.

The expected use-case is this: your composer.json file defines the seed data that is necessary for your package to function. This includes all the objects that you want included when your package is installed in a production environment. Your test data can be stored inside your repository (optionally, you can omit it from being packaged by defining files and/or directories in the "omit" node), and you can instruct Repoman to load up your test data via the command-line "--seeds_path" option:

php repoman seed /path/to/mypkg/ --seeds_path=model/seeds/dev