How-to guides

Short, task-oriented recipes: each one solves a single problem, assumes you already know the basics, and gives you a complete example you can run and adapt. If you're starting from zero, read the PGDL guide first (see What is PGDL? and Expressions (PEL)).

Every example on these pages is a real phony invocation and its actual output.

The recipes

• Generate N items per parent — tags on a user, line-items on an order, any JSON array, with the repeat step.
• Make fields agree with each other — an email that matches the name, a total that matches its price and tax, a city/district/postal that never mismatch.
• Weight choices and branch on values — weighted picks, weighted variants, and if/switch computed fields.
• Serve locale-specific data — one definition, different data under tr_TR vs en_US, and how resolution falls back.
• Write and use a package — the phony.json shape, loading a local package, and the git-based install flow.
• Migrate from Faker — a mechanical Faker-call → Phony mapping, written for a coding agent doing the port.

The shape of every recipe

Most recipes register a composition (a generator authored as data) in a phony.json package, then run it with phony generate:

phony generate --use <generator-name> --package ./my-pkg --seed 42 -n 3

• --use NAME runs a registered generator by name.
• --package DIR loads a package directory (one containing phony.json), so its generators and assets are available.
• --seed makes the run reproducible — the same seed always yields the same rows.
• -n is how many values to produce; -f jsonl switches to one JSON value per line.

phony prints a ✓ Loaded … line to stderr for each package it loads, so the JSON on stdout stays clean and pipeable.