Upgrade to 3.8.0

kirby/src/Cms/Plugin.php

@@ -3,8 +3,10 @@
 namespace Kirby\Cms;
 
 use Exception;
+use Kirby\Cms\System\UpdateStatus;
 use Kirby\Data\Data;
 use Kirby\Exception\InvalidArgumentException;
+use Kirby\Toolkit\A;
 use Kirby\Toolkit\V;
 
 /**
@@ -20,15 +22,16 @@ use Kirby\Toolkit\V;
  */
 class Plugin extends Model
 {
-	protected $extends;
-	protected $info;
-	protected $name;
-	protected $root;
+	protected array $extends;
+	protected string $name;
+	protected string $root;
+
+	// caches
+	protected array|null $info = null;
+	protected UpdateStatus|null $updateStatus = null;
 
 	/**
-	 * @param string $key
-	 * @param array|null $arguments
-	 * @return mixed|null
+	 * Allows access to any composer.json field by method call
 	 */
 	public function __call(string $key, array $arguments = null)
 	{
@@ -36,10 +39,8 @@ class Plugin extends Model
 	}
 
 	/**
-	 * Plugin constructor
-	 *
-	 * @param string $name
-	 * @param array $extends
+	 * @param string $name Plugin name within Kirby (`vendor/plugin`)
+	 * @param array $extends Associative array of plugin extensions
 	 */
 	public function __construct(string $name, array $extends = [])
 	{
@@ -53,9 +54,7 @@ class Plugin extends Model
 
 	/**
 	 * Returns the array with author information
-	 * from the composer file
-	 *
-	 * @return array
+	 * from the composer.json file
 	 */
 	public function authors(): array
 	{
@@ -64,8 +63,6 @@ class Plugin extends Model
 
 	/**
 	 * Returns a comma-separated list with all author names
-	 *
-	 * @return string
 	 */
 	public function authorsNames(): string
 	{
@@ -79,7 +76,7 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @return array
+	 * Returns the associative array of extensions the plugin bundles
 	 */
 	public function extends(): array
 	{
@@ -87,9 +84,8 @@ class Plugin extends Model
 	}
 
 	/**
-	 * Returns the unique id for the plugin
-	 *
-	 * @return string
+	 * Returns the unique ID for the plugin
+	 * (alias for the plugin name)
 	 */
 	public function id(): string
 	{
@@ -97,7 +93,7 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @return array
+	 * Returns the raw data from composer.json
 	 */
 	public function info(): array
 	{
@@ -107,7 +103,7 @@ class Plugin extends Model
 
 		try {
 			$info = Data::read($this->manifest());
-		} catch (Exception $e) {
+		} catch (Exception) {
 			// there is no manifest file or it is invalid
 			$info = [];
 		}
@@ -117,10 +113,8 @@ class Plugin extends Model
 
 	/**
 	 * Returns the link to the plugin homepage
-	 *
-	 * @return string|null
 	 */
-	public function link(): ?string
+	public function link(): string|null
 	{
 		$info     = $this->info();
 		$homepage = $info['homepage'] ?? null;
@@ -133,7 +127,7 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @return string
+	 * Returns the path to the plugin's composer.json
 	 */
 	public function manifest(): string
 	{
@@ -141,7 +135,7 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @return string
+	 * Returns the root where plugin assets are copied to
 	 */
 	public function mediaRoot(): string
 	{
@@ -149,7 +143,7 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @return string
+	 * Returns the base URL for plugin assets
 	 */
 	public function mediaUrl(): string
 	{
@@ -157,7 +151,7 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @return string
+	 * Returns the plugin name (`vendor/plugin`)
 	 */
 	public function name(): string
 	{
@@ -165,8 +159,7 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @param string $key
-	 * @return mixed
+	 * Returns a Kirby option value for this plugin
 	 */
 	public function option(string $key)
 	{
@@ -174,7 +167,7 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @return string
+	 * Returns the option prefix (`vendor.plugin`)
 	 */
 	public function prefix(): string
 	{
@@ -182,7 +175,7 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @return string
+	 * Returns the root where the plugin files are stored
 	 */
 	public function root(): string
 	{
@@ -190,11 +183,13 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @param string $name
+	 * Validates and sets the plugin name
+	 *
 	 * @return $this
-	 * @throws \Kirby\Exception\InvalidArgumentException
+	 *
+	 * @throws \Kirby\Exception\InvalidArgumentException If the plugin name has an invalid format
 	 */
-	protected function setName(string $name)
+	protected function setName(string $name): static
 	{
 		if (preg_match('!^[a-z0-9-]+\/[a-z0-9-]+$!i', $name) !== 1) {
 			throw new InvalidArgumentException('The plugin name must follow the format "a-z0-9-/a-z0-9-"');
@@ -205,7 +200,7 @@ class Plugin extends Model
 	}
 
 	/**
-	 * @return array
+	 * Returns all available plugin metadata
 	 */
 	public function toArray(): array
 	{
@@ -219,4 +214,75 @@ class Plugin extends Model
 			'version'     => $this->version()
 		];
 	}
+
+	/**
+	 * Returns the update status object unless the
+	 * update check has been disabled for the plugin
+	 * @since 3.8.0
+	 *
+	 * @param array|null $data Custom override for the getkirby.com update data
+	 */
+	public function updateStatus(array|null $data = null): UpdateStatus|null
+	{
+		if ($this->updateStatus !== null) {
+			return $this->updateStatus;
+		}
+
+		$kirby  = $this->kirby();
+		$option = $kirby->option('updates.plugins');
+
+		// specific configuration per plugin
+		if (is_array($option) === true) {
+			// filter all option values by glob match
+			$option = A::filter(
+				$option,
+				fn ($value, $key) => fnmatch($key, $this->name()) === true
+			);
+
+			// sort the matches by key length (with longest key first)
+			$keys = array_map('strlen', array_keys($option));
+			array_multisort($keys, SORT_DESC, $option);
+
+			if (count($option) > 0) {
+				// use the first and therefore longest key (= most specific match)
+				$option = reset($option);
+			} else {
+				// fallback to the default option value
+				$option = true;
+			}
+		}
+
+		if ($option === null) {
+			$option = $kirby->option('updates') ?? true;
+		}
+
+		if ($option !== true) {
+			return null;
+		}
+
+		return $this->updateStatus = new UpdateStatus($this, false, $data);
+	}
+
+	/**
+	 * Returns the normalized version number
+	 * from the composer.json file
+	 */
+	public function version(): string|null
+	{
+		$version = $this->info()['version'] ?? null;
+
+		if (is_string($version) !== true || $version === '') {
+			return null;
+		}
+
+		// normalize the version number to be without leading `v`
+		$version = ltrim($version, 'vV');
+
+		// ensure that the version number now starts with a digit
+		if (preg_match('/^[0-9]/', $version) !== 1) {
+			return null;
+		}
+
+		return $version;
+	}
 }