Merge pull request #5607 from BookStackApp/system_info_endpoint

ssddanbrown · web-flow · commit 59e2c5e52a93 · 2025-05-22T17:31:32.000+01:00
API: System info endpoint
diff --git a/app/Api/ApiDocsGenerator.php b/app/Api/ApiDocsGenerator.php
@@ -2,6 +2,7 @@
 
 namespace BookStack\Api;
 
+use BookStack\App\AppVersion;
 use BookStack\Http\ApiController;
 use Exception;
 use Illuminate\Contracts\Container\BindingResolutionException;
@@ -25,7 +26,7 @@ class ApiDocsGenerator
      */
     public static function generateConsideringCache(): Collection
     {
-        $appVersion = trim(file_get_contents(base_path('version')));
+        $appVersion = AppVersion::get();
         $cacheKey = 'api-docs::' . $appVersion;
         $isProduction = config('app.env') === 'production';
         $cacheVal = $isProduction ? Cache::get($cacheKey) : null;
diff --git a/app/App/AppVersion.php b/app/App/AppVersion.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace BookStack\App;
+
+class AppVersion
+{
+    protected static string $version = '';
+
+    /**
+     * Get the application's version number from its top-level `version` text file.
+     */
+    public static function get(): string
+    {
+        if (!empty(static::$version)) {
+            return static::$version;
+        }
+
+        $versionFile = base_path('version');
+        $version = trim(file_get_contents($versionFile));
+        static::$version = $version;
+
+        return $version;
+    }
+}
diff --git a/app/App/SystemApiController.php b/app/App/SystemApiController.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace BookStack\App;
+
+use BookStack\Http\ApiController;
+use Illuminate\Http\JsonResponse;
+
+class SystemApiController extends ApiController
+{
+    /**
+     * Read details regarding the BookStack instance.
+     * Some details may be null where not set, like the app logo for example.
+     */
+    public function read(): JsonResponse
+    {
+        $logoSetting = setting('app-logo', '');
+        if ($logoSetting === 'none') {
+            $logo = null;
+        } else {
+            $logo = $logoSetting ? url($logoSetting) : url('/logo.png');
+        }
+
+        return response()->json([
+            'version' => AppVersion::get(),
+            'instance_id' => setting('instance-id'),
+            'app_name' => setting('app-name'),
+            'app_logo' => $logo,
+            'base_url' => url('/'),
+        ]);
+    }
+}
diff --git a/app/App/helpers.php b/app/App/helpers.php
@@ -1,5 +1,6 @@
 <?php
 
+use BookStack\App\AppVersion;
 use BookStack\App\Model;
 use BookStack\Facades\Theme;
 use BookStack\Permissions\PermissionApplicator;
@@ -13,12 +14,7 @@
  */
 function versioned_asset(string $file = ''): string
 {
-    static $version = null;
-
-    if (is_null($version)) {
-        $versionFile = base_path('version');
-        $version = trim(file_get_contents($versionFile));
-    }
+    $version = AppVersion::get();
 
     $additional = '';
     if (config('app.env') === 'development') {
diff --git a/app/Exceptions/BookStackExceptionHandlerPage.php b/app/Exceptions/BookStackExceptionHandlerPage.php
@@ -2,6 +2,7 @@
 
 namespace BookStack\Exceptions;
 
+use BookStack\App\AppVersion;
 use Illuminate\Contracts\Foundation\ExceptionRenderer;
 
 class BookStackExceptionHandlerPage implements ExceptionRenderer
@@ -30,9 +31,7 @@ protected function getEnvironment(): array
         return [
             'PHP Version'       => phpversion(),
             'BookStack Version' => $this->safeReturn(function () {
-                $versionFile = base_path('version');
-
-                return trim(file_get_contents($versionFile));
+                return AppVersion::get();
             }, 'unknown'),
             'Theme Configured' => $this->safeReturn(function () {
                 return config('view.theme');
diff --git a/app/Exports/ZipExports/ZipExportBuilder.php b/app/Exports/ZipExports/ZipExportBuilder.php
@@ -2,6 +2,7 @@
 
 namespace BookStack\Exports\ZipExports;
 
+use BookStack\App\AppVersion;
 use BookStack\Entities\Models\Book;
 use BookStack\Entities\Models\Chapter;
 use BookStack\Entities\Models\Page;
@@ -70,7 +71,7 @@ protected function build(): string
         $this->data['exported_at'] = date(DATE_ATOM);
         $this->data['instance'] = [
             'id'      => setting('instance-id', ''),
-            'version' => trim(file_get_contents(base_path('version'))),
+            'version' => AppVersion::get(),
         ];
 
         $zipFile = tempnam(sys_get_temp_dir(), 'bszip-');
diff --git a/app/Settings/MaintenanceController.php b/app/Settings/MaintenanceController.php
@@ -3,6 +3,7 @@
 namespace BookStack\Settings;
 
 use BookStack\Activity\ActivityType;
+use BookStack\App\AppVersion;
 use BookStack\Entities\Tools\TrashCan;
 use BookStack\Http\Controller;
 use BookStack\References\ReferenceStore;
@@ -19,14 +20,11 @@ public function index(TrashCan $trashCan)
         $this->checkPermission('settings-manage');
         $this->setPageTitle(trans('settings.maint'));
 
-        // Get application version
-        $version = trim(file_get_contents(base_path('version')));
-
         // Recycle bin details
         $recycleStats = $trashCan->getTrashedCounts();
 
         return view('settings.maintenance', [
-            'version'      => $version,
+            'version'      => AppVersion::get(),
             'recycleStats' => $recycleStats,
         ]);
     }
diff --git a/app/Settings/SettingController.php b/app/Settings/SettingController.php
@@ -3,6 +3,7 @@
 namespace BookStack\Settings;
 
 use BookStack\Activity\ActivityType;
+use BookStack\App\AppVersion;
 use BookStack\Http\Controller;
 use BookStack\Users\Models\User;
 use Illuminate\Http\Request;
@@ -26,12 +27,9 @@ public function category(string $category)
         $this->checkPermission('settings-manage');
         $this->setPageTitle(trans('settings.settings'));
 
-        // Get application version
-        $version = trim(file_get_contents(base_path('version')));
-
         return view('settings.categories.' . $category, [
             'category'  => $category,
-            'version'   => $version,
+            'version'   => AppVersion::get(),
             'guestUser' => User::getGuest(),
         ]);
     }
diff --git a/dev/api/responses/system-read.json b/dev/api/responses/system-read.json
@@ -0,0 +1,7 @@
+{
+  "version": "v25.02.4",
+  "instance_id": "1234abcd-cc12-7808-af0a-264cb0cbd611",
+  "app_name": "My BookStack Instance",
+  "app_logo": "https://docs.example.com/uploads/images/system/2025-05/cat-icon.png",
+  "base_url": "https://docs.example.com"
+}
diff --git a/routes/api.php b/routes/api.php
@@ -8,6 +8,7 @@
 
 use BookStack\Activity\Controllers\AuditLogApiController;
 use BookStack\Api\ApiDocsController;
+use BookStack\App\SystemApiController;
 use BookStack\Entities\Controllers as EntityControllers;
 use BookStack\Exports\Controllers as ExportControllers;
 use BookStack\Permissions\ContentPermissionApiController;
@@ -92,3 +93,5 @@
 Route::put('content-permissions/{contentType}/{contentId}', [ContentPermissionApiController::class, 'update']);
 
 Route::get('audit-log', [AuditLogApiController::class, 'list']);
+
+Route::get('system', [SystemApiController::class, 'read']);
diff --git a/tests/Api/SystemApiTest.php b/tests/Api/SystemApiTest.php
@@ -0,0 +1,25 @@
+<?php
+
+namespace Api;
+
+use BookStack\Activity\ActivityType;
+use BookStack\Facades\Activity;
+use Tests\Api\TestsApi;
+use Tests\TestCase;
+
+class SystemApiTest extends TestCase
+{
+    use TestsApi;
+
+    public function test_read_returns_app_info(): void
+    {
+        $resp = $this->actingAsApiEditor()->get('/api/system');
+        $data = $resp->json();
+
+        $this->assertStringStartsWith('v', $data['version']);
+        $this->assertEquals(setting('instance-id'), $data['instance_id']);
+        $this->assertEquals(setting('app-name'), $data['app_name']);
+        $this->assertEquals(url('/logo.png'), $data['app_logo']);
+        $this->assertEquals(url('/'), $data['base_url']);
+    }
+}
