PHP code example of treptow-labs / envelope

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

treptow-labs / envelope example snippets

class UpdateUserDto
{
    public ?string $name;
    public ?string $bio;
}

use TreptowLabs\Envelope\Option;
use TreptowLabs\Envelope\Some;
use TreptowLabs\Envelope\None;

$present = Some::make('Jane');
$absent = None::make();

$present->isSome(); // true
$absent->isNone();  // true

$present->unwrap();      // 'Jane'
$absent->unwrap();       // throws \RuntimeException, None has nothing to unwrap
$absent->unwrapOr('N/A'); // 'N/A'
$absent->unwrapOr(fn () => 'N/A'); // 'N/A', callables are also accepted

$present->map(fn ($name) => strtoupper($name)); // Some('JANE')
$absent->map(fn ($name) => strtoupper($name));  // still None, map is a no-op on None

Option::from('Jane');       // Some('Jane')
Option::from(null);         // None (default sentinel is null)
Option::from(-1, -1);       // None ($value matches the given sentinel)

use TreptowLabs\Envelope\Envelope;
use TreptowLabs\Envelope\Option;

class UpdateUserDto extends Envelope
{
    public function __construct(
        public Option $name = new None(),
        public Option $bio = new None(),
        public Option $isActive = new None(),
    ) {}
}

$dto = new UpdateUserDto(
    name: Some::make('Jane'),
    isActive: Some::make(null), // explicitly provided, and explicitly null
);

$dto->toArray();
// ['name' => 'Jane', 'isActive' => null]
// 'bio' is completely absent from the array, it was never touched

use TreptowLabs\Envelope\Support\EnvelopeResolver;

$resolver = EnvelopeResolver::make($request->validated());

$dto = new UpdateUserDto(
    name: $resolver->string('name'),
    bio: $resolver->string('bio'),
    isActive: $resolver->boolean('isActive'),
);

$resolver->stringOrThrow('email');
// same as: $resolver->string('email', nullable: false, throw: true)

use TreptowLabs\Envelope\Attributes\MapsTo;

class UpdateUserDto extends Envelope
{
    public function __construct(
        #[MapsTo('is_active')]
        public Option $isActive,
    ) {}
}

use TreptowLabs\Envelope\Attributes\Omit;

class UpdateUserDto extends Envelope
{
    public function __construct(
        public Option $name,
        #[Omit]
        public Option $internalNotes,
    ) {}
}

use TreptowLabs\Envelope\Attributes\FormatUsing;
use TreptowLabs\Envelope\Formatters\DateTimeFormatter;

class UpdateEventDto extends Envelope
{
    public function __construct(
        #[FormatUsing(DateTimeFormatter::class, \DateTimeInterface::ATOM)]
        public Option $startsAt,
    ) {}
}

use TreptowLabs\Envelope\Formatters\Formatter;

class UppercaseFormatter implements Formatter
{
    public function format(mixed $value): mixed
    {
        return is_string($value) ? strtoupper($value) : $value;
    }
}

use TreptowLabs\Envelope\Attributes\MapsTo;
use TreptowLabs\Envelope\Attributes\FormatUsing;
use TreptowLabs\Envelope\Envelope;
use TreptowLabs\Envelope\Formatters\DateTimeFormatter;
use TreptowLabs\Envelope\Option;
use TreptowLabs\Envelope\Support\EnvelopeResolver;

class UpdateUserDto extends Envelope
{
    public function __construct(
        public Option $name,
        #[MapsTo('is_active')]
        public Option $isActive,
        #[FormatUsing(DateTimeFormatter::class)]
        public Option $verifiedAt,
    ) {}

    public static function fromRequest(array $data): self
    {
        $resolver = EnvelopeResolver::make($data);

        return new self(
            name: $resolver->string('name'),
            isActive: $resolver->boolean('is_active'),
            verifiedAt: $resolver->get('verified_at', fn ($v) => $v ? new \DateTimeImmutable($v) : null),
        );
    }
}

// In your controller:
public function update(Request $request, User $user)
{
    $dto = UpdateUserDto::fromRequest($request->all());

    $user->update($dto->toArray());

    return $user;
}

// Example requests:
PATCH /users/123
{"name": "Jane"}

- Only `name` is updated; `is_active` and `verified_at` are untouched

PATCH /users/123
{"verified_at": null}

- `verified_at` is set to `null`; `name` and `is_active` are untouched