Seeder by CartThrob Version 1.2.0

Creating Seed Objects

Creating Seed objects for your ExpressionEngine add-on starts out with two steps:

A minor change to your addon.setup.php

You'll need to add a seeder key to the array that lays out each of your seeds like the below:

Example addon.setup.php

//gotta ensure Seed object is added to autoload ;)
if (defined('PATH_THIRD')) {
    require_once PATH_THIRD . 'custom_addon/vendor/autoload.php';
}

return [
    'author' => 'Custom Addon',
    'author_url' => 'https://yoururl.com',
    'docs_url' => 'https://www.yoururl.com/docs',
    'name' => CUSTOM_ADDON_NAME,
    'description' => 'Custom bucket container for mess around stuff',
    'version' => CUSTOM_ADDON_VERSION,
    'namespace' => 'Your\Namespace',
    'settings_exist' => false,
    'seeder' => [
        'seeds' => [
            'your/seed/name' => Your\Namespace\Seeds\YourSeed::class,
            'your/other/seed/name' => Your\Namespace\Seeds\YourOtherSeed::class,
        ]
    ],
];

The above addon.setup.php config would be executed using the below:

php ./system/eecli.php cartthrob:seeder:seed --type your/seed/name

The Seed object

The Seed object is pretty straight forward. Define a couple properties, the name and any dependencies, write your generate and delete method, and you're done.

NOTE: Your Seed should create ONE item per call to generate and remove one item per call to delete.

The generate Method

This is where the creation happens. You'll want to create exactly ONE item, set the pk property with its database Primary Key, and return the instance. Like the below:

public function generate(): AbstractSeed
{
    $id = my_magic_create_method_that_returns_an_id();
    $this->pk = $id;
    return $this;
}

That's all that's strictly required for a Seed object's generate method.

Dependencies

Whenever possible, CartThrob Seeder will attempt to always use previously Seeded data when relating data. For example, Seeded Entries will use Seeded Members for their properties. This ensures there's no cross contamination with existing data when using Seeded data alongside.

You define your dependencies as a property on your Seed. These will ALWAYS be called before your Seed is ran to ensure data's available at runtime.

/**
 * A simple settings map for how dependencies are handled
 *  The primary key should map to a Seed object (entry, member, etc)
 *  with the secondary array settings the minimum
 * @var array
 */
protected $dependencies = [
    'member' => [
        'min' => 100,
    ],
];

The above will ensure there are 100 Seeded Members available before your Seed is ran.

Accepting Input

If your Seed requires specific datapoints from user input, either Action GET params and/or Command Line options, you can define those in your Seed which Seeder will pass along to your Seed upon execution.

You define your expected Input through the input_params property. This is a multi-dimensional array which contains the description (used in Command Line Help), the default value, and the expected name for the input.

/**
 * The configured input expectations
 * @var array[]
 */
protected $input_params = [
    'custom_input' => [
        'desc' => 'my custom explanation',
        'default' => '22'
    ],
    'second_input' => [
        'desc' => 'another description here',
        'default' => 600
    ]
];

Within your Seed, you'll access the Input using the options($key) method.

$input = $this->option('custom_input', 'default_value');

To set your Input value depends on which method of access you're using. For Command Line, you'll set the Input using a namespace of addonname:inputvalue with every dash, underscore, or slash, converted to a colon :.

--your:seed:name:custom_input 20

And on Actions you just use the stand value.

/?ACT=XX&custom_input=20

Config Overrides

You can allow for user defined override of your Seed data by making a couple changes additional changes to your Seed within the generate method:

//before passing your data to your Model/Db Write object, add the below lines:
$data = []; //your custom data
foreach ($data as $key => $value) {
    if ($this->getConfig()->has($key) && $this->getConfig()->isCallable($key)) {
        $data[$key] = $this->getConfig()->call($key, false, $this->faker());
    }
}

Seed Prototype

<?php

namespace Your\Namespace\Seeds;

use CartThrob\Seeder\Core\AbstractSeed;

class YourSeed extends AbstractSeed
{
    /**
     * The short name you used in your addon.setup.php
     * @var string 
     */
    protected $type = 'your/seed/name';

    /**
     * Does your Seed require other Seed data? 
     * @var []
     */
    protected $dependencies = [];

    /**
     * The configured input expectations
     * @var []
     */
    protected $input_params = [];

    /**
     * Should create a single Seed record
     * @return AbstractSeed
     */
    protected function generate(): AbstractSeed
    {
        return $this;
    }

    /**
     * Should remove the specific Seed record
     * @param $id
     * @return mixed|void
     */
    protected function delete($id)
    {

    }
}