matthiasnoback / convenient-immutability

Make objects initially inconsistent, yet eventually immutable

Convenient immutability for (some) PHP objects

Warning: I didn't use this library "in the wild" - please let me know if it works in your situation

Installation

Just run:

composer require matthiasnoback/convenient-immutability

Introduction

I've often encountered the following situation (in particular when working with command objects).

1. I start with a simple object (in fact, a DTO), with just some public properties.
2. The Symfony Form component copies some values into the object's properties.
3. I copy some extra data into the object (like a generated UUID).
4. I then use that object as a command or query message, handing it over to some inner layer of my application.

In other words, I have a class that looks like this:

class OrderSeats
{
    public $id;
    public $userId;
    public $seatNumbers = [];
}

And use it like this:

$form = $this->factory->create(OrderSeatsFormType::class);
$form->submit($request);
$command = $form->getData();
$command->id = Uuid::uuid4();

$commandBus->handle($command);

Then I want it to be impossible to change any field on the (command) object, making it effectively immutable.

The ConvenientImmutability\Immutable trait solves this problem. When your class uses this trait, it:

• Allows form components and the likes to put anything in your object in any particular order they like.
• Allows you to get the data from it by simply accessing its (public) variables.
• Doesn't allow anyone to overwrite previously set data.

Why would you do this?

• To feel less insecure about using public properties for your desirably immutable objects.
• To prevent accidental writes to objects you assumed were immutable.

What's the problem with this approach?

• Your objects may be immutable...
• but they can still exist in an inconsistent state.

Is this bad? I don't think so. As long as you validate the objects (e.g. using the Symfony Validator) and then throw them into your domain layer, which contains the actual safeguards against inconsistent state.

(You can also just use public properties and treat them as "set once, never again" in other parts of your application.)

License

The MIT License (MIT). Please see License File for more information.

convenient-immutability's Issues

Not compatible with typed properties in PHP 7.4

e.g.
class MyEvent:

{
    use Immutable;
    public int $number;
}

Calling
new MyEvent();

will throw an Exception:

Typed property MyEvent::$number must not be accessed before initialization
in vendor/matthiasnoback/convenient-immutability/src/Immutable.php (line 28) 
    $this->_defaultValues[$propertyName] = $property->getValue($this);

Can be easily fixed by changing the line to:

            if ($property->isInitialized($this)) {
                $this->_defaultValues[$propertyName] = $property->getValue($this);
            }

Return type of the factory doesn't match passed in object type

As it currently stands, the factory will wrap the passed in object in an Immutable wrapper. While that is efficient for simplified scenarios, it will break pretty much anywhere the type system is involved.

In addition to that, no guarantees are provided for the internal state when calling any method on the object: can probably improve that too, later on.

Form integration test failure

Don't understand why CI does not fail. This is TransformationFailedException in form because of integer values in choices.

There was 1 failure:

1. ConvenientImmutability\Test\FormIntegrationTest::it_works_with_a_standard_use_case_for_command_objects
   Failed asserting that two objects are equal.
   --- Expected
   +++ Actual
   @@ @@
   ConvenientImmutability\Test\Resources\OrderSeats Object (
   '_defaultValues' => Array (...)
   '_userDefinedValues' => Array (
   'id' => Ramsey\Uuid\Uuid Object (...)
   'userId' => 1

•    'seatNumbers' => Array (...)
  

  )
  '_userDefinedProperties' => Array (...)
  )

/home/dzubchik/tmp/dz-c/test/FormIntegrationTest.php:30

FAILURES!
Tests: 8, Assertions: 11, Failures: 1.

It should be possible to use default data with Symfony forms

Not sure if that's possible.

Deserialization behaviour

First of all thank you for this useful package. We began to use it in out project but faced with a problem during object deserialization. Did you think about using this package in cases with serialization?