Ensuring altering field methods clone object

Author: distantnative

Diff for: src/Content/Field.php

@@ -121,27 +121,27 @@ public function callback(Closure $callback): mixed
 	 * templates without the risk of XSS attacks
 	 *
 	 * @param string $context Location of output (`html`, `attr`, `js`, `css`, `url` or `xml`)
-	 * @return $this
 	 */
 	public function escape(string $context = 'html'): static
 	{
-		$this->value = Str::esc($this->value ?? '', $context);
-		return $this;
+		return $this->value(fn ($value) => Str::esc($value ?? '', $context));
 	}
 
 	/**
 	 * Creates an excerpt of the field value without html
 	 * or any other formatting.
-	 * @return $this
 	 */
 	public function excerpt(
 		int $chars = 0,
 		bool $strip = true,
 		string $rep = ' …'
 	): static {
-		$value       = $this->kirbytext()->value();
-		$this->value = Str::excerpt($value, $chars, $strip, $rep);
-		return $this;
+		return $this->value(Str::excerpt(
+			string: $this->kirbytext()->value(),
+			chars:  $chars,
+			strip:  $strip,
+			rep:    $rep
+		));
 	}
 
 	/**
@@ -154,20 +154,17 @@ public function exists(): bool
 
 	/**
 	 * Converts the field content to valid HTML
-	 * @return $this
 	 */
 	public function html(): static
 	{
-		$this->value = Html::encode($this->value);
-		return $this;
+		return $this->value(fn ($value) => Html::encode($value));
 	}
 
 	/**
 	 * Strips all block-level HTML elements from the field value,
 	 * it can be safely placed inside of other inline elements
 	 * without the risk of breaking the HTML structure.
 	 * @since 3.3.0
-	 * @return $this
 	 */
 	public function inline(): static
 	{
@@ -176,8 +173,9 @@ public function inline(): static
 		// Obsolete elements, script tags, image maps and form elements have
 		// been excluded for safety reasons and as they are most likely not
 		// needed in most cases.
-		$this->value = strip_tags($this->value ?? '', Html::$inlineList);
-		return $this;
+		return $this->value(
+			fn ($value) => strip_tags($value ?? '', Html::$inlineList)
+		);
 	}
 
 	/**
@@ -249,44 +247,37 @@ public function kirby(): App
 
 	/**
 	 * Parses all KirbyTags without also parsing Markdown
-	 * @return $this
 	 */
 	public function kirbytags(): static
 	{
-		$this->value = $this->kirby()->kirbytags(
-			text: $this->value,
+		return $this->value(fn ($value, $field) => $field->kirby()->kirbytags(
+			text: $value,
 			data: [
-				'parent' => $this->parent(),
-				'field'  => $this
+				'parent' => $field->parent(),
+				'field'  => $field
 			]
-		);
-
-		return $this;
+		));
 	}
 
 	/**
 	 * Converts the field content from Markdown/Kirbytext to valid HTML
-	 * @return $this
 	 */
 	public function kirbytext(array $options = []): static
 	{
-		$this->value = $this->kirby()->kirbytext(
-			text:    $this->value,
+		return $this->value(fn ($value, $field) => $field->kirby()->kirbytext(
+			text:    $value,
 			options: [
 				...$options,
-				'parent' => $this->parent(),
-				'field'  => $this
+				'parent' => $field->parent(),
+				'field'  => $field
 			]
-		);
-
-		return $this;
+		));
 	}
 
 	/**
 	 * Converts the field content from inline Markdown/Kirbytext
 	 * to valid HTML
 	 * @since 3.1.0
-	 * @return $this
 	 */
 	public function kirbytextInline(array $options = []): static
 	{
@@ -305,25 +296,21 @@ public function length(): int
 
 	/**
 	 * Converts the field content to lowercase
-	 * @return $this
 	 */
 	public function lower(): static
 	{
-		$this->value = Str::lower($this->value);
-		return $this;
+		return $this->value(fn ($value) => Str::lower($value));
 	}
 
 	/**
 	 * Converts markdown to valid HTML
-	 * @return $this
 	 */
 	public function markdown(array $options = []): static
 	{
-		$this->value = $this->kirby()->markdown(
-			text:    $this->value,
+		return $this->value(fn ($value) => $this->kirby()->markdown(
+			text:    $value,
 			options: $options
-		);
-		return $this;
+		));
 	}
 
 	/**
@@ -337,12 +324,10 @@ public function model(): ModelWithContent|null
 	/**
 	 * Converts all line breaks in the field content to `<br>` tags.
 	 * @since 3.3.0
-	 * @return $this
 	 */
 	public function nl2br(): static
 	{
-		$this->value = nl2br($this->value ?? '', false);
-		return $this;
+		return $this->value(fn ($value) => nl2br($value ?? '', false));
 	}
 
 	/**
@@ -360,9 +345,7 @@ public function or(mixed $fallback = null): static
 			return $fallback;
 		}
 
-		$field = clone $this;
-		$field->value = $fallback;
-		return $field;
+		return $this->value($fallback);
 	}
 
 	/**
@@ -381,13 +364,13 @@ public function parent(): ModelWithContent|null
 	 * This method is still experimental! You can use
 	 * it to solve potential problems with permalinks
 	 * already, but it might change in the future.
-	 *
-	 * @return $this
 	 */
 	public function permalinksToUrls(): static
 	{
-		if ($this->isNotEmpty() === true) {
-			$dom        = new Dom($this->value);
+		$field = clone $this;
+
+		if ($field->isNotEmpty() === true) {
+			$dom        = new Dom($field->value);
 			$attributes = ['href', 'src'];
 			$elements   = $dom->query('//*[' . implode(' | ', A::map($attributes, fn ($attribute) => '@' . $attribute)) . ']');
 
@@ -405,10 +388,10 @@ public function permalinksToUrls(): static
 				}
 			}
 
-			$this->value = $dom->toString();
+			$field->value = $dom->toString();
 		}
 
-		return $this;
+		return $field;
 	}
 
 	/**
@@ -432,7 +415,6 @@ public function query(
 	 * It parses any queries found in the field value.
 	 *
 	 * @param string|null $fallback Fallback for tokens in the template that cannot be replaced (`null` to keep the original token)
-	 * @return $this
 	 */
 	public function replace(
 		array $data = [],
@@ -441,20 +423,23 @@ public function replace(
 		if ($parent = $this->parent()) {
 			// Never pass `null` as the $template
 			// to avoid the fallback to the model ID
-			$this->value = $parent->toString(
-				$this->value ?? '',
+			return $this->value(fn ($value) => $parent->toString(
+				$value ?? '',
 				$data,
 				$fallback
-			);
-		} else {
-			$this->value = Str::template($this->value, array_replace([
-				'kirby' => $app = $this->kirby(),
-				'site'  => $app->site(),
-				'page'  => $app->page()
-			], $data), ['fallback' => $fallback]);
+			));
 		}
 
-		return $this;
+		return $this->value(fn ($value) => Str::template(
+			$value,
+			[
+				'kirby' => $app = $this->kirby(),
+				'site'  => $app->site(),
+				'page'  => $app->page(),
+				...$data
+			],
+			['fallback' => $fallback]
+		));
 	}
 
 	/**
@@ -463,34 +448,30 @@ public function replace(
 	 *
 	 * @param int $length The number of characters in the string
 	 * @param string $appendix An optional replacement for the missing rest
-	 * @return $this
 	 */
 	public function short(
 		int $length,
 		string $appendix = '…'
 	): static {
-		$this->value = Str::short($this->value, $length, $appendix);
-		return $this;
+		return $this->value(
+			fn ($value) => Str::short($value, $length, $appendix)
+		);
 	}
 
 	/**
 	 * Converts the field content to a slug
-	 * @return $this
 	 */
 	public function slug(): static
 	{
-		$this->value = Str::slug($this->value);
-		return $this;
+		return $this->value(fn ($value) => Str::slug($value));
 	}
 
 	/**
 	 * Applies SmartyPants to the field
-	 * @return $this
 	 */
 	public function smartypants(): static
 	{
-		$this->value = $this->kirby()->smartypants($this->value);
-		return $this;
+		return $this->value(fn ($value) => $this->kirby()->smartypants($value));
 	}
 
 	/**
@@ -801,12 +782,10 @@ public function toUsers(string $separator = 'yaml'): Users
 
 	/**
 	 * Converts the field content to uppercase
-	 * @return $this
 	 */
 	public function upper(): static
 	{
-		$this->value = Str::upper($this->value);
-		return $this;
+		return $this->value(fn ($value) => Str::upper($value));
 	}
 
 	/**
@@ -820,11 +799,12 @@ public function value(string|Closure|null $value = null): mixed
 			return $this->value;
 		}
 
+		$clone = clone $this;
+
 		if ($value instanceof Closure) {
-			$value = $value->call($this, $this->value);
+			$value = $value->call($this, $this->value, $clone);
 		}
 
-		$clone = clone $this;
 		$clone->value = (string)$value;
 
 		return $clone;
@@ -833,12 +813,10 @@ public function value(string|Closure|null $value = null): mixed
 	/**
 	 * Avoids typographical widows in strings by replacing
 	 * the last space with `&nbsp;`
-	 * @return $this
 	 */
 	public function widont(): static
 	{
-		$this->value = Str::widont($this->value);
-		return $this;
+		return $this->value(fn ($value) => Str::widont($value));
 	}
 
 	/**
@@ -851,12 +829,10 @@ public function words(): int
 
 	/**
 	 * Converts the field content to valid XML
-	 * @return $this
 	 */
 	public function xml(): static
 	{
-		$this->value = Xml::encode($this->value);
-		return $this;
+		return $this->value(fn ($value) => Xml::encode($value));
 	}
 
 	/**