Simple Data Objects

composer require std-out/simple-data-objects

Why

Performance

Quick Look

use StdOut\SimpleDataObjects\BaseData;
use StdOut\SimpleDataObjects\Attributes\{Cast, Rules, Pipe};
use StdOut\SimpleDataObjects\Casts\DateTimeCast;
use StdOut\SimpleDataObjects\Pipes\TrimValuePipe;

class CreateOrderData extends BaseData
{
    public function __construct(
        #[Rules(['required', 'string', 'max:200'])]
        #[Pipe(TrimValuePipe::class)]
        public readonly string $title,

        #[Rules(['required', 'email'])]
        public readonly string $customerEmail,

        #[Cast(new DateTimeCast('Y-m-d'))]
        public readonly \DateTime $deliveryDate,

        public readonly ?string $notes = null,
    ) {}
}

// validate → pipe → cast → hydrate
$order = CreateOrderData::fromValidated($request->all());

$order->title;            // trimmed string
$order->deliveryDate;     // \DateTime object
$order->toArray();        // ['title' => ..., 'customerEmail' => ..., 'deliveryDate' => '2025-01-15']
$order->toJson();         // JSON string
$order->with(notes: 'x'); // immutable copy with override

Killer Features

DataPipe — input preprocessing middleware

use StdOut\SimpleDataObjects\Pipes\{TrimStringsPipe, NullifyEmptyStringsPipe};
use StdOut\SimpleDataObjects\Pipes\{TrimValuePipe, NullifyEmptyStringValuePipe};

// Class-level: runs on the entire input array
#[Pipe(TrimStringsPipe::class, NullifyEmptyStringsPipe::class)]
class ContactData extends BaseData { ... }

// Property-level: runs only on that field's value
class ProfileData extends BaseData
{
    public function __construct(
        #[Pipe(TrimValuePipe::class)]
        public readonly string $name,

        #[Pipe(TrimValuePipe::class, NullifyEmptyStringValuePipe::class)]
        public readonly ?string $bio = null,
    ) {}
}

final class UpperCasePipe implements ValuePipe
{
    public function handle(mixed $value, string $paramName, callable $next): mixed
    {
        return $next(is_string($value) ? strtoupper($value) : $value);
    }
}

Zero-reflection in production

// bootstrap / AppServiceProvider — run once
MetadataRegistry::setStoragePath(storage_path('framework/data-objects'));

vendor/bin/sdo-warm storage/framework/data-objects app/Data

Streaming large datasets

foreach (UserData::lazyCollection($csvRows) as $user) {
    $importer->process($user); // ~12 KB peak at 100k rows — flat regardless of row count
}

Streaming large XML files

class OfferData extends BaseData   // <offer id="42"><name>…</name><price currency="UAH">499.90</price><picture>…</picture>…</offer>
{
    public function __construct(
        #[XmlAttribute]
        public readonly int $id,
        public readonly string $name,
        public readonly PriceData $price,
        #[XmlElement('picture')]
        public readonly array $pictures,
    ) {}
}

class PriceData extends BaseData
{
    public function __construct(
        #[XmlText]
        public readonly float $amount,
        #[XmlAttribute]
        public readonly string $currency,
    ) {}
}

OfferData::lazyXml('feed.xml', 'catalog/shop/offers/offer')
    ->filter(fn (OfferData $offer) => $offer->price->amount > 100)
    ->each(fn (OfferData $offer) => $importer->process($offer));

Immutable copies with with()

$updated = $user->with(email: '[email protected]'); // original unchanged
$updated->equals($user);                           // false
$user->diff($updated);                             // ['email' => ['old@...', 'new@...']]

Typed collections with IDE generics

#[DataCollection(UserData::class)]
public readonly TypedDataCollection $members,

// IDE infers type throughout the chain:
$team->members->filter(fn (UserData $u) => $u->active)->first()->name;

Validation anywhere

// In Laravel — call fromRequest() yourself, auto-validates
$data = CreateOrderData::fromRequest($request);

// Or register SimpleDataObjectsServiceProvider (opt-in, not auto-discovered)
// and skip FormRequest entirely:
public function store(CreateOrderData $data) { /* already validated */ }

// Standalone — no Laravel app needed
CreateOrderData::validate($rawArray); // throws ValidationException

Never-throw error accumulation

$result = CreateOrderData::fromResult($request->all());

$result->ok();       // bool
$result->errors();   // ['deliveryDate' => 'Invalid date format', 'items.2.price' => '...']
$result->value();    // CreateOrderData — throws if !ok()

// fromValidatedResult() merges in #[Rules] failures the same way

Optional — PATCH semantics

class UpdateUserData extends BaseData
{
    public function __construct(
        public readonly string|Optional $name,
        public readonly string|Optional|null $bio,   // null = clear it, Optional = don't touch it
    ) {}
}

$data = UpdateUserData::from(['bio' => null]);
$data->definedOnly();   // ['bio' => null] — 'name' stays absent
$model->update($data->definedOnly());

Generating classes from a sample

vendor/bin/sdo-generate storage/samples/order.json app/Data
curl -s https://api.example.com/orders/1 | vendor/bin/sdo-generate - app/Data --class=OrderData
php artisan make:data OrderData --from-model=Order --id=1042 --with=customer,items

Schema generation — JSON Schema & TypeScript

OrderData::jsonSchema();
// ['type' => 'object', 'properties' => [...], 'required' => [...], '$defs' => [...]]

vendor/bin/sdo-typescript resources/js/types/data-objects.d.ts app/Data

export interface OrderData {
  id: number;
  shippingAddress: AddressData;
  status: 'pending' | 'shipped' | 'cancelled';
}

All Attributes

Built-in Casts

Contributing

License