Changes 6: Version class improvements and unit tests

src/Content/Version.php

@@ -2,7 +2,9 @@
 
 namespace Kirby\Content;
 
+use Kirby\Cms\Language;
 use Kirby\Cms\ModelWithContent;
+use Kirby\Exception\InvalidArgumentException;
 use Kirby\Exception\NotFoundException;
 
 /**
@@ -29,43 +31,52 @@ public function __construct(
 	/**
 	 * Returns a Content object for the given language
 	 */
-	public function content(string $language = 'default'): Content
+	public function content(Language|string $language = 'default'): Content
 	{
 		return new Content(
 			parent: $this->model,
-			data:   $this->model->storage()->read($this->id, $language),
+			data:   $this->model->storage()->read($this->id, $this->language($language)),
 		);
 	}
 
 	/**
-	 * Creates a new version for the given language
+	 * Provides simplified access to the absolute content file path.
+	 * This should stay an internal method and be removed as soon as
+	 * the dependency on file storage methods is resolved more clearly.
+	 *
+	 * @internal
 	 */
-	public function create(array $fields, string $language = 'default'): void
+	public function contentFile(Language|string $language = 'default'): string
 	{
-		$this->model->storage()->create($this->id, $language, $fields);
+		return $this->model->storage()->contentFile($this->id, $this->language($language));
 	}
 
 	/**
-	 * Deletes a version by language or for any language
+	 * Creates a new version for the given language
+	 * @todo Convert to a static method that creates the version initially with all relevant languages
+	 *
+	 * @param array<string, string> $fields Content fields
 	 */
-	public function delete(string|null $language = null): void
+	public function create(array $fields, Language|string $language = 'default'): void
 	{
-		// delete all languages
-		if ($language === null) {
-			foreach ($this->model->kirby()->languages() as $language) {
-				$this->model->storage()->delete($this->id, $language->code());
-			}
-		}
+		$this->model->storage()->create($this->id, $this->language($language), $fields);
+	}
 
