README

Your content schema, explained where you build it.

Every Craft 5 field layout lets you put a tip under each field — a note that sits in the entry form, shows a lightbulb in the field layout designer, and is stored in project config with the rest of the layout. Almost nobody writes them, because one note per field per layout is a job nobody has time for, and they go stale the day a setting changes.

Xplain writes them for you. For every field in every layout it says what the field stores, gives the Twig that reads it in that layout — block. inside a Matrix, category. on a category group, the renamed handle if the layout renamed it — and adds the one thing worth knowing: eager-load this, compare the value not the label, zero is falsy. When the schema changes, the tips change with it.

Hero image *
[ image ]
💡 Images relation — one image from `images`. {% set image = entry.landingHero.one() %}
   then {{ image.url }}. Listing many entries? Eager-load it: .with(['landingHero']) …

Free. Craft 5.3+, PHP 8.2+. No database tables, no outbound requests, no runtime dependencies.

Why Craft's own tips

• They live in project config. Tips version with the schema, show up in pull requests, and deploy with project-config/apply. Nothing to migrate, nothing to sync.
• They are where people look. Under the field in the entry form, and as a lightbulb in the field layout designer.
• They outlive the plugin. Uninstall Xplain and it takes its own tips with it — or keep them: they are ordinary Craft tips.

What it does

• Writes a tip for every field in every layout — entry types, Matrix entry types, category and tag groups, volumes, global sets, users, addresses, Content Block fields, Commerce product and variant types, and any plugin's layouts. It finds them all by walking project config, so there is no list of owners to fall behind.
• Keeps them current. Save a field or a layout and a queued job rewrites whatever changed — including the Matrix field whose note lists the entry type you just edited. Existing fields get their tips on install.
• Never touches your tips. Xplain records a hash of every tip it writes. A tip is Xplain's only while its text is exactly what Xplain wrote; edit one word and it is yours, and Xplain leaves it alone from then on.
• Keeps developer notes away from authors. Xplain's tips show to admins and to users with the See Xplain's developer tips permission. Hand-written tips still show to everyone — they are the author-facing notes the property was made for.
• Explains each field in full under its own settings screen: every layout it is in, the Twig for each, the whole {% switch %} for a Matrix field with every entry type's real field handles, an element query, a GraphQL selection, and every tip.
• Exports the schema as one Markdown document — for a repo's docs folder, a handover, or a review.
• Checks in CI. php craft xplain/tips/check exits non-zero when a tip is missing or stale.

Field types

Plain Text, Email, URL, Link, Number, Range, Money, Lightswitch, Date, Time, Color, Country, Icon, JSON, Dropdown, Radio Buttons, Button Group, Checkboxes, Multi-select, Table, Addresses, Entries, Assets, Categories, Tags, Users, Matrix, Content Block, CKEditor and Redactor — and a fallback that reads the value type Craft itself declares for anything else. Plugins can describe their own field types with one event.

Install

composer require justinholtweb/craft-xplain
php craft plugin/install xplain

Tips are written by a queued job straight away. Or, to see them first:

php craft xplain/tips/write --dry-run
php craft xplain/tips/write

Commit the project config changes like any other schema change.

Console

php craft xplain/tips                 # where every tip stands
php craft xplain/tips/write           # write missing and out-of-date tips (--dry-run, --field=a,b)
php craft xplain/tips/clear           # remove Xplain's tips — never hand-written ones
php craft xplain/tips/check           # exit 1 if any tip is missing or stale
php craft xplain/explain heroImage    # one field, in full
php craft xplain/explain/schema --output=docs/schema.md

Documentation

https://justinholt.com/plugins/craft-xplain/docs

License

The Craft License. See LICENSE.md. Xplain is free: no editions, no licence key, and no licensing code in the plugin.