downgrade to kirby v3

kirby/src/Cms/File.php

@@ -2,12 +2,10 @@
 
 namespace Kirby\Cms;
 
-use Exception;
-use IntlDateFormatter;
-use Kirby\Exception\InvalidArgumentException;
 use Kirby\Filesystem\F;
 use Kirby\Filesystem\IsFile;
 use Kirby\Panel\File as Panel;
+use Kirby\Toolkit\A;
 use Kirby\Toolkit\Str;
 
 /**
@@ -41,64 +39,64 @@ class File extends ModelWithContent
 	public const CLASS_ALIAS = 'file';
 
 	/**
-	 * All registered file methods
-	 * @todo Remove when support for PHP 8.2 is dropped
+	 * Cache for the initialized blueprint object
+	 *
+	 * @var \Kirby\Cms\FileBlueprint
 	 */
-	public static array $methods = [];
+	protected $blueprint;
 
 	/**
-	 * Cache for the initialized blueprint object
+	 * @var string
 	 */
-	protected FileBlueprint|null $blueprint = null;
+	protected $filename;
 
-	protected string $filename;
+	/**
+	 * @var string
+	 */
+	protected $id;
 
-	protected string $id;
+	/**
+	 * All registered file methods
+	 *
+	 * @var array
+	 */
+	public static $methods = [];
 
 	/**
 	 * The parent object
+	 *
+	 * @var \Kirby\Cms\Model
 	 */
-	protected Page|Site|User|null $parent = null;
+	protected $parent;
 
 	/**
 	 * The absolute path to the file
+	 *
+	 * @var string|null
 	 */
-	protected string|null $root;
+	protected $root;
 
-	protected string|null $template;
+	/**
+	 * @var string
+	 */
+	protected $template;
 
 	/**
 	 * The public file Url
+	 *
+	 * @var string
 	 */
-	protected string|null $url;
-
-	/**
-	 * Creates a new File object
-	 */
-	public function __construct(array $props)
-	{
-		parent::__construct($props);
-
-		if (isset($props['filename'], $props['parent']) === false) {
-			throw new InvalidArgumentException('The filename and parent are required');
-		}
-
-		$this->filename = $props['filename'];
-		$this->parent   = $props['parent'];
-		$this->template = $props['template'] ?? null;
-		// Always set the root to null, to invoke
-		// auto root detection
-		$this->root     = null;
-		$this->url      = $props['url'] ?? null;
-
-		$this->setBlueprint($props['blueprint'] ?? null);
-	}
+	protected $url;
 
 	/**
 	 * Magic caller for file methods
 	 * and content fields. (in this order)
+	 *
+	 * @param string $method
+	 * @param array $arguments
+	 * @return mixed
 	 */
