Merge pull request #59980 from nextcloud/jtr/docs-lock-LockContext-API

docs(lock): clarify LockContext docs and modernize implementation

Author: AndyScherzinger

lib/public/Files/Lock/LockContext.php

@@ -12,32 +12,25 @@
 use OCP\Files\Node;
 
 /**
- * Structure to identify a specific lock context to request or
- * describe a lock with the affected node and ownership information
+ * Value object describing the context in which a lock is requested or evaluated.
  *
- * This is used to match a lock/unlock request or file operation to existing locks
+ * A lock context identifies the affected node together with the lock owner type
+ * and owner identifier, so lock-aware operations can be matched against existing locks.
  *
  * @since 24.0.0
  */
 final class LockContext {
-	private Node $node;
-	private int $type;
-	private string $owner;
-
 	/**
-	 * @param Node $node Node that is owned by the lock
-	 * @param int $type Type of the lock owner
-	 * @param string $owner Unique identifier for the lock owner based on the type
+	 * @param Node $node Node the lock context applies to
+	 * @param ILock::TYPE_* $type Lock owner type
+	 * @param string $owner Owner identifier for the given type - e.g. a user id, app id, or lock token
 	 * @since 24.0.0
 	 */
 	public function __construct(
-		Node $node,
-		int $type,
-		string $owner,
+		private readonly Node $node,
+		private readonly int $type,
+		private readonly string $owner,
 	) {
-		$this->node = $node;
-		$this->type = $type;
-		$this->owner = $owner;
 	}
 
 	/**
@@ -48,35 +41,40 @@ public function getNode(): Node {
 	}
 
 	/**
-	 * @return int
+	 * Returns the lock owner type.
+	 *
+	 * @return ILock::TYPE_*
 	 * @since 24.0.0
 	 */
 	public function getType(): int {
 		return $this->type;
 	}
 
 	/**
-	 * @return string user id / app id / lock token depending on the type
+	 * Returns the owner identifier for the current lock type.
+	 *
+	 * For example, this may be a user id, app id, or lock token.
+	 *
 	 * @since 24.0.0
 	 */
 	public function getOwner(): string {
 		return $this->owner;
 	}
 
 	/**
+	 * Returns a human-readable representation for logging and debugging.
+	 *
+	 * Not guaranteed to be a stable machine-readable contract.
+	 *
 	 * @since 24.0.0
 	 */
 	public function __toString(): string {
-		$typeString = 'unknown';
-		if ($this->type === ILock::TYPE_USER) {
-			$typeString = 'ILock::TYPE_USER';
-		}
-		if ($this->type === ILock::TYPE_APP) {
-			$typeString = 'ILock::TYPE_APP';
-		}
-		if ($this->type === ILock::TYPE_TOKEN) {
-			$typeString = 'ILock::TYPE_TOKEN';
-		}
-		return "$typeString  $this->owner " . $this->getNode()->getId();
+		$typeString = match ($this->type) {
+			ILock::TYPE_USER => 'ILock::TYPE_USER',
+			ILock::TYPE_APP => 'ILock::TYPE_APP',
+			ILock::TYPE_TOKEN => 'ILock::TYPE_TOKEN',
+			default => 'unknown',
+		};
+		return sprintf('%s %s %d', $typeString, $this->owner, $this->node->getId());
 	}
 }