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 todelete
.
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)
{
}
}