Skip to content

Seeders ​

A seeder is a class that writes the sample content of a site: posts, pages, photographs, menus and the options a site needs to show them. wp foehn seed runs the seeders, so a developer or a coding agent can build the site again from an empty database.

Sample content goes in a seeder, never only in the database. Content created with one-off wp post create, wp menu or wp option update commands is lost when the database is emptied or replaced by another dump.

Create a seeder ​

bash
wp foehn make:seeder events --description="Sample events" --dry-run --format=json
wp foehn make:seeder events --description="Sample events"
wp foehn discovery:clear

The command writes app/Seeders/EventsSeeder.php. Its run() upserts one post with the slug events. Edit run() to write the content, for example:

php
<?php

declare(strict_types=1);

namespace App\Seeders;

use Studiometa\Foehn\Attributes\AsSeeder;
use Studiometa\Foehn\Contracts\SeederInterface;
use Studiometa\Foehn\Seeders\Upsert;

#[AsSeeder(order: 10, description: 'Sample events')]
final class EventsSeeder implements SeederInterface
{
    public function run(): void
    {
        Upsert::post('event', 'spring-fair', [
            'post_title' => 'Spring fair',
            'post_content' => '<p>Stalls, music and food in the main square.</p>',
        ], [
            'starts_at' => '2026-04-18',
        ]);
    }
}

A seeder has the #[AsSeeder] attribute and implements SeederInterface. A class with the attribute and without the interface is skipped. wp foehn inspect problems and wp foehn discovery:status report it, with the fix. A seeder registers nothing with WordPress: it runs only when wp foehn seed runs it.

ArgumentDefaultDescription
order10Run order. Lower runs first. Seeders with the same order run by class name.
description''What the seeder writes. wp foehn inspect and wp foehn seed show it.

Run the seeders ​

bash
wp foehn seed                       # every seeder, by order
wp foehn seed --class=EventsSeeder  # one seeder, by short or full class name
wp foehn seed --dry-run             # list the seeders, in order, and run nothing
wp foehn inspect seeders            # the seeders, with their order and description

In production, wp foehn seed runs only with --force or --dry-run: it writes content that visitors see. See Production Environment.

The command stops with exit status 1 at the first seeder that throws an exception, and prints the class and the message. Throw an exception when a seeder cannot do its work, for example when the page it needs does not exist.

When two seeders have the same short class name, --class refuses the short name and lists the full names.

Idempotency ​

A seeder must be idempotent: a second run updates the content of the first run and creates nothing. wp foehn seed can then run on any site, including a site that already has the content.

  • Find a post by type and slug before you create it. Upsert::post($type, $slug, $data, $meta) does this: it updates the post of this type that has this slug (in any status), or creates it with the publish status. It returns the post ID and throws a RuntimeException when WordPress refuses the post.
  • Find an attachment by a meta value that you write on it, such as an external ID, before you import the file again.
  • Find a menu by name, and write its items again: delete the old items, then add the new ones.
  • Write options with update_option(), which replaces the value.

Run wp foehn seed two times and count the posts after each run. The counts must not change.

Order ​

Use order when a seeder reads what another seeder writes. A seeder finds that content again, by slug or by meta, and does not receive it from the other seeder. So each seeder can also run alone with --class, on a site that has the content of the seeders before it.

The demo writes its whole portfolio with eight seeders in theme/app/Seeders/:

OrderSeederWrites
10MediaSeederThe photographs, found again by their Unsplash ID
20ProjectSeederThe projects, with the photographs of each as a gallery
25PressSeederPress quotes on two projects, in ACF fields
30PageSeederThe Home, About, Journal and Legal pages
35JournalSeederThree journal posts, one of them password-protected
40TestimonialSeederThe testimonials
50SettingsSeederSite title, front page, permalinks, timezone and theme settings
60MenuSeederThe header, footer and legal menus

The starter's menus ​

The starter theme ships App\Seeders\MenusSeeder (order 10). It creates the Header, Footer and Legal menus, each with a Home link, and assigns them to the header, footer and legal locations. It finds each menu by name and creates it only when it is missing, so a second run creates nothing and keeps the items that editors added.

bash
wp foehn seed --class=MenusSeeder

See Also ​

Føhn is released under the GPL-3.0-or-later license. The starter, the installer and the Vite plugin are MIT.