Bag PHP Library

Bag is a library for creating immutable, strongly typed Value Objects in PHP.

When to use them: You should use Bag Value Objects in place of regular associative arrays. This allows you to enforce type safety and immutability, making your data handling safer and more predictable.

Key Features:

• Immutability & Strong Typing: Data cannot be changed after instantiation, and types are strictly enforced.
• Built-in Validation & Casting: Ensures data conforms to expected formats.
• Composability: You can nest Bag value objects and collections to build complex, hierarchical data structures.

Bag is a PHP library designed to help you create immutable and strongly typed value objects. It provides a safer and more predictable way to work with data by encapsulating it within objects rather than using regular arrays.

Key features include:

• Immutability & Strong Typing: Ensures data cannot be changed after instantiation and enforces type safety.
• Composability: Allows you to nest Bag value objects and collections to build complex, hierarchical data structures.
• Built-in Validation & Casting: Provides mechanisms to validate and cast data during object creation.

Bag is a library for creating immutable, strongly-typed value objects in PHP 8.3+.

Use Bag value objects in place of regular arrays to enforce type safety and immutability. Bag provides features like value casting (input and output), collection support, composability (nesting objects and collections), and built-in validation.

Key Characteristics:

• Immutable & Strongly typed: Once created, the data cannot be changed.
• Composable: You can nest Bag value objects and collections within each other.
• Framework Agnostic: While it works with any PHP project, it has deep integration with Laravel, using standard Laravel Collections and Validation, and supports automatic injection of Bag objects into Laravel controllers with validation.

Bag is a lightweight PHP library for working with immutable value objects. It provides several core capabilities for data handling:

• Value Casting: Supports both inbound and outbound casting, including support for nested Bag objects.
• Name Mapping: Allows mapping property names at both the class and property levels.
• Validation: Integrated validation support.
• Collections: Support for collections of Value Objects, specifically using Bag\Collection (an immutable-safe variant of Laravel Collections).
• Conversions: Ability to convert objects to Bag instances and wrap output arrays or JSON.
• Laravel Integration: Supports Eloquent Casting and Laravel Controller Injection.
• Hidden Properties: Ability to hide specific properties when transforming an object to an array or JSON.
• Variadic Support: Supports variadic arguments during value object creation.

Bag is a lightweight PHP library for working with immutable value objects. Key features include:

• Value Casting: Supports casting for both incoming and outgoing values, including nested Bag objects.
• Name Mapping: Allows mapping property names at both the class and property levels for both input and output.
• Validation: Integrated support for validating value object data.
• Collections: Support for collections of value objects, specifically using Bag\Collection (an immutable-safe variant of Laravel Collections).
• Object Conversion: Ability to convert standard objects to Bag instances.
• Output Wrapping: Support for wrapping output arrays or JSON.
• Laravel Integration: Includes support for Eloquent Casting and Laravel Controller Injection.
• Hidden Properties: Ability to hide specific properties when transforming the object to an array or JSON.

Bag is a lightweight PHP library for working with immutable, type-safe value objects. Key capabilities include:

• Value Casting: Supports both inbound and outbound casting, including nested Bag objects.
• Name Mapping: Allows mapping property names at both the class and property levels for inbound and outbound data.
• Validation: Integrated support for validating value object data.
• Collections: Native support for collections of value objects, specifically using Bag\Collection for immutable-safe operations.
• Object Conversion: Ability to convert standard objects into Bag instances.
• Output Wrapping: Supports wrapping output arrays or JSON.
• Laravel Integration: Provides support for Eloquent Casting and Laravel Controller Injection.
• Hidden Properties: Ability to hide specific properties when transforming a Bag to an array or JSON.

The OutputCollectionPipeline is specifically designed for transforming Bag collections into arrays or JSON. It is triggered by calling toArray(), toJson(), json_encode(), or unwrapped() on a Collection object.

The process is simple:

1. The collection data is retrieved.
2. The output is passed through a wrap step (if converting to an array or JSON) to ensure the collection structure is correctly represented in the final output.

If the input value matches the property type (including union types), it is used as-is. Otherwise, Bag automatically casts values to the defined type for all scalar types and the following:

• Bag objects
• \Bag\Collection and \Illuminate\Support\Collection objects
• \DateTimeInterface objects (including \DateTime, \DateTimeImmutable, \Carbon\Carbon, and \Carbon\CarbonImmutable) using standard PHP Date/Time formats.
• Enums

Recommendation: Use \Carbon\CarbonImmutable for all date/time properties.

By default, Bag attempts to transform JSON strings. To override the default JSON handling or to explicitly differentiate between standard strings and JSON strings, use the special type Bag::FROM_JSON within the #[Transforms] attribute.

This is useful when you want to ensure a specific method is only called when the input is intended to be parsed as JSON.

use Bag\Bag;

class MyValue extends Bag
{
    #[Transforms(Bag::FROM_JSON)]
    protected static function fromJsonString(string $json): array
    {
        return json_decode($json, true, 512, JSON_THROW_ON_ERROR);
    }
}