bd-presenter
Extend the better-data Presenter — add a fluent builder
Lonsdale201 · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Lonsdale201/wp-agent-skills --skill bd-presenterAbout this skill
name: bd-presenter description: Extend the better-data Presenter — add a fluent builder method (rename, mask, format, compute) or a PresentationContext flag. The Presenter is a mutable builder around a readonly DTO — each fluent method mutates internal state ($this->only, $this->hidden, $this->computed, etc.) and returns $this for chaining; the wrapped DataObject NEVER mutates. CollectionPresenter records every configurer as a closure on $this->configurers and replays them per item in toArray. Critical contract — any new method that emits values from the DTO MUST honor sensitiveFieldNames() (the Sensitive attribute + Secret type list); a method that bypasses redaction is a security regression. Localized strings need LocaleScope::runIn so withLocale() works. Use when adding mask, formatDate-like, hideIf, context-aware methods. Triggers on changes to Presenter.php / CollectionPresenter.php / PresentationContext.php / Formatter/. metadata: wp-skills-author: "Soczó Kristóf" wp-skills-contact: "mailto:lonsdale201@hotmail.com" wp-skills-plugin: "better-data" wp-skills-plugin-version-tested: "phase-9" wp-skills-php-min: "8.3" wp-skills-last-updated: "2026-04-29"
better-data: Extending the Presenter
For library maintainers adding output transformations to the better-data Presenter — a new fluent builder method (mask, formatPhone, hideIfBlank), a PresentationContext flag (admin vs REST vs export), or a Formatter helper. The Presenter is the read-side projection layer between a DataObject and whatever consumes it (admin UI, REST response, audit log).
Misconception this skill corrects
"The Presenter is
readonlylike the DataObject — every fluent method must clone and return a new instance."
Wrong. The DataObject is readonly, the Presenter is intentionally a mutable builder. Look at src/Presenter/Presenter.php:65-89 — class Presenter (not final readonly class), with private mutable properties $only, $hidden, $rename, $computed, $presets, $includeSensitive. Each fluent method assigns to $this->... and returns $this. This is deliberate — chained calls share state, repeated calls override, and there's no clone overhead.
What IS immutable: $this->dto is protected readonly DataObject and never gets reassigned. The builder mutates ITS state to control HOW the DTO is rendered; the DTO itself stays untouched.
The "don't mutate permanently" rule from older docs means: don't introduce a method whose effect can't be reset by a subsequent method or context swap. A method that pushes to a private array is fine; a method that writes to a static cache or to the wrapped DTO would be a regression.
Other AI-prone misconceptions:
- "I'll add
getSecretRevealed()so consumers don't need->reveal()boilerplate." Wrong — the explicit$dto->field->reveal()inside acompute()closure IS the security audit point. Adding a bypass method is the same regression as a debug-mode log of secrets. - "CollectionPresenter is a separate Presenter; I just add the method there too with copy/paste logic." Wrong —
CollectionPresenterrecords each configurer as a closure on$this->configurers(src/Presenter/CollectionPresenter.php:30-44) and replays it on every item via the per-item Presenter. The pattern is$this->configurers[] = static fn (Presenter $p) => $p->yourMethod(...);. No business logic on the collection side.
When to use this skill
Trigger when ANY of the following is true:
- Adding a fluent method to
Presenter/CollectionPresenter(hideIfBlank,truncate,defaultIfNull). - Adding a flag / accessor to
PresentationContext(isExport(),currentUserId()). - Adding a Formatter helper under
src/Presenter/Formatter/. - Reviewing a PR that emits DTO values without going through
sensitiveFieldNames()redaction.
Workflow
1. Decide: per-call (Presenter) or per-context (PresentationContext)
- Per-call (fluent method): the caller decides each invocation. Examples:
only(['email']),hide('apiKey'),formatDate('createdAt', 'Y-m-d'). Lives onPresenter+ mirrored onCollectionPresenter. - Per-context (PresentationContext): the entire rendering environment changes. Examples: REST response vs admin table vs export CSV. Lives on
PresentationContext.
Most additions are per-call. Per-context additions are rarer and require updating PresentationContext::rest(), ::admin(), ::none(), etc.
2. Per-call method shape
Look at existing methods like hide (Presenter.php:164) or rename (Presenter.php:204):
public function hideIfBlank(string|array $field): static
{
$fields = (array) $field;
foreach ($fields as $f) {
$this->hidden[$f] = static fn (PresentationContext $ctx, mixed $value): bool
=> $value === null || $value === '' || $value === [];
}
return $this;
}
Six structural rules:
- Return
static(notself, notPresenter) so subclasses chain correctly. - Parameter naming follows existing conventions —
$fieldfor single,$fieldsfor list,$capabilityfor cap names,$asfor output-key rename. - Mutate
$this->...private state. Don't add new public mutable state. - Return
$thisat the end of every fluent method. - Single concern per method.
hideIfBlankdoesn't also rename. Compose at the call site:->hideIfBlank('foo')->rename('foo', 'bar'). - Resettable. A subsequent call to a related method (or a
context()swap) should be able to undo the effect. Methods that push to$this->hidden[$field]work; methods that mutate the wrapped$this->dtowould not.
3. Mirror the method on CollectionPresenter
Every per-call method gets a mirror at src/Presenter/CollectionPresenter.php that records a configurer:
public function hideIfBlank(string|array $field): self
{
Read the complete source ↗