DDC-3640: Force version increment via mapped property #4472

New Issue

admin · 2026-01-22T14:42:22+01:00

admin commented

2026-01-22 14:42:22 +01:00

Originally created by @doctrinebot on GitHub (Mar 26, 2015).

Originally assigned to: @beberlei on GitHub.

Jira issue originally created by user dhager:

Existing feature:

It is currently possible to use optimist-locking against an entity through a version code or timestamp, which becomes incremented when the entity changes. Unfortunately, there is no way for an entity to signal that its version should be incremented when no (direct) changes have occurred.

Problem:

Sometimes you want to control or gate wide-spread or indirect changes via a particular entity, such as the root of a tree of other mutable entities. This is particularly common in Domain Driven Design.

Proposal:

Create a new configuration option for a PHP property that identifies it as a "version incrementor flag". It is only legal on entities that also have a version-field. This field will always be set to false when an entity is hydrated.

When entities are being checked for changes and flushed, this flag will (if it evaluates to true) force the version-field to update. Note that if the entity has "real changes", it will be saved and the version-field will update regardless. At the end of this process, the field is reset back to false.

This allows the user to write code such as:


    /*** @Version @Column(type="integer") **/
    private $version;

    /*** @VersionIncrementFlag **/
    $changed = false;

    /*** @OneToMany(targetEntity="Child", mappedBy="parent") **/
    private $children;    

    public function zeroChildren(){
        foreach($this->children as $child){
            $child->setValue(0);
        }
        $this->changed = true; // Where $changed is the incrementor flag
    }

Issues with other approaches:

The current workaround of a "junk column" is... suboptimal. It requires a junk data column in the database, and its presence does not easily capture the intent of the user. It also leads to extra database operations, since the junk data has to be saved no matter what.

Adding a specialized method to EntityManager, like with $em->touchVersion($entity); is also problematic, since it means you cannot conveniently trigger the new behavior when deep inside the object-graph.

Originally created by @doctrinebot on GitHub (Mar 26, 2015). Originally assigned to: @beberlei on GitHub. Jira issue originally created by user dhager: ## Existing feature: It is currently possible to use optimist-locking against an entity through a version code or timestamp, which becomes incremented when the entity changes. Unfortunately, there is no way for an entity to signal that its version should be incremented when no (direct) changes have occurred. ## Problem: Sometimes you want to control or gate wide-spread or indirect changes via a particular entity, such as the root of a tree of other mutable entities. This is particularly common in Domain Driven Design. ## Proposal: Create a new configuration option for a PHP property that identifies it as a "version incrementor flag". It is only legal on entities that also have a version-field. This field will always be set to false when an entity is hydrated. When entities are being checked for changes and flushed, this flag will (if it evaluates to true) force the version-field to update. Note that if the entity has "real changes", it will be saved and the version-field will update regardless. At the end of this process, the field is reset back to false. This allows the user to write code such as: ``` /*** @Version @Column(type="integer") **/ private $version; /*** @VersionIncrementFlag **/ $changed = false; /*** @OneToMany(targetEntity="Child", mappedBy="parent") **/ private $children; public function zeroChildren(){ foreach($this->children as $child){ $child->setValue(0); } $this->changed = true; // Where $changed is the incrementor flag } ``` ## Issues with other approaches: The current workaround of a "junk column" is... suboptimal. It requires a junk data column in the database, and its presence does not easily capture the intent of the user. It also leads to extra database operations, since the junk data has to be saved no matter what. Adding a specialized method to EntityManager, like with `$em->touchVersion($entity);` is also problematic, since it means you cannot conveniently trigger the new behavior when deep inside the object-graph.

admin added the Improvement label 2026-01-22 14:42:22 +01:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: doctrine/archived-orm#4472