Download the PHP package stougeiro/immutable without Composer

Immutable

Immutable is a rigorously designed data structure for PHP that enforces deep immutability across arrays, objects, and nested collections. It provides a predictable, safe, and expressive way to represent structured data without allowing accidental mutation, dynamic property creation, or silent type inconsistencies. Every value stored inside an Immutable instance is recursively normalized, ensuring that associative arrays become immutable objects, indexed arrays become immutable lists, and scalar values remain untouched. This strict normalization ensures that the structure you create is the structure you keep — permanently.

The core philosophy behind Immutable is to eliminate an entire class of bugs caused by unintended state changes. In traditional PHP arrays and objects, any part of the structure can be modified at any time, often far from where the data was originally created. Immutable prevents this by guaranteeing that once a structure is created, its shape and values cannot be altered — not directly, not indirectly, and not through nested references.

Immutable brings discipline and reliability to PHP’s flexible but mutation‑prone data structures. It enforces deep immutability, provides safe and expressive access patterns, and ensures that your data remains exactly as intended from the moment it is created. Whether used in small utilities or large-scale applications, Immutable helps developers write clearer, safer, and more predictable code.

✨ Features

• Deep Immutability
  Every nested element — objects, lists, and scalar values — is recursively wrapped and protected. Attempts to modify, unset, or overwrite any property or index result in explicit exceptions. Dynamic property creation, silently allowed in native PHP, is strictly forbidden.

• Strict Structural Semantics
  Immutable distinguishes between associative arrays (treated as objects) and indexed arrays (treated as lists). This distinction is preserved throughout the entire structure. Accessing an object as a list or a list as an object triggers an access exception, preventing ambiguous or incorrect usage.

• Safe Chained Access (isset‑safe)
  Missing properties return null, allowing chained isset() evaluations to behave safely and predictably without producing fatal errors.

• Native PHP Errors for Invalid Direct Access
  Immutable does not intercept invalid direct method calls on non-object values. When such operations occur, PHP’s native error system handles them, preserving natural language-level behavior.

• Explicit Error Signaling
  Invalid operations — such as calling methods on non-object list items, accessing nonexistent properties, or attempting mutation — produce clear, intentional exceptions. This makes debugging significantly easier and prevents silent failures.

• Conversion Back to Native Arrays
  The toArray() method returns the original array as provided during construction. Since PHP arrays are value types, this effectively provides a deep copy of the structure. Modifying the returned array does not affect the immutable instance.

• No Silent Type Coercion
  Immutable never converts lists into objects or objects into lists. If you attempt to access a list as an object or vice‑versa, an explicit exception is thrown.

📦 Installation

Install via Composer:

🚀 Usage Example

Immutable Object Access

This shows object-style access for associative arrays, preserving structure and preventing mutation.

Immutable List Access

Indexed arrays behave as immutable lists, allowing safe index access without converting items into objects.

Deep Conversion Back to Native Arrays

toArray() deeply unwraps the immutable structure into a native PHP array, ensuring the original immutable data remains untouched.

Using Immutable as an API Response Wrapper (REST API)

This ensures your API layer never mutates the response data accidentally.

Using Immutable Inside a DTO (Data Transfer Object)

DTOs are perfect for Immutable because they represent read‑only structured data.

This pattern guarantees that service layers cannot mutate DTO data, preserving integrity across the application.

Using Immutable to Normalize External Service Data (Microservices / Integrations)

Imagine receiving data from a microservice or external provider. Immutable ensures the structure is safe and predictable.

This pattern is extremely useful in microservices, queue consumers, event-driven systems, API gateways or domain boundaries. It prevents accidental mutation of external data.

🔌 Easy Integration

Immutable was designed to fit naturally into any PHP application architecture — from small scripts to full frameworks — without requiring adapters, service providers, or special configuration. Because it behaves like a read‑only data layer, it integrates seamlessly into DTOs, API responses, service layers, and domain logic.

To support predictable return types and stronger system expectations, Immutable provides an ImmutableInterface, allowing developers to type‑hint immutable structures throughout the application. This ensures consistent behavior and prevents accidental mutation at architectural boundaries.

Immutable also includes a dedicated factory method, Immutable::fromArray(), which normalizes any array into a fully immutable structure. For convenience, a global helper function immutable() is available, offering a concise and expressive way to create immutable data wherever needed.

🧠 Why Immutable?

PHP’s dynamic nature makes it easy to accidentally mutate data, especially when passing arrays through multiple layers of an application. A single unintended assignment can corrupt shared state, break assumptions, or introduce subtle bugs that are difficult to trace.

Immutable solves this by enforcing:

• predictability
• consistency
• safety
• clarity of intent

It is ideal for:

• configuration objects
• DTOs
• domain models
• API responses
• cached data
• value objects
• any scenario where data integrity matters

Design Goals

• Prevent accidental mutation at all levels
• Preserve the original structure exactly as provided
• Provide intuitive access to nested data
• Fail loudly and clearly on invalid operations
• Maintain strict separation between objects and lists
• Offer ergonomic chained access without sacrificing safety
• Avoid magic behaviors that hide errors or distort semantics

🤝 Contributions

Contributions are welcome. Feel free to open issues or submit pull requests.