Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

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-presenter

About 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 readonly like 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 a compute() 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 — CollectionPresenter records 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 on Presenter + mirrored on CollectionPresenter.
  • 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:

  1. Return static (not self, not Presenter) so subclasses chain correctly.
  2. Parameter naming follows existing conventions — $field for single, $fields for list, $capability for cap names, $as for output-key rename.
  3. Mutate $this->... private state. Don't add new public mutable state.
  4. Return $this at the end of every fluent method.
  5. Single concern per method. hideIfBlank doesn't also rename. Compose at the call site: ->hideIfBlank('foo')->rename('foo', 'bar').
  6. 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->dto would 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 ↗