Mergable Object Interface

[tdashton]

I have a RFC / question regarding a concept that we've introduced during the Profiles Editor project - merging two domain level objects together. Currently I do this in custom logic / a service, however it occurred to me this could be something that would be useful in general in our projects.

I was wondering if we have, or have thought of adding an interface in our libraries that we can use to indicate an object is mergable?

Example:

interface Mergable {
    public function merge(Mergable ...$object);
}

$object1->merge($object2, ...);

You may say - but this is exactly what the following code would do too:

array_merge($object1->toArray(), $object2->toArray());

This is usually correct, but consider the use case below:

In updating the profile's content via the endpoint and a PATCH request we now effectively offer a way to merge objects together while preserving existing keys in the target object, essentially like a array merge but with a bit more logic involved. This allows us to merge incomplete HTTP endpoint object content on top of another object while preserving the existing object's data if it wasn't explicitly patched from the endpoint.

Merging the resulting php arrays / objects generated from these two things

{
    "PROFILE_OVERVIEW_COMPANY_FACTS_V2": {
        "revenue": "Kununu Content V2 k.A. Ralb",
        "history": {
            "revenue": {
                "created_at": "2026-02-05T14:22:22+00:00",
                "created_by": "5dbb743f-0000-4057-8806-ec88a9fc809d",
                "updated_at": "2026-02-05T14:31:45+00:00",
                "updated_by": "5dbb743f-0000-4057-8806-ec88a9fc809d"
            }
        }
    }
}

on top of this:

{
    "PROFILE_OVERVIEW_COMPANY_FACTS_V2": {
        "numberOfEmployees": "120 vMbX",
        "history": {
            "numberOfEmployees": {
                "created_at": "2026-02-05T14:22:22+00:00",
                "created_by": "5dbb743f-0000-4057-8806-ec88a9fc809d",
                "updated_at": "2026-02-05T14:32:02+00:00",
                "updated_by": "5dbb743f-0000-4057-8806-ec88a9fc809d"
            }
        }
    }
}

results in:

{
    "PROFILE_OVERVIEW_COMPANY_FACTS_V2": {
        "revenue": "Kununu Content V2 k.A. Ralb",
        "numberOfEmployees": "120 vMbX",
        "history": {
            "revenue": {
                "created_at": "2026-02-05T14:22:22+00:00",
                "created_by": "5dbb743f-0000-4057-8806-ec88a9fc809d",
                "updated_at": "2026-02-05T14:31:45+00:00",
                "updated_by": "5dbb743f-0000-4057-8806-ec88a9fc809d"
            },
            "numberOfEmployees": {
                "created_at": "2026-02-05T14:22:22+00:00",
                "created_by": "5dbb743f-0000-4057-8806-ec88a9fc809d",
                "updated_at": "2026-02-05T14:32:02+00:00",
                "updated_by": "5dbb743f-0000-4057-8806-ec88a9fc809d"
            }
        }
    }
}

Essentially it's a array merge at its core but with some caveats:

1. Merging the history - for example when we merge history together we don't want to ever update the "created_by / created_at" if it is already set.
2. Also we may not want to overwrite existing data with null or otherwise empty values in the original object with empty values from the replacement).

The intention here is to allow encapsulation of logic which is applicable to specific objects when we want to combine them together in an array_merge like way. It would allow us to define custom ways in which objects can be combined. Like above, or for example merging entities together, while always preserving a primary key for example.

This is a RFC give me feedback if this would be useful or if it's too specific for my current use case and I should just keep it as domain logic 😄