Skip to content

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.php
new file mode 100644
index 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.php
index 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.php
new file mode 100644
index 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.php
new file mode 100644
index 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.php
new file mode 100644
index 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.php
index 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.md
index 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.