Basic Usage

Creating a Value Object

To create a new Value Object, extend the Bag\Bag class and define your properties in the constructor:

use Bag\Bag;

readonly class MyValue extends Bag {
    public function __construct(
        public string $name,
        public int $age,
    ) {
    }
}

TIP

You can add an @method annotation to your class to provide auto-complete for the ::from() method, or use the Artisan Command with the --doc option to generate it for you.

Instantiating a Value Object

To create a new instance of your Value Object, call the ::from() method. You can use an array, a Collection, named arguments, or positional arguments.

Named Arguments

$value = MyValue::from(
    name: 'Davey Shafik',
    age: => 40,
);

Array or Collection of Arguments

$value = MyValue::from([
    'name' => 'Davey Shafik',
    'age' => 40,
]);

or:

$value = MyValue::from(collect([
    'name' => 'Davey Shafik',
    'age' => 40,
]));

Positional Arguments

$value = MyValue::from('Davey Shafik', 40);

WARNING

If you use positional arguments, you must ensure they are in the same order as the constructor.

WARNING

If you have a single array argument, and an array transformer, the transformer will be applied to the array, potentially causing unwanted side-effects.

Type Casting

Bag will cast all values to their defined type automatically for all scalar types, as well as the following:

• Bag objects
• \Bag\Collection and \Illuminate\Support\Collection objects
• \DateTimeInterface objects will be cast using standard PHP Date/Time formats
  • This includes \DateTime, \DateTimeImmutable, \Carbon\Carbon and \Carbon\CarbonImmutable
• Enums

TIP

We recommend using \Carbon\CarbonImmutable for all date times.

Modifying a Value Object

Value Objects are immutable, so you cannot change their properties directly. Instead, you can create a new instance with the updated values using the Bag->with() method:

$value = MyValue::from([
    'name' => 'Davey Shafik',
    'age' => 40,
]);

$newValue = $value->with(age: 41);

dump($newValue->toArray()); // ['name' => 'Davey Shafik', 'age' => 41]

You can pass either named arguments, or an array or Collection of key-value pairs to the Bag->with() method.