Seeder by CartThrob (Seeder from here out) is a free ExpressionEngine focused data seeding tool. If you’re not familiar, a database seeding tool is one of the most aptly named tools in our universe; it seeds data into a database. Which solves so very many problems; they help with load testing, removes the dependence on client content for site structuring, and can really help push the limits on any UI.

Note that Seeder is a stand-alone tool; no other Add-on is required.

This being for ExpressionEngine means we’re Seeding Channel Entries and Members (out of the box). Basically, set up your Channel structure, execute a command, and, BOOM! you got data in your site.

But wait! There’s more.

Crap. I wrote that. Ugh… Sigh… It is true though. This well runs deep. Yeah, it Seeds Channel Entries and Members. But there’s also:

1. A complete API to create your own Seeds.
2. A Config based layer for defining the specific Seed data you want in your Seeds.
3. An API to implement third party ExpressionEngine FieldTypes into Seeder.

As I said. Deep.

So, in this series, I’m going to go over Seeder by CartThrob and provide examples and explanations on how to get things done.

First, like any program, we have to understand the rules of its universe.

How Seeder Works

It’s important to understand that Seeder will rarely (99.99%) relate to “real” data; it works in its own sandbox. For example, as we know, every Channel Entry requires a Member as an Author; Seeder will only use a Fake Member for these situations.

Which brings us to Dependencies.

Dependencies

Every Seed can define its own Dependencies; the items, and how many of them, the Seed requires to be created before it can be created. Again, using the Channel Entry Seed as an example, it requires 100 Fake Members be created before it’ll install a single Channel Entry to be used as Author relationships.

Data Tracking

Seeder keeps a record of every fake item created so it can be rolled back at any time and provide a pool of relatable data points. This becomes extremely important when creating your own Seeds (more on this in a later post).

Execution

There are 2 points of execution with Seeder: ExpressionEngine Actions and the new Command Line Interface (released with ExpressionEngine 6.1). There aren’t any template tags; it’s a utility so is executed like one. For example purposes, I’ll be sticking to the Command Line Interface.

./ee/eecli.php cartthrob:seeder:seed
./ee/eecli.php cartthrob:seeder:cleanup
./ee/eecli.php cartthrob:seeder:purge

Seed Data

To Seed data, you execute a command like so:

./ee/eecli.php cartthrob:seeder:seed --type SEED_TYPE --limit TOTAL_TO_SEED --verbose

The above would create XX Seeds and show you the progress of it doing so. Depending on the Seed though, you may be required to add additional parameters.

Parameters

Seed Members

Seeding Members into your site will require you also provide a role that is the shortname for the Member Role you want to assign these Fake members to.

./ee/eecli.php cartthrob:seeder:seed --type member --limit 10 --role members --verbose

Seeder will inspect your Member configuration, determine which Member Field Type you are using, and apply content to those fields.

Supported First Party Fields

Member Fields aren’t exactly extensible (*glares at Packet Tide) so the below is the complete coverage of Member Fields and how Seeder handles them.

Seed Channel Entries

When Seeding Channel Entries, you’ll be required to provide which Channel you want to assign your Entries to.

Note that the Entry Seed type requires there be 100 Member Seeds created prior to creation. It’s good practice to provide a role option just in case.

./ee/eecli.php cartthrob:seeder:seed --type entry --channel blogs --role authors

Just like with Member Seeds, Seeder inspects your Channel Entry configuration and applies Fake data based on the Field(s) used.

Supported First Party Fields

The below is which FieldTypes are specifically are supported by Seeder. You’ll likely note a couple missing (Grid and Fluid) but they’re in the works no doubt.

In a future post, I’ll go into detail on how Third Party developers can configure their Add-ons to work with Seeder. For now though, there ya go. A list. Of things.

Cleanup Seed Data

If you want to manage your Seeds at a granular level, you can use the cleanup command to get rid of specific Seeds. Note that due to how ExpressionEngine relates data at the Model level which means if you remove an asset that “owns” another data point, it’ll cascade accordingly.

./ee/eecli.php cartthrob:seeder:cleanup --type  SEED_TYPE --limit TOTAL_TO_SEED

Parameters

Remove All Seed Data

If you want to set your system back to a usable state, the purge Command is where it’s at. Every Seed. Gone. Like it never ever happened.

./ee/eecli.php cartthrob:seeder:purge --verbose

Parameters

Configuration Overrides

All that’s pretty great, right? You can create Seed data and remove Seed data. Good stuff. Something’s missing though; data has structure and context. Your Blog post doesn’t need 5 paragraphs in the blurb field. Your Titles might follow a specific format. You want to ensure a specific format for XXX instead of YYY.

Seeder has your back on that front with Configuration Overrides.

General Config Format

The format’s fairly straightforward (relying on ExpressionEngine’s structure) and boils down to an array full of closures using the Faker PHP library.

Config Location

Like all ExpressionEngine config files, it should be stored at system/user/config though this HAS to be named seeder.php. For Seed override, you use the index seeds as your parent array.

Config Format

Seeder will pass the Faker PHP Library to your closure which will allow you to generate any type of Fake data you require.

$config = [
    'seeds' => [
        'SEED_NAME' => [
            'DATA_POINT_OF_EMAIL' => function(Faker $faker) {
                return $faker->email();
            },
        ],
        'OTHER_SEED_NAME' => [
            'DATA_POST_OF_NAME' => function(Faker $faker) {
                return $faker->firstName();
            }       
        ]
    ]
]

Entry Config Override

To override Channel Entry data, you’ll have to break it down by channel_name and then define your channel fields. It’s important to note that you’ll use the field name to denote data. For example:

<?php
use \Faker\Generator AS Faker;

$config = [
    'seeds' => [
        'entry' => [
            'CHANNEL_NAME' => [
                'title' => function(Faker $faker) {
                    return 'Order #'.$faker->randomNumber();
                },
                'order_customer_phone' => function(Faker $faker) {
                    return $faker->phoneNumber();
                },
                'order_customer_email' => function(Faker $faker) {
                    return $faker->email();
                },
                'order_billing_first_name' => function(Faker $faker) {
                    return $faker->firstName();
                },
                'order_billing_last_name' => function(Faker $faker) {
                    return $faker->lastName();
                }
            ]
        ],
    ],
];

Member Config Override

Just like with Channel Entry configuration, to Seed Member data per field, you use the input name.

<?php
use \Faker\Generator AS Faker;

$config = [
    'seeds' => [
        'member' => [
            'first_name' => function(Faker $faker) {
                return $faker->firstName;
            },
            'last_name' => function(Faker $faker) {
                return $faker->lastName;
            },
            'join_date' => function(Faker $faker) {
                return $faker->dateTimeThisYear->format('U');
            }
        ],
    ],
];

Next Steps

And that’s Seeder. About half of it. As mentioned at the top, Seeder also has a complete API for extending and personalizing the experience. In the next piece, we’ll go over creating Seeds and updating FieldTypes to work with Seeder.

Eric Lamb

Builds things. Actively looking for clients.