PHPackages                             lisachenko/immutable-object - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. lisachenko/immutable-object

ActiveLibrary

lisachenko/immutable-object
===========================

Immutable object library

0.5.0(6y ago)97293[1 issues](https://github.com/lisachenko/immutable-object/issues)[2 PRs](https://github.com/lisachenko/immutable-object/pulls)MITPHP

Since May 2Pushed 4y ago7 watchersCompare

[ Source](https://github.com/lisachenko/immutable-object)[ Packagist](https://packagist.org/packages/lisachenko/immutable-object)[ RSS](/packages/lisachenko-immutable-object/feed)WikiDiscussions master Synced 3d ago

READMEChangelog (1)Dependencies (2)Versions (5)Used By (0)

Immutable objects in PHP
------------------------

[](#immutable-objects-in-php)

This library provides native immutable objects for PHP>=7.4.2

[![Build Status](https://camo.githubusercontent.com/0141597ae8cac4872997d2817fb973f1322e5d04fba4ab4f98b69bd69846ffdc/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f636f6d2f6c6973616368656e6b6f2f696d6d757461626c652d6f626a6563742f6d6173746572)](https://travis-ci.org/lisachenko/immutable-object)[![GitHub release](https://camo.githubusercontent.com/d7d588d2c45b59dcc5c807141e60a7964ac19950a59489496235f00e91ed9165/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f6c6973616368656e6b6f2f696d6d757461626c652d6f626a6563742e737667)](https://github.com/lisachenko/immutable-object/releases/latest)[![Minimum PHP Version](https://camo.githubusercontent.com/92fabb75236db7d7453db0680cfab230e4ba78cc321ad3864794f78327f3f3b0/687474703a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344253230372e342d3838393242462e737667)](https://php.net/)[![License](https://camo.githubusercontent.com/dd0d39beae9cd4a8a6ce9ed373880bb63604249d3915288ca431be6320933beb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6c6973616368656e6b6f2f696d6d757461626c652d6f626a6563742e737667)](https://packagist.org/packages/lisachenko/immutable-object)

Rationale
---------

[](#rationale)

How many times have you thought it would be nice to have immutable objects in PHP? How many errors could be avoided if the objects could warn about attempts to change them outside the constructor? Unfortunately, [Immutability RFC](https://wiki.php.net/rfc/immutability) has never been implemented.

What to do? Of course, there is [psalm-immutable](https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-immutable)annotation which can help us find errors when running static analysis. But during the development of the code itself, we will not see any errors when trying to change a property in such an object.

However, with the advent of [FFI](https://www.php.net/manual/en/book.ffi.php) and the [Z-Engine](https://github.com/lisachenko/z-engine) library, it became possible to use PHP to expand the capabilities of the PHP itself.

Pre-requisites and initialization
---------------------------------

[](#pre-requisites-and-initialization)

As this library depends on `FFI`, it requires PHP>=7.4 and `FFI` extension to be enabled.

To install this library, simply add it via `composer`:

```
composer require lisachenko/immutable-object
```

To enable immutability, you should activate `FFI` bindings for PHP first by initializing the `Z-Engine` library with short call to the `Core::init()`. And you also need to activate immutability handler for development mode (or do not call it for production mode to follow Design-by-Contract logic and optimize performance and stability of application)

```
use Immutable\ImmutableHandler;
use ZEngine\Core;

include __DIR__.'/vendor/autoload.php';

Core::init();
ImmutableHandler::install();
```

Probably, `Z-Engine` will provide an automatic self-registration later, but for now it's ok to perform initialization manually.

Applying immutability
---------------------

[](#applying-immutability)

In order to make your object immutable, you just need to implement the `ImmutableInterface` interface marker in your class and this library automatically convert this class to immutable. Please note, that this interface should be added to every class (it isn't guaranteed that it will work child with parent classes that was declared as immutable)

Now you can test it with following example:

```