Configuration
Settings live at Yarn → Settings, and can be overridden per environment with
config/yarn.php.
<?php
return [
'sources' => ['refTags', 'urls'],
'rollUpNested' => true,
'cacheDuration' => 900,
'maxNodes' => 600,
'orphanKinds' => ['entry', 'asset'],
'excludedGroups' => ['type:craft\\elements\\Address'],
];
What counts as a relation
sources — extra relation sources
Craft’s relation fields are always read. These are the optional ones:
| Value | What it adds | Cost |
|---|---|---|
refTags | {entry:42:url} and friends, anywhere in a field value | Reads every field value on the site |
structure | Parent-to-child edges in structure sections and category groups | One query |
urls | href and src values, and values that are nothing but a URL, that resolve to an element | Shares the refTags scan |
refTags is on by default. structure and urls are not: a hierarchy is not a dependency, and
the link scanner produces the most false positives of anything here.
refTags and urls share a single pass over the content, so switching the second one on costs
almost nothing once the first is on.
rollUpNested
On by default. A relation held inside a Matrix block, or inside an entry embedded in CKEditor, is reported as belonging to the page that owns it.
This is almost always what you want: it is the page you would open, and the page that breaks. Turn it off and every block becomes a node of its own — honest, and on a Matrix-heavy site, unreadable.
includeDisabled
On by default. Disabled elements still appear, marked as disabled. Turn it off when the map is only meant to describe what is live.
ignoredFields
Relation fields to skip, by handle. The usual reason is a field that relates everything to everything — a “related posts” field filled by an automation — which adds thousands of edges and says nothing.
linkFields
Only matters with urls on. Besides href and src in markup, Yarn reads a value that is
nothing but a link — /media/downloads/policy.pdf typed into a Table cell, a Plain Text
“button URL” field, the URL half of a Link field — as a link to whatever page or asset it resolves
to. It has to be the whole value, one token, and either root-relative or absolute on one of the
site’s own hosts.
Empty (the default), every field is read that way. List field handles to read only those:
'linkFields' => ['buttons', 'ctaUrl'],
Worth doing when a Plain Text field elsewhere holds paths that aren’t links: a value that looks like a link and resolves to nothing is reported as a broken link. A Table field is in or out as a whole; its columns can’t be picked separately.
excludedGroups
Sections, volumes, category and tag groups, users, globals, and element types from other plugins,
by key: section:3, volume:1, categoryGroup:2, tagGroup:4, users, globals,
type:craft\elements\Address.
The last shape is worth knowing about. Craft’s addresses are elements, there can be tens of thousands of them, and none of them relate to anything.
Performance
cacheDuration
Seconds an assembled graph is reused. Default 300.
The cache is also thrown away whenever any element is saved, deleted or restored, so this is a
ceiling on how long a quiet site goes without a rebuild rather than a staleness window. 0
rebuilds on every request.
A graph that serialises to more than 4 MB is not cached at all, and Yarn writes a line to
storage/logs/yarn.log saying so. Rebuilding a graph that big costs seconds; writing it to a
shared cache costs the whole site.
maxNodes
How many elements the map will draw at once. Default 400.
The layout is O(n²) per frame in the browser. Past a few hundred nodes the picture stops being
readable well before the browser stops coping, so the map keeps the busiest maxNodes and says
that it has.
scanBatchSize
Rows read at a time when scanning content. Default 500. Lower it on a site with very large rich-text fields and a small PHP memory limit.
Reporting
orphanKinds
Which kinds of element to report when nothing points at them. Default entries, assets and categories.
Users and tags are left out on purpose: a user nothing relates to is a normal user.
orphansIgnoreRoutable
Off by default. On, an element that has a URL of its own is not reported as an orphan — it is still reachable from search and from the sitemap.
Turn it on when the question is “what is unreachable”; leave it off when the question is “what is unused”.
cycleLimit
Stop after this many circular relations. Default 20; the twentieth tells you nothing new.
Elsewhere in the control panel
showElementPanel
On by default. Adds a Relations panel to the sidebar of every element edit screen, saying what points at this element before you delete it.
The panel never assembles the whole graph. It renders on every edit screen on the site, and a graph
build is not something to do on the way to an edit form. Relation fields come straight from the
relations table. Reference tags and hard-coded links (when those sources are on) come from a search
of only the content rows that could mention this element: its id, its UID, its filename, the end
of its URI. The same matcher the graph uses then checks those rows. The answer is cached until the
next element save. Links to the homepage are the exception: / has nothing distinctive to search
for, so the panel leaves those to the full picture, which is one click away.
navLabel and navIcon
What Yarn is called in the control panel's main navigation, and the icon beside it. Both are blank
by default, which keeps “Yarn” and its own icon. navIcon takes a Craft icon name
(diagram-project), picked with the icon picker on the settings screen.
deleteGuard and deleteGuardKinds
off (default) or log. On log, deleting an element that other elements point at writes what
was still using it to storage/logs/yarn.log.
It cannot stop the deletion, and does not pretend to. Craft has no cancellable hook that fires
before a field has already deleted the element’s nested content:
Elements::EVENT_BEFORE_DELETE_ELEMENT is not cancellable, and vetoing the one that is
(Element::EVENT_BEFORE_DELETE) keeps the element row and destroys its blocks. Prevention belongs
on the sidebar panel, while there is still time to reconsider; this setting is for afterwards,
when somebody asks why a page went blank last Thursday.
Findings digest
Once a day or once a week, Yarn can email what it has found since the last digest — a reference tag that now points at nothing, a live page relating to an entry somebody switched off — so content rot is noticed without anybody opening Yarn to look.
'digestEnabled' => true,
'digestFrequency' => 'weekly', // or 'daily'
'digestWeekday' => 1, // ISO: 1 = Monday … 7 = Sunday
'digestHour' => 8, // 0–23, system time zone
'digestRecipients' => '$YARN_DIGEST_RECIPIENTS',
'digestSendWhenEmpty' => false,
'digestSite' => '', // site handle; empty for the primary site
'digestChecks' => ['brokenTargets', 'absentTargets', 'disabledTargets', 'unresolvedReferences', 'cycles', 'selfReferences'],
'digestWebTrigger' => true,
digestEnabled, digestFrequency, digestWeekday, digestHour
Off by default. The digest becomes due at the given hour (in the system time zone, Settings →
General) on the given day — every day for daily — and is sent by the first run at or after
that moment, once per day or ISO week. A site whose cron missed the hour still sends later in
the same period; it never sends twice.
digestRecipients
Email addresses separated by commas or new lines, or an environment variable holding them. Each recipient gets their own message, so nobody on the list learns who else is on it. Never required: an empty list just means nothing is sent.
digestSendWhenEmpty
Off by default: a period with nothing new sends nothing (and still counts as that period's digest). Turn it on if silence is ambiguous for you and you would rather get an "all clear".
digestSite and digestChecks
Which site's graph to report on, and which checks. Nothing ticked means every check. Orphans and unused assets are left out by default — they are housekeeping rather than breakage, and on most sites they would bury the one broken reference the digest exists to surface.
"New" means a finding that was not in the last digest, matched by element ids, never titles — so renaming an entry does not make its broken relation news again, and a problem that was fixed and then comes back is.
Sending it: cron, or the web fallback
The reliable way is a cron job. It is safe to run as often as you like:
*/15 * * * * php /path/to/craft yarn/digest/send
Without one, leave digestWebTrigger on: at the end of a web request Yarn looks at the
schedule (at most every five minutes — a cache read the rest of the time) and, when the digest is
due, queues a job to send it. Either route ends in the same decision, recorded in Yarn's one
database table, so cron and the fallback never both send.
Yarn deliberately does not use Craft's garbage-collection event for this: it runs on a dice roll, which is not a schedule.
Send a test digest now, at the bottom of the settings screen and of Yarn → Findings, sends what the next digest would say, marked as a test, to the recipients (or to you, when there are none). It does not count as the period's digest. It needs the Send a test findings digest permission.
logLevel
debug, info (default), warning or error. Yarn logs to storage/logs/yarn.log.