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

bd-data-object

Add or modify DataObject subclasses inside the better-data library — the immutable, attribute-decorated DTOs the whole library is built around. Every DTO is final readonly class extends DataObject with constructor-promoted typed parameters; sources hydrate via ::fromArray, sinks project via SinkProjection, the Presenter renders via HasPresenter trait. Important — every trailing constructor parameter MUST have a default; otherwise PHP Reflection reports isDefaultValueAvailable=false on earlier params too and DataObject throws MissingRequiredFieldException at hydration. Also Secret fields default to ?Secret = null (never new Secret('')), encrypt requires the Secret type, and DTOs never grow public mutators (use ->with()). Use when adding a new DTO (e.g. UserProfileDto), adding fields to an existing DTO, or reviewing a PR introducing a class extending DataObject. Triggers on extends DataObject, DataObject::fromArray, ->with(), HasWpSources, HasWpSinks, HasPresenter, MissingRequiredFieldEx

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-data-object

About this skill


name: bd-data-object description: Add or modify DataObject subclasses inside the better-data library — the immutable, attribute-decorated DTOs the whole library is built around. Every DTO is final readonly class extends DataObject with constructor-promoted typed parameters; sources hydrate via ::fromArray, sinks project via SinkProjection, the Presenter renders via HasPresenter trait. Important — every trailing constructor parameter MUST have a default; otherwise PHP Reflection reports isDefaultValueAvailable=false on earlier params too and DataObject throws MissingRequiredFieldException at hydration. Also Secret fields default to ?Secret = null (never new Secret('')), encrypt requires the Secret type, and DTOs never grow public mutators (use ->with()). Use when adding a new DTO (e.g. UserProfileDto), adding fields to an existing DTO, or reviewing a PR introducing a class extending DataObject. Triggers on extends DataObject, DataObject::fromArray, ->with(), HasWpSources, HasWpSinks, HasPresenter, MissingRequiredFieldException in better-data. 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: Adding a DataObject

For library maintainers and downstream contributors who add or modify a DataObject subclass inside better-data. Every typed shape — production DTOs in src/, test fixtures in tests/Fixtures/, plugin-level DTOs in the companion testbed — extends the abstract DataObject (src/DataObject.php:36) and is the foundation that every engine (sources, sinks, validation, Presenter, REST schema, better-route bridge) reads against.

Misconception this skill corrects

"I'll just declare the constructor parameters with the types I want and set the values when I instantiate the class — defaults are optional."

In better-data, defaults are load-bearing. The hydration entry point DataObject::fromArray (src/DataObject.php:47-79) iterates ReflectionParameters and treats any parameter without isDefaultValueAvailable() (and without allowsNull()) as REQUIRED — throwing MissingRequiredFieldException. PHP's Reflection silently demotes earlier-positioned defaults to "required" if a later parameter has no default — so a single missing default at the end cascades and breaks ::fromArray for the whole DTO.

Other AI-prone misconceptions:

  • "I'll add encrypt: true to the MetaKey and store the property as a plain string." Wrong shape — #[Encrypted] writes ciphertext but the in-memory value is still a plain string that leaks via var_dump / print_r / serialize. Use Secret as the property type.
  • "I'll add a public mutator method (setEmail()) to make consumer code more ergonomic." Wrong — every DTO is final readonly class. Mutation is $dto->with(['email' => 'new@example.com']) which returns a NEW instance. Mutators break the immutability contract that Secret, route-side projection, and Presenter caching all depend on.

When to use this skill

Trigger when ANY of the following is true:

  • Adding a new final readonly class extends DataObject under src/, tests/Fixtures/, or the companion plugin's Dto/.
  • Adding, removing, or retyping a constructor parameter on an existing DTO.
  • The diff or PR title mentions: "new DTO", "add Dto", "add field to Dto", "introduce Dto".
  • Reviewing a class that extends DataObject — use this skill's checklist before approving.
  • Hitting MissingRequiredFieldException at runtime — usually the cause is a trailing parameter without a default.

Workflow

1. Choose the file location

What you're buildingPath
Production DTO (library users hydrate it)src/<area>/<Name>Dto.php
Test-only fixturetests/Fixtures/<Name>Dto.php
Plugin-level DTO (companion testbed)wp-content/plugins/better-data-plugin-test/src/Dto/<Name>Dto.php

2. Declare the class

namespace MyNamespace;

use BetterData\DataObject;
use BetterData\Source\HasWpSources;
use BetterData\Sink\HasWpSinks;
use BetterData\Presenter\HasPresenter;

final readonly class ProductDto extends DataObject
{
    use HasWpSources;
    use HasWpSinks;
    use HasPresenter;

    public function __construct(
        public int $id = 0,
        public string $post_title = '',
        public string $post_status = 'publish',
    ) {}
}

Three non-negotiables:

  • final — never extended. The library does not support subclass-of-DTO patterns.
  • readonly — every property is immutable. Hydration writes once via newInstanceArgs; consumers mutate via ->with(...).
  • extends DataObject — gives you ::fromArray, ::fromArrayValidated, ->toArray(), ->with(), attribute-aware coercion.

3. Constructor-promoted parameters with defaults on every trailing one

The single most important rule. Every parameter must have either an explicit default OR be nullable. Recommended defaults by type:

TypeDefault
int= 0
string= ''
float= 0.0
bool= false
array= []
?DateTimeImmutable= null
?Secret= null (NEVER new Secret(''))
BackedEnumfirst case (= MyEnum::Default) or = null if nullable

PHP-side reasoning: ReflectionParameter::isDefaultValueAvailable() returns false when ANY required parameter sits later in the signature. The hydrator at src/DataObject.php:63-73 checks this exact predicate; missing a default at position N silently breaks defaults at positions 0..N-1.

4. Choose the most-specific type possible

Better-data leans on type information for coercion, schema generation, and Presenter formatting. Be specific:

  • ?DateTimeImmutable over ?string for timestamps — TypeCoercer parses ISO-8601 strings and WC_DateTime inst
Read the complete source ↗