Demo data
The admin page Tools / Demo data (?object=manage_demo) fills the modules of a site that are empty, or have no table yet, with
demo content: news, static pages, FAQ, tips, comments, users, shop categories, products and orders, and payment accounts. It is made for a demo
website and for trying a new part of an existing site (a shop that has no products yet) without touching its real content. Every demo row is
listed in a ledger, so a batch can be removed again exactly. The demo db/demo_data (Demos) shows the rows the generator makes.
Turning it on
Nothing can be seeded until one of two settings is on (admin Settings, tab Docs & demo site; both are for super-admins and need a typed confirmation):
main.DEMO_WEBSITE: the site is a demo website (the public docs / demo site).main()->is_demo_website()main.DEMO_DATA_SEED_ALLOWED: demo data may be seeded on this site, for a staging copy or a new part of a site.main()->is_demo_seed_allowed()
$PROJECT_CONF['main']['DEMO_DATA_SEED_ALLOWED'] = true; // turn it off again when the demo rows are in place or removed
With both off the page only shows how to turn it on and the batches seeded before, which can still be removed. The site doctor shows a notice while the switch is on, and while demo rows are left on a site that is not a demo website.
Seeding
- Sources. The page lists each source with its rows and how many of them are demo rows, and its state: empty (no rows),
table missing, demo rows only, few rows (fewer real rows than the volume), has content, or not possible (for
example no
shop_catscategory set). Empty and missing sources are ticked; sample shows rows it would write. - Volume. 10, 100, 1000 or 10000 main rows per source, scaled per source (two comments per news item, one order per two products, at most 30 shop categories). Each count can be changed. The console also takes 100000.
- Preview. Shows the units per source, the sources added because another one needs them (comments need news, orders need products), the tables a missing source would create (while "create missing tables" is ticked) and a sample row of each source. Nothing is written yet.
- Approve. Each source has its own tick; a source that already has content is never ticked for you. A batch of more than 1000 units, or
one that adds to a source with content, asks for the typed word
SEED. The module switches of the seeded parts that are off (the user module that shows them on the site, the admin module) can be turned on here as well. - Progress. A batch is written in transactions of 100 units, about four seconds a request; the batch page continues by itself and shows the progress. Bigger volumes are quicker from the console.
What demo rows look like
- Plain text from fixed word, name and city lists in English, Ukrainian, German or Latin lorem ipsum, from a seeded generator: no markup,
quotes or braces, safe on any page. HTML columns (news text, page text, FAQ answers, product descriptions) get the same text inside a fixed
<p>template. - URL keys and page names start with
demo-b<batch>-, product codes withDEMO-: a real page name is never taken. - Users are inactive (they cannot log in) with a random password nobody knows, hashed like any other, and an address of
example.invalid; phone numbers are in the 555-01xx block, IP addresses in 192.0.2.0/24. They go to the user groupyf_demo_seed_sources::$USER_GROUP(2, "Member"), which must be an active group other than the guests. - Comments, orders and payment accounts only belong to demo news, products and users: demo rows never appear under real content.
Removing
Remove on a batch shows what will happen first: the rows of each table, the rows edited since they were seeded, the rows other rows still use (a real comment on a demo news item, a real order of a demo product) and the rows already gone. Only rows named in the batch's ledger are deleted, by their primary key, children before parents, and only for a source the code defines and a table that source writes: any other ledger row is left alone, stays in the ledger and is reported. A failed delete rolls its chunk back, ledger rows included.
- Edited rows. An edit is noticed through a hash of the columns the seed wrote that matter (titles, texts, URL keys, prices,
flags; listed per source in
yf_demo_seed_sources). A change only to other columns (a view counter, a last-login time) is not an edit. A row without a stored hash counts as edited. Edited rows stay; with "also remove the edited rows" an edited row goes only when itsadd_dateis not newer than its seeding, so a row the database later gave the same id is never removed; tables without that column (pages, tips, orders, link rows) keep their edited rows either way. - Used rows always stay.
- Rows that stay leave the ledger: from then on they are the site's own rows and no later removal touches them.
- Tables a batch created stay. Undo features turns the module switches of a batch back off.
Console
php .dev/console/yf.php demo:seed # sources and their state, the recommended plan
php .dev/console/yf.php demo:seed --volume=1000 --dry-run # plan and a sample row per source
php .dev/console/yf.php demo:seed --sources=news,comments --volume=100 --locale=uk --yes
php .dev/console/yf.php demo:seed --count=shop_products:500 --features --yes
php .dev/console/yf.php demo:seed --list
php .dev/console/yf.php demo:seed --remove=3 --yes # --edited also removes the edited rows
The console needs the same setting; every write needs --yes.
Safety
- Super-admins (group 1) only, whatever the block rules say; every change is a POST with the session token.
- Every seed, removal and switch change goes to the admin wall and the log.
- Tables without transactions (MyISAM, Aria, MEMORY) are never seeded: a chunk and its ledger rows must roll back together. Convert them to InnoDB first.
- "Turn features on" never flips the modules of
yf_demo_seed::$FEATURE_DENY(login, registration, accounts, admin tools); a user module is marked "public site pages", because once it is on every visitor sees its pages. - Generators only use demo parents whose row still has its seeded hash: a demo order or payment account never goes to a real user.
- The "Seed demo data" link of an empty admin list shows only for an empty table, not for a filter that matched nothing.
- The ledger tables are
sys_demo_seed(one row per demo row: batch, source, table, key, hash of the seeded values) andsys_demo_seed_batches.
More sources
A site adds a source with _class('demo_seed')->register('name', $definition, $provider): the definition names its tables, key
columns, the columns that tell an edited row, the rows that use it and its ratio; $provider->rows_name($g, $n, $ctx) returns the rows
of unit $n, built with the text generator $g (yf_demo_seed_text). The built-in sources in
yf_demo_seed_sources are the examples.