+	/**
+	 * Deletes a version with all its languages
+	 */
+	public function delete(): void
+	{
 		// delete the default language in single-language mode
 		if ($this->model->kirby()->multilang() === false) {
-			$this->model->storage()->delete($this->id, 'default');
+			$this->model->storage()->delete($this->id, $this->language('default'));
 			return;
 		}
 
-		// delete a single language
-		$this->model->storage()->delete($this->id, $language);
-
+		// delete all languages
+		foreach ($this->model->kirby()->languages() as $language) {
+			$this->model->storage()->delete($this->id, $language);
+		}
 	}
 
 	/**
@@ -75,19 +86,26 @@ public function delete(string|null $language = null): void
 	 * @throws \Kirby\Exception\NotFoundException if the version does not exist
 	 */
 	public function ensure(
-		string $language = 'default'
+		Language|string $language = 'default'
 	): void {
-		if ($this->exists($language) !== true) {
-			throw new NotFoundException('Version "' . $this->id . ' (' . $language . ')" does not already exist');
+		if ($this->exists($language) === true) {
+			return;
 		}
+
+		$message = match($this->model->kirby()->multilang()) {
+			true  => 'Version "' . $this->id . ' (' . $language . ')" does not already exist',
+			false => 'Version "' . $this->id . '" does not already exist',
+		};
+
+		throw new NotFoundException($message);
 	}
 
 	/**
 	 * Checks if a version exists for the given language
 	 */
-	public function exists(string $language = 'default'): bool
+	public function exists(Language|string $language = 'default'): bool
 	{
-		return $this->model->storage()->exists($this->id, $language);
+		return $this->model->storage()->exists($this->id, $this->language($language));
 	}
 
 	/**
@@ -98,6 +116,33 @@ public function id(): VersionId
 		return $this->id;
 	}
 
+	/**
+	 * Converts a "user-facing" language code or Language object
+	 * to a `Language` object to be used in storage methods
+	 *
+	 * @throws \Kirby\Exception\InvalidArgumentException if the language code does not match a valid language
+	 */
+	protected function language(
+		Language|string|null $languageCode = null,
+	): Language {
+		if ($languageCode instanceof Language) {
+			return $languageCode;
+		}
+
+		// single language
+		if ($this->model->kirby()->multilang() === false) {
+			return Language::single();
+		}
+
+		// look up the actual language object if possible
+		if ($language = $this->model->kirby()->language($languageCode)) {
+			return $language;
+		}
+
+		// validate the language code
+		throw new InvalidArgumentException('Invalid language: ' . $languageCode);
+	}
+
 	/**
 	 * Returns the parent model
 	 */
@@ -109,77 +154,70 @@ public function model(): ModelWithContent
 	/**
 	 * Returns the modification timestamp of a version
 	 * if it exists
-	 *
-	 * @param string $lang Code `'default'` in a single-lang installation
 	 */
 	public function modified(
-		string $language = 'default'
+		Language|string $language = 'default'
 	): int|null {
-		$this->ensure($language);
-		return $this->model->storage()->modified($this->id, $language);
+		if ($this->exists($language) === true) {
+			return $this->model->storage()->modified($this->id, $this->language($language));
+		}
+
+		return null;
 	}
 
 	/**
 	 * Moves the version to a new language and/or version
+	 *
+	 * @throws \Kirby\Exception\NotFoundException If the version does not exist
 	 */
-	public function move(string $fromLanguage, VersionId $toVersionId, string $toLanguage): void
-	{
+	public function move(
+		Language|string $fromLanguage,
+		VersionId $toVersionId,
+		Language|string $toLanguage
+	): void {
 		$this->ensure($fromLanguage);
-		$this->model->storage()->move($this->id, $fromLanguage, $toVersionId, $toLanguage);
+		$this->model->storage()->move(
+			fromVersionId: $this->id,
+			fromLanguage: $this->language($fromLanguage),
+			toVersionId: $toVersionId,
+			toLanguage: $this->language($toLanguage)
+		);
 	}
 
 	/**
 	 * Returns the stored content fields
 	 *
-	 * @param string $lang Code `'default'` in a single-lang installation
 	 * @return array<string, string>
+	 *
+	 * @throws \Kirby\Exception\NotFoundException If the version does not exist
 	 */
-	public function read(string $language = 'default'): array
+	public function read(Language|string $language = 'default'): array
 	{
 		$this->ensure($language);
-		return $this->model->storage()->read($this->id, $language);
+		return $this->model->storage()->read($this->id, $this->language($language));
 	}
 
 	/**
 	 * Updates the modification timestamp of an existing version
 	 *
-	 * @param string $lang Code `'default'` in a single-lang installation
-	 *
 	 * @throws \Kirby\Exception\NotFoundException If the version does not exist
 	 */
-	public function touch(string|null $language = null): void
+	public function touch(Language|string $language = 'default'): void
 	{
-		// touch all languages
-		if ($language === null) {
-			foreach ($this->model->kirby()->languages() as $language) {
-				$this->touch($language->code());
-			}
-		}
-
-		// make sure the version exists
 		$this->ensure($language);
-
-		// touch the default language in single-language mode
-		if ($this->model->kirby()->multilang() === false) {
-			$this->model->storage()->touch($this->id, 'default');
-			return;
-		}
-
-		// touch a single language
-		$this->model->storage()->touch($this->id, $language);
+		$this->model->storage()->touch($this->id, $this->language($language));
 	}
 
 	/**
 	 * Updates the content fields of an existing version
 	 *
 	 * @param array<string, string> $fields Content fields
-	 * @param string $lang Code `'default'` in a single-lang installation
 	 *
 	 * @throws \Kirby\Exception\NotFoundException If the version does not exist
 	 */
-	public function update(array $fields, string $language = 'default'): void
+	public function update(array $fields, Language|string $language = 'default'): void
 	{
 		$this->ensure($language);
-		$this->model->storage()->update($this->id, $language, $fields);
+		$this->model->storage()->update($this->id, $this->language($language), $fields);
 	}
 }