Skip to main content
Version: v2

Generated Content

Generated Content fills a site with placeholder content from code, so a rebuilt environment comes back with pages, terms, and files already in place. You write a plugin per bundle, and the module runs the plugins in order when it's installed with GENERATED_CONTENT_CREATE=1, or whenever you ask it to. Plugins built on its static helpers produce identical output on every run, which is what visual regression tests and consistent demo sites need.

This page is for developers on a project built from Vortex who need demo or test content. It shows how to write a generator plugin, which helpers keep its output stable, and the ways to run generation. The module documentation is the reference for its full API.

Plugin system​

Each generator is a PHP class in a module's src/Plugin/GeneratedContent/ directory, marked with the #[GeneratedContent] attribute and extending GeneratedContentPluginBase. Its generate() method creates the entities and returns them, so the module can track them for cleanup.

Creating a plugin​

The following plugin, a shorter version of the shipped Page plugin, creates 20 page nodes with static titles and body text:

namespace Drupal\ys_demo\Plugin\GeneratedContent\Node;

use Drupal\generated_content\Attribute\GeneratedContent;
use Drupal\generated_content\Plugin\GeneratedContent\GeneratedContentPluginBase;

#[GeneratedContent(
  id: 'ys_demo_node_page',
  entity_type: 'node',
  bundle: 'page',
  weight: 20,
)]
class Page extends GeneratedContentPluginBase {

  public function generate(): array {
    $entities = [];
    $storage = $this->entityTypeManager->getStorage('node');

    for ($i = 1; $i <= 20; $i++) {
      $node = $storage->create([
        'type' => 'page',
        'title' => sprintf('Demo page %s %s', $i, $this->helper::staticName()),
        'status' => 1,
      ]);

      $node->set('body', [
        'value' => $this->helper::staticRichText(3),
        'format' => 'full_html',
      ]);

      $node->save();

      $entities[] = $node;
    }

    return $entities;
  }

}
note

For a bundle under content moderation, also set the moderation_state field to published before saving. A new node otherwise takes the workflow's default moderation state, and a draft default leaves it unpublished whatever its status says. The shipped Page plugin shows the guarded check.

Attribute parameters​

The #[GeneratedContent] attribute takes the following parameters:

ParameterTypeRequiredDescription
idstringyesUnique plugin ID
entity_typestringyesTarget entity type, such as node or taxonomy_term
bundlestringyesTarget bundle
weightintnoExecution order, lowest first (default: 0)
trackingboolnoIf TRUE, tracks the created entities so the module can remove them later. If FALSE, doesn't track them (default: TRUE)
labelTranslatableMarkupnoHuman-readable name of the plugin
helperstringnoCustom helper class extending GeneratedContentHelper. For any other class, the plugin falls back to the default helper

Generation helpers​

$this->helper is a GeneratedContentHelper singleton, or the subclass named in the plugin's helper parameter. It produces field values, creates file assets, and looks up entities that earlier plugins created. The following examples show some of what it offers, and the module documentation lists the full set.

Static helpers return the same values on every run, which is what visual regression testing needs. They read a fixed list of text in order, so the output stays stable as long as the plugins make the same calls in the same order:

$this->helper::staticName();          // Fixed-length name.
$this->helper::staticSentence(5);     // Sentence of 5 words.
$this->helper::staticRichText(3);     // 3 paragraphs of HTML.

Random helpers vary on every run, which suits content that only needs to make the site look populated:

$this->helper::randomName();
$this->helper::randomSentence(5, 10); // Between 5 and 10 words.
$this->helper::randomEmail();
$this->helper::randomTimestamp('-1year', 'now');

Entity helpers reference content that earlier plugins produced. Use weight to make sure those plugins ran first, and pick the static variant when the reference itself must stay stable between runs:

// In a node plugin with weight: 20 (runs after terms at weight: 10).
$node->set('field_tags', $this->helper::randomTerms('tags', 3));
$node->set('field_author', $this->helper::staticUser());

Asset helpers create managed files from the dummy assets that ship with the module, covering image, document, audio, and video extensions:

$node->set('field_image', $this->helper::createFile('png'));
$node->set('field_attachment', $this->helper::createFile('pdf'));

Triggering generation​

Generation starts in 1 of 4 ways, each covered in the following sections.

Drush command​

To run the page plugin, pass the entity type, the bundle, and a count to the following command:

drush generated-content:create-content node page 20

The command needs all 3 arguments. It splits the count into batches of 50 and runs the bundle's plugin once per batch, so the plugin decides how many entities each run creates. With 20, the Page plugin runs once and creates its 20 pages. Confirm that the new pages appear in the content list at /admin/content.

The command runs only the plugin for that entity type and bundle. It doesn't run plugins with a lower weight first, so a plugin that references other generated content finds only what already exists.

Admin UI​

To generate content from the administration interface, go to /admin/config/development/generated-content. The page lists every plugin with its weight, its tracking setting, and the number of entities it created. Select the plugins to process, then click Generate, Delete, or Regenerate.

Environment variable​

With GENERATED_CONTENT_CREATE=1 set, installing generated_content or a module that provides plugins generates the content. It only runs while no generated content exists yet, so installing another module later doesn't duplicate the content. GENERATED_CONTENT_ITEMS limits generation to a comma-separated list of entity_type-bundle pairs:

GENERATED_CONTENT_ITEMS="taxonomy_term-tags,node-page"

Provisioning​

Vortex installs the module from the EnableDevelopmentModulesDeployStep deploy step in every environment except production. The step sets GENERATED_CONTENT_CREATE=1 for that install, so the content arrives with the module. Set DRUPAL_GENERATED_CONTENT_SKIP to 1 to install the module without the content.

The step installs the module after the modules that supply generator plugins, such as ys_demo. Provisioning again doesn't duplicate the content, because the install skips a module that's already enabled.

➡️ See Provision

Example in Vortex​

The ys_demo module ships a single generated content plugin, Page: it creates 20 page nodes whose titles and body text come from the static helpers, so the same pages appear on every rebuild. The nodes back the demo /pages view used by the Testmode example.