Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
50.35%
71 / 141
53.33%
8 / 15
 CRAP
0.00%
0 / 1
DashboardController
50.35%
71 / 141
53.33%
8 / 15
 469.62
0.00%
0 / 1
 __construct
100.00%
1 / 1
100.00%
1 / 1
 1
 getFreshCache
81.82%
9 / 11
0.00%
0 / 1
 7.29
 getStaleCache
100.00%
4 / 4
100.00%
1 / 1
 4
 storeCache
0.00%
0 / 4
0.00%
0 / 1
 2
 verify
100.00%
4 / 4
100.00%
1 / 1
 1
 versions
60.00%
15 / 25
0.00%
0 / 1
 12.10
 visits
100.00%
8 / 8
100.00%
1 / 1
 3
 topTen
100.00%
5 / 5
100.00%
1 / 1
 2
 news
11.11%
3 / 27
0.00%
0 / 1
 80.23
 searches
100.00%
3 / 3
100.00%
1 / 1
 1
 contentHealth
100.00%
3 / 3
100.00%
1 / 1
 1
 getLayout
100.00%
3 / 3
100.00%
1 / 1
 1
 saveLayout
53.85%
7 / 13
0.00%
0 / 1
 7.46
 resetLayout
54.55%
6 / 11
0.00%
0 / 1
 7.35
 sanitizeLayout
0.00%
0 / 19
0.00%
0 / 1
 72
