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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Lonsdale201/wp-agent-skills --skill bd-data-object技能说明
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: trueto theMetaKeyand store the property as a plainstring." Wrong shape —#[Encrypted]writes ciphertext but the in-memory value is still a plain string that leaks viavar_dump/print_r/serialize. UseSecretas the property type. - "I'll add a public mutator method (
setEmail()) to make consumer code more ergonomic." Wrong — every DTO isfinal readonly class. Mutation is$dto->with(['email' => 'new@example.com'])which returns a NEW instance. Mutators break the immutability contract thatSecret, 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 DataObjectundersrc/,tests/Fixtures/, or the companion plugin'sDto/. - 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
MissingRequiredFieldExceptionat runtime — usually the cause is a trailing parameter without a default.
Workflow
1. Choose the file location
| What you're building | Path |
|---|---|
| Production DTO (library users hydrate it) | src/<area>/<Name>Dto.php |
| Test-only fixture | tests/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 vianewInstanceArgs; 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:
| Type | Default |
|---|---|
int | = 0 |
string | = '' |
float | = 0.0 |
bool | = false |
array | = [] |
?DateTimeImmutable | = null |
?Secret | = null (NEVER new Secret('')) |
BackedEnum | first 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:
?DateTimeImmutableover?stringfor timestamps —TypeCoercerparses ISO-8601 strings andWC_DateTimeinst