diff options
Diffstat (limited to 'apps/theming/lib')
| -rw-r--r-- | apps/theming/lib/Capabilities.php | 20 | ||||
| -rw-r--r-- | apps/theming/lib/Controller/IconController.php | 26 | ||||
| -rw-r--r-- | apps/theming/lib/Controller/ThemingController.php | 37 | ||||
| -rw-r--r-- | apps/theming/lib/Controller/UserThemeController.php | 44 | ||||
| -rw-r--r-- | apps/theming/lib/ResponseDefinitions.php | 36 |
5 files changed, 143 insertions, 20 deletions
diff --git a/apps/theming/lib/Capabilities.php b/apps/theming/lib/Capabilities.php index 5c063715f43..fbb287aa410 100644 --- a/apps/theming/lib/Capabilities.php +++ b/apps/theming/lib/Capabilities.php @@ -7,6 +7,7 @@ * @author Julien Veyssier <eneiluj@posteo.net> * @author Julius Härtl <jus@bitgrid.net> * @author Morris Jobke <hey@morrisjobke.de> + * @author Kate Döen <kate.doeen@nextcloud.com> * * @license GNU AGPL version 3 or any later version * @@ -64,6 +65,25 @@ class Capabilities implements IPublicCapability { /** * Return this classes capabilities + * + * @return array{ + * theming: array{ + * name: string, + * url: string, + * slogan: string, + * color: string, + * color-text: string, + * color-element: string, + * color-element-bright: string, + * color-element-dark: string, + * logo: string, + * background: string, + * background-plain: bool, + * background-default: bool, + * logoheader: string, + * favicon: string, + * }, + * } */ public function getCapabilities() { $backgroundLogo = $this->config->getAppValue('theming', 'backgroundMime', ''); diff --git a/apps/theming/lib/Controller/IconController.php b/apps/theming/lib/Controller/IconController.php index 1b16293a7f3..86b45fbbc03 100644 --- a/apps/theming/lib/Controller/IconController.php +++ b/apps/theming/lib/Controller/IconController.php @@ -8,6 +8,7 @@ * @author Julius Härtl <jus@bitgrid.net> * @author Michael Weimann <mail@michael-weimann.eu> * @author Roeland Jago Douma <roeland@famdouma.nl> + * @author Kate Döen <kate.doeen@nextcloud.com> * * @license GNU AGPL version 3 or any later version * @@ -80,10 +81,15 @@ class IconController extends Controller { * @PublicPage * @NoCSRFRequired * - * @param $app string app name - * @param $image string image file name (svg required) - * @return FileDisplayResponse|NotFoundResponse + * Get a themed icon + * + * @param string $app ID of the app + * @param string $image image file name (svg required) + * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: 'image/svg+xml'}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}> * @throws \Exception + * + * 200: Themed icon returned + * 404: Themed icon not found */ public function getThemedIcon(string $app, string $image): Response { $color = $this->themingDefaults->getColorPrimary(); @@ -107,9 +113,12 @@ class IconController extends Controller { * @PublicPage * @NoCSRFRequired * - * @param $app string app name - * @return FileDisplayResponse|DataDisplayResponse|NotFoundResponse + * @param string $app ID of the app + * @return DataDisplayResponse<Http::STATUS_OK, array{Content-Type: 'image/x-icon'}>|FileDisplayResponse<Http::STATUS_OK, array{Content-Type: 'image/x-icon'}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}> * @throws \Exception + * + * 200: Favicon returned + * 404: Favicon not found */ public function getFavicon(string $app = 'core'): Response { $response = null; @@ -146,9 +155,12 @@ class IconController extends Controller { * @PublicPage * @NoCSRFRequired * - * @param $app string app name - * @return DataDisplayResponse|FileDisplayResponse|NotFoundResponse + * @param string $app ID of the app + * @return DataDisplayResponse<Http::STATUS_OK, array{Content-Type: 'image/png'}>|FileDisplayResponse<Http::STATUS_OK, array{Content-Type: 'image/x-icon'|'image/png'}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}> * @throws \Exception + * + * 200: Touch icon returned + * 404: Touch icon not found */ public function getTouchIcon(string $app = 'core'): Response { $response = null; diff --git a/apps/theming/lib/Controller/ThemingController.php b/apps/theming/lib/Controller/ThemingController.php index c247f2c9d56..33af2b72183 100644 --- a/apps/theming/lib/Controller/ThemingController.php +++ b/apps/theming/lib/Controller/ThemingController.php @@ -18,6 +18,7 @@ * @author Robin Appelman <robin@icewind.nl> * @author Roeland Jago Douma <roeland@famdouma.nl> * @author Thomas Citharel <nextcloud@tcit.fr> + * @author Kate Döen <kate.doeen@nextcloud.com> * * @license GNU AGPL version 3 or any later version * @@ -46,6 +47,7 @@ use OCP\AppFramework\Http; use OCP\AppFramework\Http\DataDisplayResponse; use OCP\AppFramework\Http\DataResponse; use OCP\AppFramework\Http\FileDisplayResponse; +use OCP\AppFramework\Http\JSONResponse; use OCP\AppFramework\Http\NotFoundResponse; use OCP\Files\IAppData; use OCP\Files\NotFoundException; @@ -314,10 +316,15 @@ class ThemingController extends Controller { * @NoCSRFRequired * @NoSameSiteCookieRequired * - * @param string $key - * @param bool $useSvg - * @return FileDisplayResponse|NotFoundResponse + * Get an image + * + * @param string $key Key of the image + * @param bool $useSvg Return image as SVG + * @return FileDisplayResponse<Http::STATUS_OK, array{}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}> * @throws NotPermittedException + * + * 200: Image returned + * 404: Image not found */ public function getImage(string $key, bool $useSvg = true) { try { @@ -347,7 +354,15 @@ class ThemingController extends Controller { * @NoSameSiteCookieRequired * @NoTwoFactorRequired * - * @return DataDisplayResponse|NotFoundResponse + * Get the CSS stylesheet for a theme + * + * @param string $themeId ID of the theme + * @param bool $plain Let the browser decide the CSS priority + * @param bool $withCustomCss Include custom CSS + * @return DataDisplayResponse<Http::STATUS_OK, array{Content-Type: 'text/css'}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}> + * + * 200: Stylesheet returned + * 404: Theme not found */ public function getThemeStylesheet(string $themeId, bool $plain = false, bool $withCustomCss = false) { $themes = $this->themesService->getThemes(); @@ -387,9 +402,13 @@ class ThemingController extends Controller { * @NoCSRFRequired * @PublicPage * - * @return Http\JSONResponse + * Get the manifest for an app + * + * @param string $app ID of the app + * @psalm-suppress LessSpecificReturnStatement The content of the Manifest doesn't need to be described in the return type + * @return JSONResponse<Http::STATUS_OK, array{name: string, short_name: string, start_url: string, theme_color: string, background_color: string, description: string, icons: array{src: non-empty-string, type: string, sizes: string}[], display: string}, array{}> */ - public function getManifest($app) { + public function getManifest(string $app) { $cacheBusterValue = $this->config->getAppValue('theming', 'cachebuster', '0'); if ($app === 'core' || $app === 'settings') { $name = $this->themingDefaults->getName(); @@ -407,6 +426,10 @@ class ThemingController extends Controller { } $description = $info['summary'] ?? ''; } + /** + * @var string $description + * @var string $shortName + */ $responseJS = [ 'name' => $name, 'short_name' => $shortName, @@ -431,7 +454,7 @@ class ThemingController extends Controller { ], 'display' => 'standalone' ]; - $response = new Http\JSONResponse($responseJS); + $response = new JSONResponse($responseJS); $response->cacheFor(3600); return $response; } diff --git a/apps/theming/lib/Controller/UserThemeController.php b/apps/theming/lib/Controller/UserThemeController.php index 6a58366c4f6..e0279bec149 100644 --- a/apps/theming/lib/Controller/UserThemeController.php +++ b/apps/theming/lib/Controller/UserThemeController.php @@ -11,6 +11,7 @@ declare(strict_types=1); * @author Janis Köhr <janis.koehr@novatec-gmbh.de> * @author John Molakvoæ <skjnldsv@protonmail.com> * @author Roeland Jago Douma <roeland@famdouma.nl> + * @author Kate Döen <kate.doeen@nextcloud.com> * * @license GNU AGPL version 3 or any later version * @@ -32,6 +33,7 @@ namespace OCA\Theming\Controller; use OCA\Theming\AppInfo\Application; use OCA\Theming\ITheme; +use OCA\Theming\ResponseDefinitions; use OCA\Theming\Service\BackgroundService; use OCA\Theming\Service\ThemesService; use OCA\Theming\ThemingDefaults; @@ -48,10 +50,13 @@ use OCP\IRequest; use OCP\IUserSession; use OCP\PreConditionNotMetException; +/** + * @psalm-import-type ThemingBackground from ResponseDefinitions + */ class UserThemeController extends OCSController { protected ?string $userId = null; - + private IConfig $config; private IUserSession $userSession; private ThemesService $themesService; @@ -84,8 +89,11 @@ class UserThemeController extends OCSController { * Enable theme * * @param string $themeId the theme ID - * @return DataResponse - * @throws OCSBadRequestException|PreConditionNotMetException + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> + * @throws OCSBadRequestException Enabling theme is not possible + * @throws PreConditionNotMetException + * + * 200: Theme enabled successfully */ public function enableTheme(string $themeId): DataResponse { $theme = $this->validateTheme($themeId); @@ -101,8 +109,11 @@ class UserThemeController extends OCSController { * Disable theme * * @param string $themeId the theme ID - * @return DataResponse - * @throws OCSBadRequestException|PreConditionNotMetException + * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> + * @throws OCSBadRequestException Disabling theme is not possible + * @throws PreConditionNotMetException + * + * 200: Theme disabled successfully */ public function disableTheme(string $themeId): DataResponse { $theme = $this->validateTheme($themeId); @@ -119,7 +130,8 @@ class UserThemeController extends OCSController { * * @param string $themeId the theme ID * @return ITheme - * @throws OCSBadRequestException|PreConditionNotMetException + * @throws OCSBadRequestException + * @throws PreConditionNotMetException */ private function validateTheme(string $themeId): ITheme { if ($themeId === '' || !$themeId) { @@ -143,6 +155,12 @@ class UserThemeController extends OCSController { /** * @NoAdminRequired * @NoCSRFRequired + * + * Get the background image + * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}> + * + * 200: Background image returned + * 404: Background image not found */ public function getBackground(): Http\Response { $file = $this->backgroundService->getBackground(); @@ -156,6 +174,10 @@ class UserThemeController extends OCSController { /** * @NoAdminRequired + * + * Delete the background + * + * @return JSONResponse<Http::STATUS_OK, ThemingBackground, array{}> */ public function deleteBackground(): JSONResponse { $currentVersion = (int)$this->config->getUserValue($this->userId, Application::APP_ID, 'userCacheBuster', '0'); @@ -169,6 +191,16 @@ class UserThemeController extends OCSController { /** * @NoAdminRequired + * + * Set the background + * + * @param string $type Type of background + * @param string $value Path of the background image + * @param string|null $color Color for the background + * @return JSONResponse<Http::STATUS_OK, ThemingBackground, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_INTERNAL_SERVER_ERROR, array{error: string}, array{}> + * + * 200: Background set successfully + * 400: Setting background is not possible */ public function setBackground(string $type = BackgroundService::BACKGROUND_DEFAULT, string $value = '', string $color = null): JSONResponse { $currentVersion = (int)$this->config->getUserValue($this->userId, Application::APP_ID, 'userCacheBuster', '0'); diff --git a/apps/theming/lib/ResponseDefinitions.php b/apps/theming/lib/ResponseDefinitions.php new file mode 100644 index 00000000000..ddd8615e455 --- /dev/null +++ b/apps/theming/lib/ResponseDefinitions.php @@ -0,0 +1,36 @@ +<?php +declare(strict_types=1); + +/** + * @copyright Copyright (c) 2023 Kate Döen <kate.doeen@nextcloud.com> + * + * @author Kate Döen <kate.doeen@nextcloud.com> + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + * + */ + +namespace OCA\Theming; + +/** + * @psalm-type ThemingBackground = array{ + * backgroundImage: ?string, + * backgroundColor: string, + * version: int, + * } + */ +class ResponseDefinitions { +} |