1<?php
2
3/**
4 * The Admin Dashboard Controller
5 *
6 * This Source Code Form is subject to the terms of the Mozilla Public License,
7 * v. 2.0. If a copy of the MPL was not distributed with this file, You can
8 * obtain one at https://mozilla.org/MPL/2.0/.
9 *
10 * @package   phpMyFAQ
11 * @author    Thorsten Rinne <thorsten@phpmyfaq.de>
12 * @copyright 2023-2026 phpMyFAQ Team
13 * @license   https://www.mozilla.org/MPL/2.0/ Mozilla Public License Version 2.0
14 * @link      https://www.phpmyfaq.de
15 * @since     2023-10-15
16 */
17
18declare(strict_types=1);
19
20namespace phpMyFAQ\Controller\Administration\Api;
21
22use Exception;
23use JsonException;
24use phpMyFAQ\Administration\DashboardLayout;
25use phpMyFAQ\Administration\Faq as AdminFaq;
26use phpMyFAQ\Administration\RemoteApiClient;
27use phpMyFAQ\Administration\Session as AdminSession;
28use phpMyFAQ\Controller\AbstractController;
29use phpMyFAQ\Enums\PermissionType;
30use phpMyFAQ\Faq;
31use phpMyFAQ\Search;
32use phpMyFAQ\Session\Token;
33use phpMyFAQ\System;
34use phpMyFAQ\Translation;
35use Psr\Cache\CacheItemPoolInterface;
36use Psr\Cache\InvalidArgumentException;
37use Symfony\Component\HttpClient\HttpClient;
38use Symfony\Component\HttpFoundation\JsonResponse;
39use Symfony\Component\HttpFoundation\Request;
40use Symfony\Component\HttpFoundation\Response;
41use Symfony\Component\Routing\Attribute\Route;
42use Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface;
43use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
44
45final class DashboardController extends AbstractController
46{
47    /**
48     * How long a cached remote response is considered fresh, in seconds.
49     */
50    private const REMOTE_CACHE_TTL = 3600;
51
52    /**
53     * How long a cached remote response is retained for stale-on-error fallback, in seconds.
54     */
55    private const REMOTE_CACHE_RETENTION = 86_400;
56
57    /**
58     * Widget keys that may appear in a stored dashboard layout. Anything else is dropped.
59     */
60    private const ALLOWED_WIDGETS = [
61        'inactive-faqs',
62        'recent-users',
63        'content-health',
64        'popular-searches',
65        'version-check',
66        'verification-check',
67        'backup-status',
68        'sponsor',
69        'support',
70    ];
71
72    public function __construct(
73        private readonly AdminSession $adminSession,
74        private readonly CacheItemPoolInterface $cache,
75    ) {
76        parent::__construct();
77    }
78
79    /**
80     * Returns a still-fresh cached payload for the given key, or null when none exists.
81     *
82     * @return array<string, mixed>|null
83     * @throws InvalidArgumentException
84     */
85    private function getFreshCache(string $key): ?array
86    {
87        $item = $this->cache->getItem($key);
88        if (!$item->isHit()) {
89            return null;
90        }
91
92        $cached = $item->get();
93        if (!is_array($cached) || !array_key_exists('fetchedAt', $cached) || !array_key_exists('payload', $cached)) {
94            return null;
95        }
96
97        if ((time() - (int) $cached['fetchedAt']) > self::REMOTE_CACHE_TTL) {
98            return null;
99        }
100
101        if (!is_array($cached['payload'])) {
102            return null;
103        }
104
105        /* @mago-expect analysis:less-specific-return-statement - the cache payload keys are re-validated by consumers */
106        return $cached['payload'];
107    }
108
109    /**
110     * Returns any cached payload for the given key regardless of age (stale-on-error fallback).
111     *
112     * @return array<string, mixed>|null
113     * @throws InvalidArgumentException
114     */
115    private function getStaleCache(string $key): ?array
116    {
117        $cached = $this->cache->getItem($key)->get();
118        if (is_array($cached) && array_key_exists('payload', $cached) && is_array($cached['payload'])) {
119            /* @mago-expect analysis:less-specific-return-statement - the cache payload keys are re-validated by consumers */
120            return $cached['payload'];
121        }
122
123        return null;
124    }
125
126    /**
127     * Stores a remote payload together with its fetch timestamp.
128     *
129     * @param array<string, mixed> $payload
130     * @throws InvalidArgumentException
131     */
132    private function storeCache(string $key, array $payload): void
133    {
134        $item = $this->cache->getItem($key);
135        $item->set(['fetchedAt' => time(), 'payload' => $payload]);
136        $item->expiresAfter(self::REMOTE_CACHE_RETENTION);
137        $this->cache->save($item);
138    }
139
140    /**
141     * @throws JsonException
142     */
143    #[Route(path: 'dashboard/verify', name: 'admin.api.dashboard.verify', methods: ['POST'])]
144    public function verify(Request $request): JsonResponse
145    {
146        $this->userHasPermission(PermissionType::CONFIGURATION_EDIT);
147
148        $data = $request->getContent();
149        $api = new RemoteApiClient($this->configuration, new System());
150
151        return $this->json($api->setRemoteHashes($data)->getVerificationIssues());
152    }
153
154    /**
155     * @throws Exception
156     */
157    #[Route(path: 'dashboard/versions', name: 'admin.api.dashboard.versions', methods: ['GET'])]
158    public function versions(): JsonResponse
159    {
160        $this->userHasPermission(PermissionType::CONFIGURATION_EDIT);
161
162        $releaseEnvironment = (string) $this->configuration->get(item: 'upgrade.releaseEnvironment');
163        $cacheKey = 'dashboard.versions.' . $releaseEnvironment;
164
165        $fresh = $this->getFreshCache($cacheKey);
166        if ($fresh !== null) {
167            return $this->json($fresh);
168        }
169
170        $api = new RemoteApiClient($this->configuration, new System());
171
172        try {
173            $versions = $api->getVersions();
174            if (!array_key_exists('installed', $versions) || !array_key_exists($releaseEnvironment, $versions)) {
175                throw new Exception('Version lookup failed for release environment "' . $releaseEnvironment . '".');
176            }
177
178            $info = [];
179            if (version_compare($versions['installed'], $versions[$releaseEnvironment]) < 0) {
180                $info = ['warning' => Translation::get(key: 'ad_you_should_update')];
181            }
182
183            if (version_compare($versions['installed'], $versions[$releaseEnvironment]) >= 0) {
184                $info = [
185                    'success' =>
186                        Translation::getString(key: 'ad_xmlrpc_latest') . ': phpMyFAQ ' . ($versions['stable'] ?? ''),
187                ];
188            }
189
190            $this->storeCache($cacheKey, $info);
191
192            return $this->json($info);
193        } catch (DecodingExceptionInterface|TransportExceptionInterface|Exception $exception) {
194            $stale = $this->getStaleCache($cacheKey);
195            if ($stale !== null) {
196                return $this->json($stale);
197            }
198
199            return $this->json(['error' => $exception->getMessage()], Response::HTTP_BAD_REQUEST);
200        }
201    }
202
203    /**
204     * @throws Exception
205     */
206    #[Route(path: 'dashboard/visits', name: 'admin.api.dashboard.visits', methods: ['GET'])]
207    public function visits(Request $request): JsonResponse
208    {
209        $this->userHasPermission(PermissionType::STATISTICS_VIEWLOGS);
210
211        if ($this->configuration->get(item: 'main.enableUserTracking')) {
212            $requestTime = (int) $request->server->get('REQUEST_TIME');
213            $endDate = $requestTime !== 0 ? $requestTime : time();
214            $days = (int) $request->query->get('days', 30);
215            $days = max(7, min($days, 365));
216            return $this->json($this->adminSession->getVisitsForDays($endDate, $days));
217        }
218
219        return $this->json(['error' => 'User tracking is disabled.'], 400);
220    }
221
222    /**
223     * @throws Exception
224     */
225    #[Route(path: 'dashboard/topten', name: 'admin.api.dashboard.topten', methods: ['GET'])]
226    public function topTen(): JsonResponse
227    {
228        $this->userHasPermission(PermissionType::STATISTICS_VIEWLOGS);
229
230        if ($this->configuration->get(item: 'main.enableUserTracking')) {
231            $faqStatistics = new Faq\Statistics($this->configuration);
232            return $this->json($faqStatistics->getTopTenData());
233        }
234
235        return $this->json(['error' => 'User tracking is disabled.'], 400);
236    }
237
238    /**
239     * @throws Exception
240     */
241    #[Route(path: 'dashboard/news', name: 'admin.api.dashboard.news', methods: ['GET'])]
242    public function news(): JsonResponse
243    {
244        $this->userIsAuthenticated();
245
246        if (!$this->configuration->get(item: 'main.enableRecentNews')) {
247            return $this->json(['error' => 'Recent news is disabled.'], Response::HTTP_FORBIDDEN);
248        }
249
250        $cacheKey = 'dashboard.news';
251
252        $fresh = $this->getFreshCache($cacheKey);
253        if ($fresh !== null) {
254            return $this->json($fresh);
255        }
256
257        try {
258            $httpClient = HttpClient::create(['max_redirects' => 2, 'timeout' => 10]);
259            $response = $httpClient->request('GET', 'https://www.phpmyfaq.de/api/news/recent');
260
261            if ($response->getStatusCode() === Response::HTTP_OK) {
262                $data = $response->toArray(throw: false);
263                if (array_key_exists('news', $data) && is_array($data['news'])) {
264                    $data['news'] = array_slice($data['news'], offset: 0, length: 5);
265                }
266
267                $payload = [];
268                foreach ($data as $payloadKey => $payloadValue) {
269                    $payload[(string) $payloadKey] = $payloadValue;
270                }
271
272                $this->storeCache($cacheKey, $payload);
273
274                return $this->json($data);
275            }
276
277            $stale = $this->getStaleCache($cacheKey);
278            if ($stale !== null) {
279                return $this->json($stale);
280            }
281
282            return $this->json(['error' => 'Failed to fetch news.'], Response::HTTP_BAD_GATEWAY);
283        } catch (TransportExceptionInterface $exception) {
284            $stale = $this->getStaleCache($cacheKey);
285            if ($stale !== null) {
286                return $this->json($stale);
287            }
288
289            return $this->json(['error' => $exception->getMessage()], Response::HTTP_BAD_GATEWAY);
290        }
291    }
292
293    /**
294     * Returns the most popular search terms of the last 30 days.
295     *
296     * @throws Exception
297     */
298    #[Route(path: 'dashboard/searches', name: 'admin.api.dashboard.searches', methods: ['GET'])]
299    public function searches(): JsonResponse
300    {
301        $this->userIsAuthenticated();
302
303        $search = new Search($this->configuration);
304
305        return $this->json($search->getMostPopularSearches(numResults: 7, withLang: false, timeWindow: 30));
306    }
307
308    /**
309     * Returns aggregated content health counters (orphaned and stale FAQs).
310     *
311     * @throws Exception
312     */
313    #[Route(path: 'dashboard/content-health', name: 'admin.api.dashboard.content-health', methods: ['GET'])]
314    public function contentHealth(): JsonResponse
315    {
316        $this->userIsAuthenticated();
317
318        $faq = new AdminFaq($this->configuration);
319
320        return $this->json($faq->getContentHealthStatistics());
321    }
322
323    /**
324     * Returns the stored dashboard widget layout of the current admin user.
325     *
326     * @throws Exception
327     */
328    #[Route(path: 'dashboard/layout', name: 'admin.api.dashboard.layout.get', methods: ['GET'])]
329    public function getLayout(): JsonResponse
330    {
331        $this->userIsAuthenticated();
332
333        $dashboardLayout = new DashboardLayout($this->configuration);
334
335        return $this->json(['config' => $dashboardLayout->get($this->currentUser->getUserId())]);
336    }
337
338    /**
339     * Persists the dashboard widget layout of the current admin user.
340     *
341     * @throws Exception
342     */
343    #[Route(path: 'dashboard/layout', name: 'admin.api.dashboard.layout.save', methods: ['POST'])]
344    public function saveLayout(Request $request): JsonResponse
345    {
346        $this->userIsAuthenticated();
347
348        $data = json_decode($request->getContent());
349        if (!is_object($data)) {
350            return $this->json(['error' => 'Invalid request body.'], Response::HTTP_BAD_REQUEST);
351        }
352
353        $csrfToken = is_string($data->csrfToken ?? null) ? $data->csrfToken : null;
354        if (!Token::getInstance($this->session)->verifyToken('dashboard', $csrfToken)) {
355            return $this->json(['error' => Translation::get(key: 'msgNoPermission')], Response::HTTP_UNAUTHORIZED);
356        }
357
358        $dashboardLayout = new DashboardLayout($this->configuration);
359        $config = $this->sanitizeLayout($data->config ?? null);
360        $saved = $dashboardLayout->save($this->currentUser->getUserId(), $config);
361
362        if (!$saved) {
363            return $this->json(['error' => 'Could not save layout.'], Response::HTTP_INTERNAL_SERVER_ERROR);
364        }
365
366        return $this->json(['success' => true, 'config' => $config]);
367    }
368
369    /**
370     * Removes the stored layout of the current admin user, reverting to the default.
371     *
372     * @throws Exception
373     */
374    #[Route(path: 'dashboard/layout/reset', name: 'admin.api.dashboard.layout.reset', methods: ['POST'])]
375    public function resetLayout(Request $request): JsonResponse
376    {
377        $this->userIsAuthenticated();
378
379        $data = json_decode($request->getContent());
380        if (!is_object($data)) {
381            return $this->json(['error' => 'Invalid request body.'], Response::HTTP_BAD_REQUEST);
382        }
383
384        $csrfToken = is_string($data->csrfToken ?? null) ? $data->csrfToken : null;
385        if (!Token::getInstance($this->session)->verifyToken('dashboard', $csrfToken)) {
386            return $this->json(['error' => Translation::get(key: 'msgNoPermission')], Response::HTTP_UNAUTHORIZED);
387        }
388
389        $dashboardLayout = new DashboardLayout($this->configuration);
390        if (!$dashboardLayout->reset($this->currentUser->getUserId())) {
391            return $this->json(['error' => 'Could not reset layout.'], Response::HTTP_INTERNAL_SERVER_ERROR);
392        }
393
394        return $this->json(['success' => true]);
395    }
396
397    /**
398     * Validates an untrusted layout payload, keeping only known widgets and a clean shape.
399     *
400     * @return array<int, array{key: string, position: int, visible: bool}>
401     */
402    private function sanitizeLayout(mixed $config): array
403    {
404        if (!is_array($config)) {
405            return [];
406        }
407
408        $clean = [];
409        $seen = [];
410        $position = 0;
411
412        foreach ($config as $entry) {
413            $key = is_object($entry) ? $entry->key ?? null : null;
414            if (
415                !is_string($key)
416                || !in_array($key, self::ALLOWED_WIDGETS, strict: true)
417                || array_key_exists($key, $seen)
418            ) {
419                continue;
420            }
421
422            $seen[$key] = true;
423            $visible = is_object($entry) ? $entry->visible ?? true : true;
424            $clean[] = [
425                'key' => $key,
426                'position' => $position++,
427                'visible' => (bool) $visible,
428            ];
429        }
430
431        return $clean;
432    }
433}