NOW MANAGED ON CODEBERG
Theme Modules: Added install helper command
Dan Brown45ae03ceac11
diff --git a/app/Console/Commands/InstallModuleCommand.php b/app/Console/Commands/InstallModuleCommand.phpnew file mode 100644index 000000000..c2ce1a444--- /dev/null+++ b/app/Console/Commands/InstallModuleCommand.php@@ -0,0 +1,249 @@+<?php++namespace BookStack\Console\Commands;++use BookStack\Http\HttpRequestService;+use BookStack\Theming\ThemeModule;+use BookStack\Theming\ThemeModuleException;+use BookStack\Theming\ThemeModuleManager;+use BookStack\Theming\ThemeModuleZip;+use Illuminate\Console\Command;+use Illuminate\Support\Str;++class InstallModuleCommand extends Command+{+ /**+ * The name and signature of the console command.+ *+ * @var string+ */+ protected $signature = 'bookstack:install-module+ {location : The URL or path of the module file}';++ /**+ * The console command description.+ *+ * @var string+ */+ protected $description = 'Install a module to the currently configured theme';++ protected array $cleanupActions = [];++ /**+ * Execute the console command.+ */+ public function handle(): int+ {+ $location = $this->argument('location');++ // Get the ZIP file containing the module files+ $zipPath = $this->getPathToZip($location);+ if (!$zipPath) {+ $this->cleanup();+ return 1;+ }++ // Validate module zip file (metadata, size, etc...) and get module instance+ $zip = new ThemeModuleZip($zipPath);+ $themeModule = $this->validateAndGetModuleInfoFromZip($zip);+ if (!$themeModule) {+ $this->cleanup();+ return 1;+ }++ // Get the theme folder in use, attempting to create one if no active theme in use+ $themeFolder = $this->getThemeFolder();+ if (!$themeFolder) {+ $this->cleanup();+ return 1;+ }++ // Get the modules folder of the theme, attempting to create it if not existing,+ // and create a new module manager instance.+ $moduleFolder = $this->getModuleFolder($themeFolder);+ $manager = new ThemeModuleManager($moduleFolder);++ // Handle existing modules with the same name+ $exitingModulesWithName = $manager->getByName($themeModule->name);+ $shouldContinue = $this->handleExistingModulesWithSameName($exitingModulesWithName, $manager);+ if (!$shouldContinue) {+ $this->cleanup();+ return 1;+ }++ // Extract module ZIP into the theme modules folder+ try {+ $newModule = $manager->addFromZip($themeModule->name, $zip);+ } catch (ThemeModuleException $exception) {+ $this->error("ERROR: Failed to install module with error: {$exception->getMessage()}");+ $this->cleanup();+ return 1;+ }++ $this->info("Module {$newModule->name} ({$newModule->version}) successfully installed!");+ $this->info("It has been installed at {$moduleFolder}/{$newModule->folderName}.");+ $this->cleanup();+ return 0;+ }++ protected function handleExistingModulesWithSameName(array $existingModules, ThemeModuleManager $manager): bool+ {+ if (count($existingModules) === 0) {+ return true;+ }++ $this->warn("The following modules already exist with the same name:");+ foreach ($existingModules as $folder => $module) {+ $this->line("{$module->name} ({$folder}:{$module->version}) - {$module->description}}");+ }+ $this->line('');++ $choices = ['Cancel Module Install', 'Add Alongside Existing'];+ if (count($existingModules) === 1) {+ $choices[] = 'Replace Existing Module';+ }+ $choice = $this->choice("What would you like to do?", $choices, 0, null, false);+ if ($choice === 'Cancel Module Install') {+ return false;+ }++ if ($choice === 'Replace Existing Module') {+ $existingModuleFolder = array_key_first($existingModules);+ $this->info("Replacing existing module in {$existingModuleFolder} folder");+ $manager->deleteModuleFolder($existingModuleFolder);+ }++ return true;+ }++ protected function getModuleFolder(string $themeFolder): string|null+ {+ $path = $themeFolder . DIRECTORY_SEPARATOR . 'modules';+ if (!file_exists($path)) {+ if (!is_dir($path)) {+ $this->error("ERROR: Cannot create a modules folder, file already exists at {$path}");+ }++ $created = mkdir($path, 0755, true);+ if (!$created) {+ $this->error("ERROR: Failed to create a modules folder at {$path}");+ }+ }++ return $path;+ }++ protected function getThemeFolder(): string|null+ {+ $path = theme_path('');+ if (!$path) {+ $shouldCreate = $this->confirm('No active theme folder found, would you like to create one?');+ if (!$shouldCreate) {+ return null;+ }++ $folder = 'custom';+ while (file_exists(base_path("themes" . DIRECTORY_SEPARATOR . $folder))) {+ $folder = 'custom-' . Str::random(4);+ }++ $path = base_path("themes/{$folder}");+ $created = mkdir($path, 0755, true);+ if (!$created) {+ $this->error('Failed to create a theme folder to use. This may be a permissions issue. Try manually configuring an active theme.');+ return null;+ }++ $this->info("Created theme folder at {$path}");+ $this->warn("You will need to set APP_THEME={$folder} in your BookStack env configuration to enable this theme!");+ }++ return $path;+ }++ protected function validateAndGetModuleInfoFromZip(ThemeModuleZip $zip): ThemeModule|null+ {+ if (!$zip->exists()) {+ $this->error("ERROR: Cannot open ZIP file at {$zip->getPath()}");+ return null;+ }++ if ($zip->getContentsSize() > (50 * 1024 * 1024)) {+ $this->error("ERROR: Module ZIP file is too large. Maximum size is 50MB.");+ return null;+ }++ try {+ $themeModule = $zip->getModuleInstance();+ } catch (ThemeModuleException $exception) {+ $this->error("ERROR: Failed to read module metadata with error: {$exception->getMessage()}");+ return null;+ }++ return $themeModule;+ }++ protected function downloadModuleFile(string $location): string+ {+ $httpRequests = app()->make(HttpRequestService::class);+ $client = $httpRequests->buildClient(30);++ $resp = $client->get($location, ['stream' => true]);++ $tempFile = tempnam(sys_get_temp_dir(), 'bookstack_module_');+ $fileHandle = fopen($tempFile, 'w');++ stream_copy_to_stream($resp->getBody()->detach(), $fileHandle);++ fclose($fileHandle);++ $this->cleanupActions[] = function () use ($tempFile) {+ unlink($tempFile);+ };++ return $tempFile;+ }++ protected function getPathToZip(string $location): string|null+ {+ $lowerLocation = strtolower($location);+ $isRemote = str_starts_with($lowerLocation, 'http://') || str_starts_with($lowerLocation, 'https://');++ if ($isRemote) {+ // Warning about fetching from source+ $host = parse_url($location, PHP_URL_HOST);+ $this->warn("This will download a module from {$host}. Modules can contain code which would have the ability to do anything on the BookStack host server.");+ $trustHost = $this->confirm('Are you sure you trust this source?');+ if (!$trustHost) {+ return null;+ }++ // Check if the connection is http. If so, warn the user.+ if (str_starts_with($lowerLocation, 'http://')) {+ $this->warn('You are downloading a module from an insecure HTTP source. We recommend using HTTPS sources.');+ if (!$this->confirm('Do you wish to continue?')) {+ return null;+ }+ }++ // Download ZIP and get its location+ return $this->downloadModuleFile($location);+ }++ // Validate file and get full location+ $zipPath = realpath($location);+ if (!$zipPath || !is_file($zipPath)) {+ $this->error("ERROR: Module file not found at {$location}");+ return null;+ }++ return $zipPath;+ }++ protected function cleanup(): void+ {+ foreach ($this->cleanupActions as $action) {+ $action();+ }+ }+}diff --git a/app/Theming/ThemeModule.php b/app/Theming/ThemeModule.phpindex 12b1486be..ab5fc6145 100644--- a/app/Theming/ThemeModule.php+++ b/app/Theming/ThemeModule.php@@ -2,46 +2,44 @@namespace BookStack\Theming;-use BookStack\Exceptions\ThemeException;-readonly class ThemeModule{public function __construct(public string $name,public string $description,- public string $folderName,public string $version,+ public string $folderName,) {}/*** Create a ThemeModule instance from JSON data.*- * @throws ThemeException+ * @throws ThemeModuleException*/public static function fromJson(array $data, string $folderName): self{if (empty($data['name']) || !is_string($data['name'])) {- throw new ThemeException("Module in folder \"{$folderName}\" is missing a valid 'name' property");+ throw new ThemeModuleException("Module in folder \"{$folderName}\" is missing a valid 'name' property");}if (!isset($data['description']) || !is_string($data['description'])) {- throw new ThemeException("Module in folder \"{$folderName}\" is missing a valid 'description' property");+ throw new ThemeModuleException("Module in folder \"{$folderName}\" is missing a valid 'description' property");}if (!isset($data['version']) || !is_string($data['version'])) {- throw new ThemeException("Module in folder \"{$folderName}\" is missing a valid 'version' property");+ throw new ThemeModuleException("Module in folder \"{$folderName}\" is missing a valid 'version' property");}if (!preg_match('/^v?\d+\.\d+\.\d+(-.*)?$/', $data['version'])) {- throw new ThemeException("Module in folder \"{$folderName}\" has an invalid 'version' format. Expected semantic version format like '1.0.0' or 'v1.0.0'");+ throw new ThemeModuleException("Module in folder \"{$folderName}\" has an invalid 'version' format. Expected semantic version format like '1.0.0' or 'v1.0.0'");}return new self(name: $data['name'],description: $data['description'],- folderName: $folderName,version: $data['version'],+ folderName: $folderName,);}@@ -53,4 +51,9 @@ readonly class ThemeModule$component = trim($path, '/');return theme_path("modules/{$this->folderName}/{$component}");}++ public function getVersion(): string+ {+ return str_starts_with($this->version, 'v') ? $this->version : 'v' . $this->version;+ }}diff --git a/app/Theming/ThemeModuleException.php b/app/Theming/ThemeModuleException.phpnew file mode 100644index 000000000..4d296a64f--- /dev/null+++ b/app/Theming/ThemeModuleException.php@@ -0,0 +1,7 @@+<?php++namespace BookStack\Theming;++class ThemeModuleException extends \Exception+{+}diff --git a/app/Theming/ThemeModuleManager.php b/app/Theming/ThemeModuleManager.phpnew file mode 100644index 000000000..a1227abf7--- /dev/null+++ b/app/Theming/ThemeModuleManager.php@@ -0,0 +1,133 @@+<?php++namespace BookStack\Theming;++use Illuminate\Support\Str;++class ThemeModuleManager+{+ /** @var array<string, ThemeModule>|null */+ protected array|null $loadedModules = null;++ public function __construct(+ protected string $modulesFolderPath+ ) {+ }++ /**+ * @return array<string, ThemeModule>+ */+ public function getByName(string $name): array+ {+ return array_filter($this->load(), fn(ThemeModule $module) => $module->getName() === $name);+ }++ public function deleteModuleFolder(string $moduleFolderName): void+ {+ $modules = $this->load();+ $module = $modules[$moduleFolderName] ?? null;+ if (!$module) {+ return;+ }++ $moduleFolderPath = $module->path('');+ if (!file_exists($moduleFolderPath)) {+ return;+ }++ $this->deleteDirectoryRecursively($moduleFolderPath);+ unset($this->loadedModules[$moduleFolderName]);+ }++ /**+ * @throws ThemeModuleException+ */+ public function addFromZip(string $name, ThemeModuleZip $zip): ThemeModule+ {+ $baseFolderName = Str::limit(Str::slug($name), 20);+ $folderName = $baseFolderName;+ while (!$baseFolderName || file_exists($this->modulesFolderPath . DIRECTORY_SEPARATOR . $folderName)) {+ $folderName = ($baseFolderName ?: 'mod') . '-' . Str::random(4);+ }++ $folderPath = $this->modulesFolderPath . DIRECTORY_SEPARATOR . $folderName;+ $zip->extractTo($folderPath);++ $module = $this->loadFromFolder($folderName);+ if (!$module) {+ throw new ThemeModuleException("Failed to load module from zip file after extraction.");+ }++ return $module;+ }++ protected function deleteDirectoryRecursively(string $path): void+ {+ $items = array_diff(scandir($path), ['.', '..']);+ foreach ($items as $item) {+ $itemPath = $path . DIRECTORY_SEPARATOR . $item;+ if (is_dir($itemPath)) {+ $this->deleteDirectoryRecursively($itemPath);+ } else {+ $deleted = unlink($itemPath);+ if (!$deleted) {+ throw new ThemeModuleException("Failed to delete file at \"{$itemPath}\"");+ }+ }+ }+ rmdir($path);+ }++ public function load(): array+ {+ if ($this->loadedModules !== null) {+ return $this->loadedModules;+ }++ if (!is_dir($this->modulesFolderPath)) {+ return [];+ }++ $subFolders = array_filter(scandir($this->modulesFolderPath), function ($item) {+ return $item !== '.' && $item !== '..' && is_dir($this->modulesFolderPath . DIRECTORY_SEPARATOR . $item);+ });++ $modules = [];++ foreach ($subFolders as $folderName) {+ $module = $this->loadFromFolder($folderName);+ if ($module) {+ $modules[$folderName] = $module;+ }+ }++ $this->loadedModules = $modules;++ return $modules;+ }++ protected function loadFromFolder(string $folderName): ThemeModule|null+ {+ $moduleJsonFile = $this->modulesFolderPath . DIRECTORY_SEPARATOR . $folderName . DIRECTORY_SEPARATOR . 'bookstack-module.json';+ if (!file_exists($moduleJsonFile)) {+ return null;+ }++ try {+ $jsonContent = file_get_contents($moduleJsonFile);+ $jsonData = json_decode($jsonContent, true);++ if (json_last_error() !== JSON_ERROR_NONE) {+ throw new ThemeModuleException("Invalid JSON in module file at \"{$moduleJsonFile}\": " . json_last_error_msg());+ }++ $module = ThemeModule::fromJson($jsonData, $folderName);+ } catch (ThemeModuleException $exception) {+ throw $exception;+ } catch (\Exception $exception) {+ throw new ThemeModuleException("Failed loading module from \"{$moduleJsonFile}\" with error: {$exception->getMessage()}");+ }++ return $module;+ }+}diff --git a/app/Theming/ThemeModuleZip.php b/app/Theming/ThemeModuleZip.phpnew file mode 100644index 000000000..f6d9432b0--- /dev/null+++ b/app/Theming/ThemeModuleZip.php@@ -0,0 +1,93 @@+<?php++namespace BookStack\Theming;++readonly class ThemeModuleZip+{+ public function __construct(+ protected string $path+ ) {+ }++ public function extractTo(string $destinationPath): void+ {+ $zip = new \ZipArchive();+ $zip->open($this->path);+ $zip->extractTo($destinationPath);+ $zip->close();+ }++ /**+ * Read the module's JSON metadata to read it into a ThemeModule instance.+ * @throws ThemeModuleException+ */+ public function getModuleInstance(): ThemeModule+ {+ $zip = new \ZipArchive();+ $open = $zip->open($this->path);+ if ($open !== true) {+ throw new ThemeModuleException("Unable to open zip file at {$this->path}");+ }++ $moduleJsonText = $zip->getFromName('bookstack-module.json');+ $zip->close();++ if ($moduleJsonText === false) {+ throw new ThemeModuleException("bookstack-module.json not found within module ZIP at {$this->path}");+ }++ $moduleJson = json_decode($moduleJsonText, true);+ if ($moduleJson === null) {+ throw new ThemeModuleException("Could not read JSON from bookstack-module.json within module ZIP at {$this->path}");+ }++ return ThemeModule::fromJson($moduleJson, '_temp');+ }++ /**+ * Get the path to the zip file.+ */+ public function getPath(): string+ {+ return $this->path;+ }++ /**+ * Check if the zip file exists and that it appears to be a valid zip file.+ */+ public function exists(): bool+ {+ if (!file_exists($this->path)) {+ return false;+ }++ $zip = new \ZipArchive();+ $open = $zip->open($this->path);+ $zip->close();+ return $open === true;+ }++ /**+ * Get the total size of the zip file contents when uncompressed.+ */+ public function getContentsSize(): int+ {+ $zip = new \ZipArchive();++ if ($zip->open($this->path) !== true) {+ return 0;+ }++ $totalSize = 0;+ for ($i = 0; $i < $zip->numFiles; $i++) {+ $stat = $zip->statIndex($i);+ if ($stat !== false) {+ $totalSize += $stat['size'];+ }+ }++ $zip->close();++ return $totalSize;+ }+}diff --git a/app/Theming/ThemeService.php b/app/Theming/ThemeService.phpindex 6f3112980..6013bb558 100644--- a/app/Theming/ThemeService.php+++ b/app/Theming/ThemeService.php@@ -105,41 +105,16 @@ class ThemeService/*** Read the modules folder and load in any valid theme modules.+ * @throws ThemeModuleException*/public function loadModules(): void{$modulesFolder = theme_path('modules');- if (!$modulesFolder || !is_dir($modulesFolder)) {+ if (!$modulesFolder) {return;}- $subFolders = array_filter(scandir($modulesFolder), function ($item) use ($modulesFolder) {- return $item !== '.' && $item !== '..' && is_dir($modulesFolder . DIRECTORY_SEPARATOR . $item);- });-- foreach ($subFolders as $folderName) {- $moduleJsonFile = $modulesFolder . DIRECTORY_SEPARATOR . $folderName . DIRECTORY_SEPARATOR . 'bookstack-module.json';-- if (!file_exists($moduleJsonFile)) {- continue;- }-- try {- $jsonContent = file_get_contents($moduleJsonFile);- $jsonData = json_decode($jsonContent, true);-- if (json_last_error() !== JSON_ERROR_NONE) {- throw new ThemeException("Invalid JSON in module file at \"{$moduleJsonFile}\": " . json_last_error_msg());- }-- $module = ThemeModule::fromJson($jsonData, $folderName);- $this->modules[$folderName] = $module;- } catch (ThemeException $exception) {- throw $exception;- } catch (\Exception $exception) {- throw new ThemeException("Failed loading module from \"{$moduleJsonFile}\" with error: {$exception->getMessage()}");- }- }+ $this->modules = (new ThemeModuleManager($modulesFolder))->load();}/**diff --git a/dev/docs/visual-theme-system.md b/dev/docs/visual-theme-system.mdindex 8d5669b82..327660be5 100644--- a/dev/docs/visual-theme-system.md+++ b/dev/docs/visual-theme-system.md@@ -53,7 +53,7 @@ configured application theme.There are some considerations to these publicly served files:-- Only a predetermined range "web safe" content-types are currently served.+- Only a predetermined range of "web safe" content-types are currently served.- This limits running into potential insecure scenarios in serving problematic file types.- A static 1-day cache time it set on files served from this folder.- You can use alternative cache-breaking techniques (change of query string) upon changes if needed.