docs: document entityModify()'s authoritative-identifier contract

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
2026-08-25 22:46:29 -04:00
parent b3e0c00c87
commit 964128e051
1 changed files with 8 additions and 1 deletions
@@ -56,12 +56,19 @@ interface ServiceEntityMutableInterface {
    /**
     * Modifies an existing entity
     *
+     * The returned entity's identifier is authoritative and may differ from
+     * the target identifier. Providers without in-place update support may
+     * implement this as an append-and-replace (or equivalent create-then-
+     * destroy) operation, in which case the target identifier is superseded
+     * and no longer resolvable; callers must persist the returned identifier
+     * rather than assume the target remains valid.
+     *
     * @since 2025.05.01
     *
     * @param EntityIdentifier $target Target entity identifier
     * @param MessagePropertiesMutableInterface $properties Entity properties to update
     *
-     * @return EntityBaseInterface Modified entity
+     * @return EntityBaseInterface Modified entity, with its own authoritative identifier
     */
    public function entityModify(EntityIdentifier $target, MessagePropertiesMutableInterface $properties): EntityBaseInterface;