-	public function __call(string $method, array $arguments = []): mixed
+	public function __call(string $method, array $arguments = [])
 	{
 		// public property access
 		if (isset($this->$method) === true) {
@@ -119,8 +117,25 @@ class File extends ModelWithContent
 		return $this->content()->get($method);
 	}
 
+	/**
+	 * Creates a new File object
+	 *
+	 * @param array $props
+	 */
+	public function __construct(array $props)
+	{
+		// set filename as the most important prop first
+		// TODO: refactor later to avoid redundant prop setting
+		$this->setProperty('filename', $props['filename'] ?? null, true);
+
+		// set other properties
+		$this->setProperties($props);
+	}
+
 	/**
 	 * Improved `var_dump` output
+	 *
+	 * @return array
 	 */
 	public function __debugInfo(): array
 	{
@@ -132,7 +147,10 @@ class File extends ModelWithContent
 
 	/**
 	 * Returns the url to api endpoint
+	 *
 	 * @internal
+	 * @param bool $relative
+	 * @return string
 	 */
 	public function apiUrl(bool $relative = false): string
 	{
@@ -141,144 +159,73 @@ class File extends ModelWithContent
 
 	/**
 	 * Returns the FileBlueprint object for the file
+	 *
+	 * @return \Kirby\Cms\FileBlueprint
 	 */
-	public function blueprint(): FileBlueprint
+	public function blueprint()
 	{
-		return $this->blueprint ??= FileBlueprint::factory(
-			'files/' . $this->template(),
-			'files/default',
-			$this
-		);
-	}
-
-	/**
-	 * Returns an array with all blueprints that are available for the file
-	 * by comparing files sections and files fields of the parent model
-	 */
-	public function blueprints(string $inSection = null): array
-	{
-		// get cached results for the current file model
-		// (except when collecting for a specific section)
-		if ($inSection === null && $this->blueprints !== null) {
-			return $this->blueprints; // @codeCoverageIgnore
+		if (is_a($this->blueprint, 'Kirby\Cms\FileBlueprint') === true) {
+			return $this->blueprint;
 		}
 
-		// always include the current template as option
-		$templates = [
-			$this->template() ?? 'default',
-			...$this->parent()->blueprint()->acceptedFileTemplates($inSection)
-		];
-
-		// make sure every template is only included once
-		$templates = array_unique(array_filter($templates));
-
-		// load the blueprint details for each collected template name
-		$blueprints = [];
-
-		foreach ($templates as $template) {
-			// default template doesn't need to exist as file
-			// to be included in the list
-			if ($template === 'default') {
-				$blueprints[$template] = [
-					'name'  => 'default',
-					'title' => '– (default)',
-				];
-				continue;
-			}
-
-			if ($blueprint = FileBlueprint::factory('files/' . $template, null, $this)) {
-				try {
-					// ensure that file matches `accept` option,
-					// if not remove template from available list
-					$this->match($blueprint->accept());
-
-					$blueprints[$template] = [
-						'name'  => $name = Str::after($blueprint->name(), '/'),
-						'title' => $blueprint->title() . ' (' . $name . ')',
-					];
-				} catch (Exception) {
-					// skip when `accept` doesn't match
-				}
-			}
-		}
-
-		$blueprints = array_values($blueprints);
-
-		// sort blueprints alphabetically while
-		// making sure the default blueprint is on top of list
-		usort($blueprints, fn ($a, $b) => match (true) {
-			$a['name'] === 'default' => -1,
-			$b['name'] === 'default' => 1,
-			default => strnatcmp($a['title'], $b['title'])
-		});
-
-		// no caching for when collecting for specific section
-		if ($inSection !== null) {
-			return $blueprints; // @codeCoverageIgnore
-		}
-
-		return $this->blueprints = $blueprints;
+		return $this->blueprint = FileBlueprint::factory('files/' . $this->template(), 'files/default', $this);
 	}
 
 	/**
 	 * Store the template in addition to the
 	 * other content.
+	 *
 	 * @internal
+	 * @param array $data
+	 * @param string|null $languageCode
+	 * @return array
 	 */
-	public function contentFileData(
-		array $data,
-		string $languageCode = null
-	): array {
-		// only add the template in, if the $data array
-		// doesn't explicitly unsets it
-		if (
-			array_key_exists('template', $data) === false &&
-			$template = $this->template()
-		) {
-			$data['template'] = $template;
-		}
-
-		return $data;
+	public function contentFileData(array $data, string $languageCode = null): array
+	{
+		return A::append($data, [
+			'template' => $this->template(),
+		]);
 	}
 
 	/**
 	 * Returns the directory in which
 	 * the content file is located
+	 *
 	 * @internal
-	 * @deprecated 4.0.0
-	 * @todo Remove in v5
-	 * @codeCoverageIgnore
+	 * @return string
 	 */
 	public function contentFileDirectory(): string
 	{
-		Helpers::deprecated('The internal $model->contentFileDirectory() method has been deprecated. Please let us know via a GitHub issue if you need this method and tell us your use case.', 'model-content-file');
 		return dirname($this->root());
 	}
 
 	/**
 	 * Filename for the content file
+	 *
 	 * @internal
-	 * @deprecated 4.0.0
-	 * @todo Remove in v5
-	 * @codeCoverageIgnore
+	 * @return string
 	 */
 	public function contentFileName(): string
 	{
-		Helpers::deprecated('The internal $model->contentFileName() method has been deprecated. Please let us know via a GitHub issue if you need this method and tell us your use case.', 'model-content-file');
 		return $this->filename();
 	}
 
 	/**
 	 * Constructs a File object
+	 *
 	 * @internal
+	 * @param mixed $props
+	 * @return static
 	 */
-	public static function factory(array $props): static
+	public static function factory($props)
 	{
 		return new static($props);
 	}
 
 	/**
 	 * Returns the filename with extension
+	 *
+	 * @return string
 	 */
 	public function filename(): string
 	{
@@ -287,14 +234,19 @@ class File extends ModelWithContent
 
 	/**
 	 * Returns the parent Files collection
+	 *
+	 * @return \Kirby\Cms\Files
 	 */
-	public function files(): Files
+	public function files()
 	{
 		return $this->siblingsCollection();
 	}
 
 	/**
 	 * Converts the file to html
+	 *
+	 * @param array $attr
+	 * @return string
 	 */
 	public function html(array $attr = []): string
 	{
@@ -306,91 +258,58 @@ class File extends ModelWithContent
 
 	/**
 	 * Returns the id
+	 *
+	 * @return string
 	 */
 	public function id(): string
 	{
-		if (
-			$this->parent() instanceof Page ||
-			$this->parent() instanceof User
-		) {
-			return $this->id ??= $this->parent()->id() . '/' . $this->filename();
+		if ($this->id !== null) {
+			return $this->id;
 		}
 
-		return $this->id ??= $this->filename();
+		if (is_a($this->parent(), 'Kirby\Cms\Page') === true) {
+			return $this->id = $this->parent()->id() . '/' . $this->filename();
+		} elseif (is_a($this->parent(), 'Kirby\Cms\User') === true) {
+			return $this->id = $this->parent()->id() . '/' . $this->filename();
+		}
+
+		return $this->id = $this->filename();
 	}
 
 	/**
 	 * Compares the current object with the given file object
+	 *
+	 * @param \Kirby\Cms\File $file
+	 * @return bool
 	 */
 	public function is(File $file): bool
 	{
 		return $this->id() === $file->id();
 	}
 
-	/**
-	 * Checks if the files is accessible.
-	 * This permission depends on the `read` option until v5
-	 */
-	public function isAccessible(): bool
-	{
-		// TODO: remove this check when `read` option deprecated in v5
-		if ($this->isReadable() === false) {
-			return false;
-		}
-
-		static $accessible = [];
-
-		if ($template = $this->template()) {
-			return $accessible[$template] ??= $this->permissions()->can('access');
-		}
-
-		return $accessible['__none__'] ??= $this->permissions()->can('access');
-	}
-
-	/**
-	 * Check if the file can be listable by the current user
-	 * This permission depends on the `read` option until v5
-	 */
-	public function isListable(): bool
-	{
-		// TODO: remove this check when `read` option deprecated in v5
-		if ($this->isReadable() === false) {
-			return false;
-		}
-
-		// not accessible also means not listable
-		if ($this->isAccessible() === false) {
-			return false;
-		}
-
-		static $listable = [];
-
-		if ($template = $this->template()) {
-			return $listable[$template] ??= $this->permissions()->can('list');
-		}
-
-		return $listable['__none__'] ??= $this->permissions()->can('list');
-	}
-
 	/**
 	 * Check if the file can be read by the current user
 	 *
-	 * @todo Deprecate `read` option in v5 and make the necessary changes for `access` and `list` options.
+	 * @return bool
 	 */
 	public function isReadable(): bool
 	{
 		static $readable = [];
 
-		if ($template = $this->template()) {
-			return $readable[$template] ??= $this->permissions()->can('read');
+		$template = $this->template();
+
+		if (isset($readable[$template]) === true) {
+			return $readable[$template];
 		}
 
-		return $readable['__none__'] ??= $this->permissions()->can('read');
+		return $readable[$template] = $this->permissions()->can('read');
 	}
 
 	/**
 	 * Creates a unique media hash
+	 *
 	 * @internal
+	 * @return string
 	 */
 	public function mediaHash(): string
 	{
@@ -399,7 +318,9 @@ class File extends ModelWithContent
 
 	/**
 	 * Returns the absolute path to the file in the public media folder
+	 *
 	 * @internal
+	 * @return string
 	 */
 	public function mediaRoot(): string
 	{
@@ -408,7 +329,9 @@ class File extends ModelWithContent
 
 	/**
 	 * Creates a non-guessable token string for this file
+	 *
 	 * @internal
+	 * @return string
 	 */
 	public function mediaToken(): string
 	{
@@ -418,7 +341,9 @@ class File extends ModelWithContent
 
 	/**
 	 * Returns the absolute Url to the file in the public media folder
+	 *
 	 * @internal
+	 * @return string
 	 */
 	public function mediaUrl(): string
 	{
@@ -428,16 +353,17 @@ class File extends ModelWithContent
 	/**
 	 * Get the file's last modification time.
 	 *
+	 * @param string|\IntlDateFormatter|null $format
 	 * @param string|null $handler date, intl or strftime
+	 * @param string|null $languageCode
+	 * @return mixed
 	 */
-	public function modified(
-		string|IntlDateFormatter|null $format = null,
-		string|null $handler = null,
-		string|null $languageCode = null
-	): string|int|false {
+	public function modified($format = null, string $handler = null, string $languageCode = null)
+	{
 		$file     = $this->modifiedFile();
 		$content  = $this->modifiedContent($languageCode);
 		$modified = max($file, $content);
+		$handler ??= $this->kirby()->option('date.handler', 'date');
 
 		return Str::date($modified, $format, $handler);
 	}
@@ -445,15 +371,20 @@ class File extends ModelWithContent
 	/**
 	 * Timestamp of the last modification
 	 * of the content file
+	 *
+	 * @param string|null $languageCode
+	 * @return int
 	 */
 	protected function modifiedContent(string $languageCode = null): int
 	{
-		return $this->storage()->modified('published', $languageCode) ?? 0;
+		return F::modified($this->contentFile($languageCode));
 	}
 
 	/**
 	 * Timestamp of the last modification
 	 * of the source file
+	 *
+	 * @return int
 	 */
 	protected function modifiedFile(): int
 	{
@@ -462,35 +393,39 @@ class File extends ModelWithContent
 
 	/**
 	 * Returns the parent Page object
+	 *
+	 * @return \Kirby\Cms\Page|null
 	 */
-	public function page(): Page|null
+	public function page()
 	{
-		if ($this->parent() instanceof Page) {
-			return $this->parent();
-		}
-
-		return null;
+		return is_a($this->parent(), 'Kirby\Cms\Page') === true ? $this->parent() : null;
 	}
 
 	/**
 	 * Returns the panel info object
+	 *
+	 * @return \Kirby\Panel\File
 	 */
-	public function panel(): Panel
+	public function panel()
 	{
 		return new Panel($this);
 	}
 
 	/**
-	 * Returns the parent object
+	 * Returns the parent Model object
+	 *
+	 * @return \Kirby\Cms\Model
 	 */
-	public function parent(): Page|Site|User
+	public function parent()
 	{
 		return $this->parent ??= $this->kirby()->site();
 	}
 
 	/**
 	 * Returns the parent id if a parent exists
+	 *
 	 * @internal
+	 * @return string
 	 */
 	public function parentId(): string
 	{
@@ -499,40 +434,34 @@ class File extends ModelWithContent
 
 	/**
 	 * Returns a collection of all parent pages
+	 *
+	 * @return \Kirby\Cms\Pages
 	 */
-	public function parents(): Pages
+	public function parents()
 	{
-		if ($this->parent() instanceof Page) {
-			return $this->parent()->parents()->prepend(
-				$this->parent()->id(),
-				$this->parent()
-			);
+		if (is_a($this->parent(), 'Kirby\Cms\Page') === true) {
+			return $this->parent()->parents()->prepend($this->parent()->id(), $this->parent());
 		}
 
 		return new Pages();
 	}
 
-	/**
-	 * Return the permanent URL to the file using its UUID
-	 * @since 3.8.0
-	 */
-	public function permalink(): string|null
-	{
-		return $this->uuid()?->url();
-	}
-
 	/**
 	 * Returns the permissions object for this file
+	 *
+	 * @return \Kirby\Cms\FilePermissions
 	 */
-	public function permissions(): FilePermissions
+	public function permissions()
 	{
 		return new FilePermissions($this);
 	}
 
 	/**
 	 * Returns the absolute root to the file
+	 *
+	 * @return string|null
 	 */
-	public function root(): string|null
+	public function root(): ?string
 	{
 		return $this->root ??= $this->parent()->root() . '/' . $this->filename();
 	}
@@ -540,8 +469,10 @@ class File extends ModelWithContent
 	/**
 	 * Returns the FileRules class to
 	 * validate any important action.
+	 *
+	 * @return \Kirby\Cms\FileRules
 	 */
-	protected function rules(): FileRules
+	protected function rules()
 	{
 		return new FileRules();
 	}
@@ -549,9 +480,10 @@ class File extends ModelWithContent
 	/**
 	 * Sets the Blueprint object
 	 *
+	 * @param array|null $blueprint
 	 * @return $this
 	 */
-	protected function setBlueprint(array $blueprint = null): static
+	protected function setBlueprint(array $blueprint = null)
 	{
 		if ($blueprint !== null) {
 			$blueprint['model'] = $this;
@@ -561,39 +493,103 @@ class File extends ModelWithContent
 		return $this;
 	}
 
+	/**
+	 * Sets the filename
+	 *
+	 * @param string $filename
+	 * @return $this
+	 */
+	protected function setFilename(string $filename)
+	{
+		$this->filename = $filename;
+		return $this;
+	}
+
+	/**
+	 * Sets the parent model object
+	 *
+	 * @param \Kirby\Cms\Model $parent
+	 * @return $this
+	 */
+	protected function setParent(Model $parent)
+	{
+		$this->parent = $parent;
+		return $this;
+	}
+
+	/**
+	 * Always set the root to null, to invoke
+	 * auto root detection
+	 *
+	 * @param string|null $root
+	 * @return $this
+	 */
+	protected function setRoot(string $root = null)
+	{
+		$this->root = null;
+		return $this;
+	}
+
+	/**
+	 * @param string|null $template
+	 * @return $this
+	 */
+	protected function setTemplate(string $template = null)
+	{
+		$this->template = $template;
+		return $this;
+	}
+
+	/**
+	 * Sets the url
+	 *
+	 * @param string|null $url
+	 * @return $this
+	 */
+	protected function setUrl(string $url = null)
+	{
+		$this->url = $url;
+		return $this;
+	}
+
 	/**
 	 * Returns the parent Files collection
 	 * @internal
+	 *
+	 * @return \Kirby\Cms\Files
 	 */
-	protected function siblingsCollection(): Files
+	protected function siblingsCollection()
 	{
 		return $this->parent()->files();
 	}
 
 	/**
 	 * Returns the parent Site object
+	 *
+	 * @return \Kirby\Cms\Site
 	 */
-	public function site(): Site
+	public function site()
 	{
-		if ($this->parent() instanceof Site) {
-			return $this->parent();
-		}
-
-		return $this->kirby()->site();
+		return is_a($this->parent(), 'Kirby\Cms\Site') === true ? $this->parent() : $this->kirby()->site();
 	}
 
 	/**
 	 * Returns the final template
+	 *
+	 * @return string|null
 	 */
-	public function template(): string|null
+	public function template(): ?string
 	{
 		return $this->template ??= $this->content()->get('template')->value();
 	}
 
 	/**
 	 * Returns siblings with the same template
+	 *
+	 * @param bool $self
+	 * @return \Kirby\Cms\Files
 	 */
-	public function templateSiblings(bool $self = true): Files
+	public function templateSiblings(bool $self = true)
 	{
 		return $this->siblings($self)->filter('template', $this->template());
 	}
@@ -602,27 +598,122 @@ class File extends ModelWithContent
 	 * Extended info for the array export
 	 * by injecting the information from
 	 * the asset.
+	 *
+	 * @return array
 	 */
 	public function toArray(): array
 	{
-		return array_merge(parent::toArray(), $this->asset()->toArray(), [
-			'id'       => $this->id(),
-			'template' => $this->template(),
-		]);
+		return array_merge($this->asset()->toArray(), parent::toArray());
 	}
 
 	/**
 	 * Returns the Url
+	 *
+	 * @return string
 	 */
 	public function url(): string
 	{
 		return $this->url ??= ($this->kirby()->component('file::url'))($this->kirby(), $this);
 	}
 
+
+	/**
+	 * Deprecated!
+	 */
+
+	/**
+	 * Provides a kirbytag or markdown
+	 * tag for the file, which will be
+	 * used in the panel, when the file
+	 * gets dragged onto a textarea
+	 *
+	 * @todo Remove in 3.8.0
+	 *
+	 * @internal
+	 * @param string|null $type (null|auto|kirbytext|markdown)
+	 * @param bool $absolute
+	 * @return string
+	 * @codeCoverageIgnore
+	 */
+	public function dragText(string $type = null, bool $absolute = false): string
+	{
+		Helpers::deprecated('Cms\File::dragText() has been deprecated and will be removed in Kirby 3.8.0. Use $file->panel()->dragText() instead.');
+		return $this->panel()->dragText($type, $absolute);
+	}
+
+	/**
+	 * Returns an array of all actions
+	 * that can be performed in the Panel
+	 *
+	 * @todo Remove in 3.8.0
+	 *
+	 * @since 3.3.0 This also checks for the lock status
+	 * @since 3.5.1 This also checks for matching accept settings
+	 *
+	 * @param array $unlock An array of options that will be force-unlocked
+	 * @return array
+	 * @codeCoverageIgnore
+	 */
+	public function panelOptions(array $unlock = []): array
+	{
+		Helpers::deprecated('Cms\File::panelOptions() has been deprecated and will be removed in Kirby 3.8.0. Use $file->panel()->options() instead.');
+		return $this->panel()->options($unlock);
+	}
+
+	/**
+	 * Returns the full path without leading slash
+	 *
+	 * @todo Remove in 3.8.0
+	 *
+	 * @internal
+	 * @return string
+	 * @codeCoverageIgnore
+	 */
+	public function panelPath(): string
+	{
+		Helpers::deprecated('Cms\File::panelPath() has been deprecated and will be removed in Kirby 3.8.0. Use $file->panel()->path() instead.');
+		return $this->panel()->path();
+	}
+
+	/**
+	 * Prepares the response data for file pickers
+	 * and file fields
+	 *
+	 * @todo Remove in 3.8.0
+	 *
+	 * @param array|null $params
+	 * @return array
+	 * @codeCoverageIgnore
+	 */
+	public function panelPickerData(array $params = []): array
+	{
+		Helpers::deprecated('Cms\File::panelPickerData() has been deprecated and will be removed in Kirby 3.8.0. Use $file->panel()->pickerData() instead.');
+		return $this->panel()->pickerData($params);
+	}
+
+	/**
+	 * Returns the url to the editing view
+	 * in the panel
+	 *
+	 * @todo Remove in 3.8.0
+	 *
+	 * @internal
+	 * @param bool $relative
+	 * @return string
+	 * @codeCoverageIgnore
+	 */
+	public function panelUrl(bool $relative = false): string
+	{
+		Helpers::deprecated('Cms\File::panelUrl() has been deprecated and will be removed in Kirby 3.8.0. Use $file->panel()->url() instead.');
+		return $this->panel()->url($relative);
+	}
+
 	/**
 	 * Simplified File URL that uses the parent
 	 * Page URL and the filename as a more stable
 	 * alternative for the media URLs.
+	 *
+	 * @return string
 	 */
 	public function previewUrl(): string
 	{