better support for installing plugins via composer (#5112)

* merge installation and update commands
* generate metadata from array
* new command to list available packages
* added a management script to simplify updates
* added directory for dev files
* helper functions for installation and listing of packages
* run plugin database installers

src/Plugin/AbstractPluginExtension.php

@@ -14,17 +14,6 @@ use Symfony\Component\HttpKernel\DependencyInjection\Extension;
 
 abstract class AbstractPluginExtension extends Extension
 {
-    protected function registerIcon(ContainerBuilder $container, string $name, string $icon): void
-    {
-        $container->setParameter(
-            'tabler_bundle.icons',
-            array_merge(
-                $container->getParameter('tabler_bundle.icons'),
-                [$name => $icon]
-            )
-        );
-    }
-
     protected function registerBundleConfiguration(ContainerBuilder $container, array $configs): void
     {
         $bundleConfig = [$this->getAlias() => $configs];

src/Plugin/Package.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * This file is part of the Kimai time-tracking app.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace App\Plugin;
+
+/**
+ * @internaö
+ */
+final class Package
+{
+    public function __construct(private readonly \SplFileInfo $packageFile, private readonly PluginMetadata $pluginMetadata)
+    {
+    }
+
+    public function getPackageFile(): \SplFileInfo
+    {
+        return $this->packageFile;
+    }
+
+    public function getMetadata(): PluginMetadata
+    {
+        return $this->pluginMetadata;
+    }
+}

src/Plugin/PackageManager.php

@@ -0,0 +1,155 @@
+<?php
+
+/*
+ * This file is part of the Kimai time-tracking app.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace App\Plugin;
+
+/**
+ * @internal
+ */
+final class PackageManager
+{
+    public const PACKAGE_DIR = 'var/packages';
+
+    public function __construct(private readonly string $projectDirectory)
+    {
+    }
+
+    /**
+     * @return Package[]
+     */
+    public function getAvailablePackages(): array
+    {
+        return $this->findAvailablePackages($this->projectDirectory . '/' . self::PACKAGE_DIR);
+    }
+
+    /**
+     * Copied from Composer\Repository\ArtifactRepository
+     * @see https://github.com/composer/composer/blob/main/src/Composer/Repository/ArtifactRepository.php
+     *
+     * @return Package[]
+     */
+    private function findAvailablePackages(string $path): array
+    {
+        $packages = [];
+
+        $directory = new \RecursiveDirectoryIterator($path, \RecursiveDirectoryIterator::FOLLOW_SYMLINKS);
+        $iterator = new \RecursiveIteratorIterator($directory);
+        $regex = new \RegexIterator($iterator, '/^.+\.zip$/i');
+        /** @var \SplFileInfo $file */
+        foreach ($regex as $file) {
+            if (!$file->isFile()) {
+                continue;
+            }
+
+            $package = $this->getComposerJson($file->getPathname());
+            if ($package === null) {
+                continue;
+            }
+
+            $content = json_decode($package, true);
+            if (\JSON_ERROR_NONE !== json_last_error() || !\is_array($content)) {
+                throw new \RuntimeException('Failed to parse composer.json file in: ' . $file->getPathname());
+            }
+
+            $packages[] = new Package($file, PluginMetadata::createFromArray($content));
+        }
+
+        return $packages;
+    }
+
+    /**
+     * Copied from Composer\Util\Zip
+     * @see https://github.com/composer/composer/blob/main/src/Composer/Util/Zip.php
+     */
+    private function getComposerJson(string $pathToZip): ?string
+    {
+        if (!\extension_loaded('zip')) {
+            throw new \RuntimeException('The Zip Util requires PHP\'s zip extension');
+        }
+
+        $zip = new \ZipArchive();
+        if ($zip->open($pathToZip) !== true) {
+            return null;
+        }
+
+        if (0 === $zip->numFiles) {
+            $zip->close();
+
+            return null;
+        }
+
+        $foundFileIndex = self::locateFile($zip, 'composer.json');
+
+        $content = null;
+        $configurationFileName = $zip->getNameIndex($foundFileIndex);
+        if ($configurationFileName !== false) {
+            $stream = $zip->getStream($configurationFileName);
+
+            if (false !== $stream) {
+                $content = stream_get_contents($stream);
+                if ($content === false) {
+                    $content = null;
+                }
+            }
+        }
+
+        $zip->close();
+
+        return $content;
+    }
+
+    /**
+     * Copied from Composer\Util\Zip
+     * @see https://github.com/composer/composer/blob/main/src/Composer/Util/Zip.php
+     */
+    private static function locateFile(\ZipArchive $zip, string $filename): int
+    {
+        // return root composer.json if it is there and is a file
+        if (false !== ($index = $zip->locateName($filename)) && $zip->getFromIndex($index) !== false) {
+            return $index;
+        }
+
+        $topLevelPaths = [];
+        for ($i = 0; $i < $zip->numFiles; $i++) {
+            $name = $zip->getNameIndex($i);
+            if ($name === false) {
+                continue;
+            }
+            $dirname = \dirname($name);
+
+            // ignore OSX specific resource fork folder
+            if (strpos($name, '__MACOSX') !== false) {
+                continue;
+            }
+
+            // handle archives with proper TOC
+            if ($dirname === '.') {
+                $topLevelPaths[$name] = true;
+                if (\count($topLevelPaths) > 1) {
+                    throw new \RuntimeException('Archive has more than one top level directories, and no composer.json was found on the top level, so it\'s an invalid archive. Top level paths found were: ' . implode(',', array_keys($topLevelPaths)));
+                }
+                continue;
+            }
+
+            // handle archives which do not have a TOC record for the directory itself
+            if (false === strpos($dirname, '\\') && false === strpos($dirname, '/')) {
+                $topLevelPaths[$dirname . '/'] = true;
+                if (\count($topLevelPaths) > 1) {
+                    throw new \RuntimeException('Archive has more than one top level directories, and no composer.json was found on the top level, so it\'s an invalid archive. Top level paths found were: ' . implode(',', array_keys($topLevelPaths)));
+                }
+            }
+        }
+
+        if ($topLevelPaths && false !== ($index = $zip->locateName(key($topLevelPaths) . $filename)) && $zip->getFromIndex($index) !== false) {
+            return $index;
+        }
+
+        throw new \RuntimeException('No composer.json found either at the top level or within the topmost directory');
+    }
+}

src/Plugin/Plugin.php

@@ -20,7 +20,7 @@ final class Plugin
     public function getMetadata(): PluginMetadata
     {
         if ($this->metadata === null) {
-            $this->metadata = new PluginMetadata($this->getPath());
+            $this->metadata = PluginMetadata::createFromPath($this->getPath());
         }
 
         return $this->metadata;
@@ -33,12 +33,7 @@ final class Plugin
 
     public function getName(): string
     {
-        $meta = $this->getMetadata();
-        if ($meta->getName() !== null) {
-            return $meta->getName();
-        }
-
-        return $this->getId();
+        return $this->getMetadata()->getName();
     }
 
     public function getId(): string

src/Plugin/PluginMetadata.php

@@ -13,57 +13,79 @@ use App\Constants;
 
 class PluginMetadata
 {
-    private ?string $version = null;
-    private ?int $kimaiVersion = null;
-    private ?string $homepage = null;
-    private ?string $description = null;
-    private ?string $name = null;
+    private string $package;
+    private string $version;
+    private int $kimaiVersion;
+    private string $homepage;
+    private string $description;
+    private string $name;
 
-    /**
-     * @throws \Exception
-     */
-    public function __construct(string $path)
+    public static function createFromPath(string $path): self
     {
         if (!is_dir($path) || !is_readable($path)) {
             throw new \Exception(\sprintf('Bundle directory "%s" cannot be accessed.', $path));
         }
 
-        $pluginName = basename($path);
         $composer = $path . '/composer.json';
 
         if (!file_exists($composer) || !is_readable($composer)) {
-            throw new \Exception(\sprintf('Bundle "%s" does not ship composer.json, which is required since 2.0.', $pluginName));
+            throw new \Exception('Bundle does not ship composer.json, which is required since 2.0.');
         }
 
+        /** @var array<mixed>|null $json */
         $json = json_decode(file_get_contents($composer), true);
 
+        if ($json === null) {
+            throw new \Exception('Could not parse composer.json, invalid JSON?');
+        }
+
+        return self::createFromArray($json);
+    }
+
+    /**
+     * @param array<mixed> $json
+     */
+    public static function createFromArray(array $json): self
+    {
         if (!\array_key_exists('extra', $json)) {
-            throw new \Exception(\sprintf('Bundle "%s" does not define an "extra" node in composer.json, which is required since 2.0.', $pluginName));
+            throw new \Exception('Bundle "%s" does not define an "extra" node in composer.json, which is required since 2.0.');
         }
 
         if (!\array_key_exists('kimai', $json['extra'])) {
-            throw new \Exception(\sprintf('Bundle "%s" does not define the "extra.kimai" node in composer.json, which is required since 2.0.', $pluginName));
+            throw new \Exception('Bundle does not define the "extra.kimai" node in composer.json, which is required since 2.0.');
         }
 
         if (!\array_key_exists('require', $json['extra']['kimai'])) {
-            throw new \Exception(\sprintf('Bundle "%s" does not define the minimum Kimai version in "extra.kimai.required" in composer.json, which is required since 2.0.', $pluginName));
+            throw new \Exception('Bundle does not define the minimum Kimai version in "extra.kimai.required" in composer.json, which is required since 2.0.');
         }
 
         if (!\array_key_exists('name', $json['extra']['kimai'])) {
-            throw new \Exception(\sprintf('Bundle "%s" does not define its name in "extra.kimai.name" in composer.json, which is required since 2.0.', $pluginName));
+            throw new \Exception('Bundle does not define its name in "extra.kimai.name" in composer.json, which is required since 2.0.');
         }
 
         if (!\is_int($json['extra']['kimai']['require'])) {
-            throw new \Exception(\sprintf('Bundle "%s" defines an invalid Kimai minimum version in extra.kimai.require. Please provide an integer as in Constants::VERSION_ID.', $pluginName));
+            throw new \Exception('Bundle defines an invalid Kimai minimum version in extra.kimai.require. Please provide an integer as in Constants::VERSION_ID.');
         }
 
-        $this->description = $json['description'] ?? '';
-        $this->homepage = $json['homepage'] ?? Constants::HOMEPAGE . '/store/';
-        $this->name = $json['extra']['kimai']['name'];
-        $this->kimaiVersion = $json['extra']['kimai']['require'];
+        $meta = new self();
+
+        $meta->package = $json['name'] ?? '';
+        $meta->description = $json['description'] ?? '';
+        $meta->homepage = $json['homepage'] ?? Constants::HOMEPAGE . '/store/';
+        $meta->name = $json['extra']['kimai']['name'];
+        $meta->kimaiVersion = $json['extra']['kimai']['require'];
 
         // the version field is required if we use composer to install a plugin via var/packages/
-        $this->version = $json['extra']['kimai']['version'] ?? ($json['version'] ?? 'unknown');
+        $meta->version = $json['extra']['kimai']['version'] ?? ($json['version'] ?? 'unknown');
+
+        return $meta;
+    }
+
+    private function __construct() {}
+
+    public function getPackage(): string
+    {
+        return $this->package;
     }
 
     public function getDescription(): ?string
@@ -71,22 +93,22 @@ class PluginMetadata
         return $this->description;
     }
 
-    public function getVersion(): ?string
+    public function getVersion(): string
     {
         return $this->version;
     }
 
-    public function getKimaiVersion(): ?int
+    public function getKimaiVersion(): int
     {
         return $this->kimaiVersion;
     }
 
-    public function getHomepage(): ?string
+    public function getHomepage(): string
     {
         return $this->homepage;
     }
 
-    public function getName(): ?string
+    public function getName(): string
     {
         return $this->name;
     }