bd-attribute
Add a new declarative attribute to the better-data library (e.g. #[ArrayOf], #[Default], domain hint). Attributes live in src/Attribute/ as final readonly classes with constructor-promoted public properties — pure data carriers, never business logic. The failure mode that catches every contributor is "partial wiring" — declaring the attribute and reading it in ONE engine (e.g. only PostSink) while leaving Presenter, RestSchemaBuilder, and AttributeDrivenHydrator untouched. Stress scenarios have caught this pattern repeatedly. Every relevant engine must know about the new attribute, otherwise it silently degrades on the unwired path. Use when adding any new #[Foo] attribute that DTO authors will sprinkle on parameters / properties. Triggers on creating a class in src/Attribute/, applying #[Attribute(...)], references to AttributeDrivenHydrator / SinkProjection::prepareValue / RestSchemaBuilder / Presenter::sensitiveFieldNames in the diff.
Lonsdale201 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Lonsdale201/wp-agent-skills --skill bd-attribute技能说明
name: bd-attribute description: >- Add a new declarative attribute to the better-data library (e.g. #[ArrayOf], #[Default], domain hint). Attributes live in src/Attribute/ as final readonly classes with constructor-promoted public properties — pure data carriers, never business logic. The failure mode that catches every contributor is "partial wiring" — declaring the attribute and reading it in ONE engine (e.g. only PostSink) while leaving Presenter, RestSchemaBuilder, and AttributeDrivenHydrator untouched. Stress scenarios have caught this pattern repeatedly. Every relevant engine must know about the new attribute, otherwise it silently degrades on the unwired path. Use when adding any new #[Foo] attribute that DTO authors will sprinkle on parameters / properties. Triggers on creating a class in src/Attribute/, applying #[Attribute(...)], references to AttributeDrivenHydrator / SinkProjection::prepareValue / RestSchemaBuilder / Presenter::sensitiveFieldNames in the diff. 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 new attribute
For library maintainers introducing a new declarative hint that DTO authors will place on constructor parameters / properties — #[ArrayOf], #[Default], #[ListOf]-style markers, domain-specific decorators. The attribute itself is just a data carrier; the work is wiring it into every engine that reads attributes, because partial wiring silently degrades.
Misconception this skill corrects
"I'll add
src/Attribute/Foo.phpand read it inPostSink— done."
Attributes are read by multiple engines, and missing one leaves a feature that works on a happy path and fails subtly elsewhere. The original encrypt flag was meta-only; when options needed the same semantics, the partial wiring left a footgun until #[Encrypted] replaced it across OptionSink, PostSink, AttributeDrivenHydrator, RestSchemaBuilder, and Presenter — all in one go.
The engines that read attributes today, all need to know about a new attribute relevant to their concern:
- Read-side hydration:
AttributeDrivenHydrator(src/Internal/AttributeDrivenHydrator.php) andDataObject::coerceParameter(src/DataObject.php:168). - Write-side projection:
SinkProjection::prepareValue(src/Internal/SinkProjection.php:193) andOptionSink::projectForStorage(src/Sink/OptionSink.php:119). - REST / OpenAPI schema:
RestSchemaBuilder::buildProperty(src/Internal/RestSchemaBuilder.php). - Output / display:
Presenter::sensitiveFieldNamesand friends in src/Presenter/Presenter.php.
If your attribute is a write-time concern (encryption, formatting, slashing), all four still need to coordinate — read-side has to invert what write-side did.
When to use this skill
Trigger when ANY of the following is true:
- Creating a new file under
src/Attribute/. - Adding
#[Attribute(...)]to any class. - The diff adds a new attribute reference (
#[NewThing]) to a DTO and to the consumer engine. - Reviewing a PR that wires an attribute into ONE engine — flag every other relevant engine as missing.
Workflow
1. File and shape
<?php
declare(strict_types=1);
namespace BetterData\Attribute;
use Attribute;
#[Attribute(Attribute::TARGET_PARAMETER | Attribute::TARGET_PROPERTY)]
final readonly class Foo
{
public function __construct(
public string $name = '',
public bool $required = false,
) {}
}
Three structural rules:
TARGET_PARAMETER | Attribute::TARGET_PROPERTY— better-data DTOs use constructor-promoted parameters which appear as both. Restricting to just one breaks DTO authors who happen to use the other style.final readonly class— same immutability promise the DTOs make. Attribute instances are constructed once per Reflection lookup; mutation is meaningless.- Constructor-promoted public properties — the attribute reads its own data via
$reflectionAttribute->newInstance()->propertyName. No methods, no business logic.
2. Repeatable attributes
If a single parameter can carry the attribute multiple times (validation rules, multiple format hints), add Attribute::IS_REPEATABLE:
#[Attribute(
Attribute::TARGET_PARAMETER | Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE
)]
final readonly class Tag
{
public function __construct(public string $name) {}
}
Then on the read side, use getAttributes(Tag::class) (which returns array<ReflectionAttribute>) and iterate, instead of getAttributes(Tag::class)[0] ?? null.
3. Decide which engines need to know
| Engine | Read it when… | File |
|---|---|---|
AttributeDrivenHydrator | Attribute affects how a stored value becomes a typed property (decryption, list-coercion) | src/Internal/AttributeDrivenHydrator.php |
DataObject::coerceParameter | Attribute affects type coercion in ::fromArray (the simple in-memory hydration path) | src/DataObject.php:168 |
SinkProjection::prepareValue | Attribute affects how a property becomes a storable scalar / array | src/Internal/SinkProjection.php:193 |
OptionSink::projectForStorage | Attribute changes how an option-sink-bound property serializes (different from meta) | src/Sink/OptionSink.php:119 |
RestSchemaBuilder::buildProperty | Attribute should appear in REST schema / OpenAPI output | src/Internal/RestSchemaBuilder.php |
Presenter::sensitiveFieldNames / filters | Attribute affects what present()->toArray() shows | src/Presenter/Presenter.php:481 |
A common trap: an attribute looks like a write-only concern (e.g. "always sanitize HTML on save") but the read side m
阅读完整来源 ↗