From 964128e05179742072e56d422aaaec423f6e3caa Mon Sep 17 00:00:00 2001 From: Sebastian Krupinski Date: Tue, 25 Aug 2026 22:46:29 -0400 Subject: [PATCH] docs: document entityModify()'s authoritative-identifier contract Signed-off-by: Sebastian Krupinski --- .../lib/Mail/Service/ServiceEntityMutableInterface.php | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/shared/lib/Mail/Service/ServiceEntityMutableInterface.php b/shared/lib/Mail/Service/ServiceEntityMutableInterface.php index 238bdb2..0984ba0 100644 --- a/shared/lib/Mail/Service/ServiceEntityMutableInterface.php +++ b/shared/lib/Mail/Service/ServiceEntityMutableInterface.php @@ -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;