` query
- * parameter overrides the user's Nextcloud locale; in strict mode
- * an unknown explicit lang returns 404 instead of falling back.
- * REQ-DASH-039.
- *
- * Response shape:
- * - `dashboard`: the dashboard entity payload
- * - `translation`: the matched translation row
- * - `availableLanguages`: sorted list of codes
- * - `currentLanguage`: the matched code
- * - `isFallback`: true when the primary fallback was used
- *
- * @param string $uuid The dashboard UUID.
- *
- * @return JSONResponse The resolved payload.
- *
- * @spec openspec/specs/dashboard-language-content/spec.md
- */
- #[NoAdminRequired]
- public function resolved(string $uuid): JSONResponse
- {
- $user = $this->userSession->getUser();
- if ($this->userId === null || $user === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- try {
- $this->actionAuth->requireAction($user, 'dashboard-translation.resolved');
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- try {
- $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: [
- 'status' => 'error',
- 'error' => 'not_found',
- ],
- statusCode: Http::STATUS_NOT_FOUND
- );
- }
-
- $variant = $this->resolveVariant(
- uuid: $uuid,
- dashboard: $dashboard,
- explicitLang: $this->request->getParam(key: 'lang')
- );
-
- // Only the strict explicit-lang path yields null; the locale path
- // always materialises a variant. REQ-DASH-039 strict scenario.
- if ($variant === null) {
- return new JSONResponse(
- data: [
- 'status' => 'error',
- 'error' => 'language_not_available',
- ],
- statusCode: Http::STATUS_NOT_FOUND
- );
- }
-
- return ResponseHelper::success(
- data: [
- 'dashboard' => $dashboard->jsonSerialize(),
- 'translation' => $variant['translation']->jsonSerialize(),
- 'availableLanguages' => $this->resolveAvailableLanguages(
- uuid: $uuid,
- variant: $variant
- ),
- 'currentLanguage' => $variant['translation']->getLanguageCode(),
- 'isFallback' => $variant['isFallback'],
- ]
- );
- }//end resolved()
-
- /**
- * Resolve the translation variant this request should render.
- *
- * A usable `?lang=` query parameter selects the strict exact-match
- * path (which may report "no such language" by returning null); its
- * absence — or a blank / non-string value — selects the viewer's own
- * locale, which always yields a variant. REQ-DASH-039.
- *
- * @param string $uuid The dashboard UUID.
- * @param Dashboard $dashboard The dashboard entity (legacy source).
- * @param mixed $explicitLang The raw `lang` query parameter.
- *
- * @return array{translation: mixed, isFallback: bool}|null The variant,
- * or null.
- */
- private function resolveVariant(
- string $uuid,
- Dashboard $dashboard,
- mixed $explicitLang
- ): ?array {
- if (is_string($explicitLang) === false || $explicitLang === '') {
- return $this->resolveLocaleVariant(uuid: $uuid, dashboard: $dashboard);
- }
-
- return $this->resolveExactVariant(uuid: $uuid, explicitLang: $explicitLang);
- }//end resolveVariant()
-
- /**
- * Resolve a variant that matches the requested code exactly.
- *
- * Strict mode for the explicit `?lang=` parameter — when no exact
- * match exists for the requested code the caller must return 404
- * instead of the primary-fallback envelope, so a near-miss (the
- * service's own fallback) is reported as "no match" here.
- * REQ-DASH-039 strict scenario.
- *
- * @param string $uuid The dashboard UUID.
- * @param string $explicitLang The requested language code.
- *
- * @return array{translation: mixed, isFallback: bool}|null The exact
- * match, or
- * null.
- */
- private function resolveExactVariant(string $uuid, string $explicitLang): ?array
- {
- $variant = $this->translationService->resolveForLocale(
- dashboardUuid: $uuid,
- preferredLanguage: $explicitLang
- );
-
- $requested = DashboardTranslationMapper::normaliseLanguageCode(
- raw: $explicitLang
- );
- $matched = null;
- if ($variant !== null) {
- $matched = (string) $variant['translation']->getLanguageCode();
- }
-
- if ($matched !== $requested) {
- return null;
- }
-
- return $variant;
- }//end resolveExactVariant()
-
- /**
- * Resolve the variant for the viewer's own locale.
- *
- * Legacy fallback — dashboards predating REQ-DASH-038 may have no
- * translation rows yet. Materialise an in-memory variant from the
- * dashboard's own fields so the response envelope shape stays
- * uniform. REQ-DASH-044.
- *
- * @param string $uuid The dashboard UUID.
- * @param Dashboard $dashboard The dashboard entity (legacy source).
- *
- * @return array{translation: mixed, isFallback: bool} The variant.
- */
- private function resolveLocaleVariant(string $uuid, Dashboard $dashboard): array
- {
- $variant = $this->translationService->resolveForLocale(
- dashboardUuid: $uuid,
- preferredLanguage: ''
- );
-
- if ($variant !== null) {
- return $variant;
- }
-
- return [
- 'translation' => $this->translationService
- ->materialiseLegacyVariant(dashboard: $dashboard),
- 'isFallback' => true,
- ];
- }//end resolveLocaleVariant()
-
- /**
- * List the language codes offered for this dashboard.
- *
- * A dashboard with no stored translation rows still advertises the
- * one code the resolved variant carries, so the language switcher is
- * never empty when content is being shown.
- *
- * @param string $uuid The dashboard UUID.
- * @param array{translation: mixed, isFallback: bool} $variant The resolved variant.
- *
- * @return array The available codes.
- */
- private function resolveAvailableLanguages(string $uuid, array $variant): array
- {
- $available = $this->translationService->listAvailableLanguages(
- dashboardUuid: $uuid
- );
- if (count($available) > 0) {
- return $available;
- }
-
- $code = (string) $variant['translation']->getLanguageCode();
- if ($code === '') {
- return $available;
- }
-
- return [$code];
- }//end resolveAvailableLanguages()
-
- /**
- * Look up the dashboard and verify the current user is the owner.
- *
- * Returns null when the check passes; an HTTP 403 / 404 envelope
- * when it fails. Group-shared dashboards are not addressable via
- * the personal-scope translation endpoints — they short-circuit to
- * 403 (the group-scoped translation flow lives separately).
- *
- * @param string $uuid The dashboard UUID.
- *
- * @return JSONResponse|null The error envelope or null on success.
- */
- private function assertOwner(string $uuid): ?JSONResponse
- {
- try {
- $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: [
- 'status' => 'error',
- 'error' => 'not_found',
- ],
- statusCode: Http::STATUS_NOT_FOUND
- );
- }
-
- if ($dashboard->getUserId() !== $this->userId) {
- return ResponseHelper::forbidden();
- }
-
- return null;
- }//end assertOwner()
-
- /**
- * Build the patch payload from individual nullable parameters.
- *
- * `null` means "not in payload" (skip the key); anything else (incl.
- * the empty string) means "set it explicitly". The service then
- * inspects key presence with `array_key_exists`.
- *
- * @param string|null $name The new name.
- * @param string|null $description The new description.
- * @param string|null $widgetTreeJson The new widget tree JSON.
- *
- * @return array The patch payload.
- */
- private function buildPatch(
- ?string $name,
- ?string $description,
- ?string $widgetTreeJson
- ): array {
- $patch = [];
- if ($name !== null) {
- $patch['name'] = $name;
- }
-
- if ($description !== null) {
- $patch['description'] = $description;
- }
-
- if ($widgetTreeJson !== null) {
- $patch['widgetTreeJson'] = $widgetTreeJson;
- }
-
- return $patch;
- }//end buildPatch()
+class DashboardTranslationApiController extends Controller {
+ /**
+ * Constructor
+ *
+ * @param IRequest $request The request.
+ * @param DashboardMapper $dashboardMapper Dashboard mapper
+ * (used for the
+ * ownership check
+ * before any
+ * translation
+ * mutation).
+ * @param DashboardTranslationService $translationService Translation
+ * service.
+ * @param ActionAuthService $actionAuth ADR-023 action
+ * authorization.
+ * @param IUserSession $userSession User session
+ * (IUser resolution).
+ * @param string|null $userId The user ID.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly DashboardMapper $dashboardMapper,
+ private readonly DashboardTranslationService $translationService,
+ private readonly ActionAuthService $actionAuth,
+ private readonly IUserSession $userSession,
+ private readonly ?string $userId,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
+
+ /**
+ * GET /api/dashboards/{uuid}/translations — list every translation
+ * variant for a dashboard. Returns 403 when the dashboard belongs
+ * to another user. REQ-DASH-038.
+ *
+ * @param string $uuid The dashboard UUID.
+ *
+ * @return JSONResponse The list payload.
+ *
+ * @spec openspec/specs/dashboard-language-content/spec.md
+ */
+ #[NoAdminRequired]
+ public function list(string $uuid): JSONResponse {
+ $user = $this->userSession->getUser();
+ if ($this->userId === null || $user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'dashboard-translation.list');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ $ownerCheck = $this->assertOwner(uuid: $uuid);
+ if ($ownerCheck !== null) {
+ return $ownerCheck;
+ }
+
+ $variants = $this->translationService->listVariants(
+ dashboardUuid: $uuid
+ );
+
+ $serialized = ResponseHelper::serializeList(entities: $variants);
+
+ return ResponseHelper::success(
+ data: ['translations' => $serialized]
+ );
+ }//end list()
+
+ /**
+ * POST /api/dashboards/{uuid}/translations — create a new variant.
+ *
+ * Body: `{languageCode, name?, description?, widgetTreeJson?, copyFrom?}`.
+ * Returns 201 with the created entity. Maps duplicate-language
+ * conflicts to HTTP 409. REQ-DASH-040.
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param string|null $languageCode The language code from the body.
+ * @param string|null $name The optional name.
+ * @param string|null $description The optional description.
+ * @param string|null $widgetTreeJson The optional widget tree JSON.
+ * @param string|null $copyFrom Optional source language.
+ *
+ * @return JSONResponse The created variant.
+ *
+ * @spec openspec/specs/dashboard-language-content/spec.md
+ */
+ #[NoAdminRequired]
+ public function create(
+ string $uuid,
+ ?string $languageCode = null,
+ ?string $name = null,
+ ?string $description = null,
+ ?string $widgetTreeJson = null,
+ ?string $copyFrom = null,
+ ): JSONResponse {
+ $user = $this->userSession->getUser();
+ if ($this->userId === null || $user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'dashboard-translation.create');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ $ownerCheck = $this->assertOwner(uuid: $uuid);
+ if ($ownerCheck !== null) {
+ return $ownerCheck;
+ }
+
+ if ($this->isBlank(value: $languageCode) === true) {
+ return self::invalidArgument(
+ message: DashboardTranslationService::ERR_INVALID_LANGUAGE
+ );
+ }
+
+ try {
+ $variant = $this->translationService->createVariant(
+ dashboardUuid: $uuid,
+ languageCode: (string)$languageCode,
+ name: $name,
+ description: $description,
+ widgetTreeJson: $widgetTreeJson,
+ copyFromLanguage: $copyFrom
+ );
+
+ return new JSONResponse(
+ data: ['translation' => $variant->jsonSerialize()],
+ statusCode: Http::STATUS_CREATED
+ );
+ } catch (InvalidArgumentException $e) {
+ return self::invalidArgument(message: $e->getMessage());
+ } catch (Exception $e) {
+ return $this->mapCreateFailure(exception: $e);
+ }//end try
+ }//end create()
+
+ /**
+ * Test whether an optional string parameter carries no value.
+ *
+ * A missing body key arrives as `null` and an explicitly blank one as
+ * `''`; both are rejected identically by the create endpoint.
+ *
+ * @param string|null $value The parameter value.
+ *
+ * @return bool True when the parameter carries no value.
+ */
+ private function isBlank(?string $value): bool {
+ return ($value === null || $value === '');
+ }//end isBlank()
+
+ /**
+ * Build the shared HTTP 400 invalid-argument envelope.
+ *
+ * @param string $message The validation message.
+ *
+ * @return JSONResponse The 400 response.
+ */
+ private static function invalidArgument(string $message): JSONResponse {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'invalid_argument',
+ 'message' => $message,
+ ],
+ statusCode: Http::STATUS_BAD_REQUEST
+ );
+ }//end invalidArgument()
+
+ /**
+ * Map a create-variant failure onto its HTTP envelope.
+ *
+ * A duplicate-language collision is the one domain failure with a
+ * dedicated status (HTTP 409); everything else falls through to the
+ * generic error envelope. REQ-DASH-040.
+ *
+ * @param Exception $exception The failure thrown by the service.
+ *
+ * @return JSONResponse The mapped response.
+ */
+ private function mapCreateFailure(Exception $exception): JSONResponse {
+ if ($exception->getMessage() === DashboardTranslationService::ERR_LANGUAGE_EXISTS) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'language_exists',
+ 'message' => $exception->getMessage(),
+ ],
+ statusCode: Http::STATUS_CONFLICT
+ );
+ }
+
+ return ResponseHelper::error(exception: $exception);
+ }//end mapCreateFailure()
+
+ /**
+ * PUT /api/dashboards/{uuid}/translations/{lang} — update a variant.
+ *
+ * Body: `{name?, description?, widgetTreeJson?}`. Returns 200 with
+ * the updated entity. REQ-DASH-041.
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param string $lang The language code from the URL.
+ * @param string|null $name Optional new name.
+ * @param string|null $description Optional new description.
+ * @param string|null $widgetTreeJson Optional new widget tree JSON.
+ *
+ * @return JSONResponse The updated variant.
+ *
+ * @spec openspec/specs/dashboard-language-content/spec.md
+ */
+ #[NoAdminRequired]
+ public function update(
+ string $uuid,
+ string $lang,
+ ?string $name = null,
+ ?string $description = null,
+ ?string $widgetTreeJson = null,
+ ): JSONResponse {
+ $user = $this->userSession->getUser();
+ if ($this->userId === null || $user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'dashboard-translation.update');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ $ownerCheck = $this->assertOwner(uuid: $uuid);
+ if ($ownerCheck !== null) {
+ return $ownerCheck;
+ }
+
+ $patch = $this->buildPatch(
+ name: $name,
+ description: $description,
+ widgetTreeJson: $widgetTreeJson
+ );
+
+ try {
+ $variant = $this->translationService->updateVariant(
+ dashboardUuid: $uuid,
+ languageCode: $lang,
+ patch: $patch
+ );
+
+ return ResponseHelper::success(
+ data: ['translation' => $variant->jsonSerialize()]
+ );
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'not_found',
+ ],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ } catch (Exception $e) {
+ return ResponseHelper::error(exception: $e);
+ }//end try
+ }//end update()
+
+ /**
+ * DELETE /api/dashboards/{uuid}/translations/{lang} — delete a
+ * variant. Maps last-variant / primary-variant guards to HTTP 400.
+ * REQ-DASH-042.
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param string $lang The language code from the URL.
+ *
+ * @return JSONResponse The status payload.
+ *
+ * @spec openspec/specs/dashboard-language-content/spec.md
+ */
+ #[NoAdminRequired]
+ public function destroy(string $uuid, string $lang): JSONResponse {
+ $user = $this->userSession->getUser();
+ if ($this->userId === null || $user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'dashboard-translation.destroy');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ $ownerCheck = $this->assertOwner(uuid: $uuid);
+ if ($ownerCheck !== null) {
+ return $ownerCheck;
+ }
+
+ try {
+ $this->translationService->deleteVariant(
+ dashboardUuid: $uuid,
+ languageCode: $lang
+ );
+
+ return ResponseHelper::success(data: ['status' => 'ok']);
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'not_found',
+ ],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ } catch (Exception $e) {
+ $errorCode = 'invalid_state';
+ if ($e->getMessage() === DashboardTranslationService::ERR_LAST_VARIANT) {
+ $errorCode = 'last_variant';
+ } elseif ($e->getMessage() === DashboardTranslationService::ERR_DELETE_PRIMARY) {
+ $errorCode = 'primary_variant';
+ }
+
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => $errorCode,
+ 'message' => $e->getMessage(),
+ ],
+ statusCode: Http::STATUS_BAD_REQUEST
+ );
+ }//end try
+ }//end destroy()
+
+ /**
+ * POST /api/dashboards/{uuid}/translations/{lang}/set-primary —
+ * promote a variant to primary. Idempotent. REQ-DASH-043.
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param string $lang The language code from the URL.
+ *
+ * @return JSONResponse The promoted variant.
+ *
+ * @spec openspec/specs/dashboard-language-content/spec.md
+ */
+ #[NoAdminRequired]
+ public function setPrimary(string $uuid, string $lang): JSONResponse {
+ $user = $this->userSession->getUser();
+ if ($this->userId === null || $user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'dashboard-translation.set-primary');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ $ownerCheck = $this->assertOwner(uuid: $uuid);
+ if ($ownerCheck !== null) {
+ return $ownerCheck;
+ }
+
+ try {
+ $variant = $this->translationService->promoteVariantToPrimary(
+ dashboardUuid: $uuid,
+ languageCode: $lang
+ );
+
+ return ResponseHelper::success(
+ data: ['translation' => $variant->jsonSerialize()]
+ );
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'not_found',
+ ],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ } catch (Exception $e) {
+ return ResponseHelper::error(exception: $e);
+ }
+ }//end setPrimary()
+
+ /**
+ * GET /api/dashboards/{uuid}/resolved — resolve the dashboard's
+ * content for the viewer's locale. Optional `?lang=` query
+ * parameter overrides the user's Nextcloud locale; in strict mode
+ * an unknown explicit lang returns 404 instead of falling back.
+ * REQ-DASH-039.
+ *
+ * Response shape:
+ * - `dashboard`: the dashboard entity payload
+ * - `translation`: the matched translation row
+ * - `availableLanguages`: sorted list of codes
+ * - `currentLanguage`: the matched code
+ * - `isFallback`: true when the primary fallback was used
+ *
+ * @param string $uuid The dashboard UUID.
+ *
+ * @return JSONResponse The resolved payload.
+ *
+ * @spec openspec/specs/dashboard-language-content/spec.md
+ */
+ #[NoAdminRequired]
+ public function resolved(string $uuid): JSONResponse {
+ $user = $this->userSession->getUser();
+ if ($this->userId === null || $user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'dashboard-translation.resolved');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ try {
+ $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'not_found',
+ ],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }
+
+ $variant = $this->resolveVariant(
+ uuid: $uuid,
+ dashboard: $dashboard,
+ explicitLang: $this->request->getParam(key: 'lang')
+ );
+
+ // Only the strict explicit-lang path yields null; the locale path
+ // always materialises a variant. REQ-DASH-039 strict scenario.
+ if ($variant === null) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'language_not_available',
+ ],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }
+
+ return ResponseHelper::success(
+ data: [
+ 'dashboard' => $dashboard->jsonSerialize(),
+ 'translation' => $variant['translation']->jsonSerialize(),
+ 'availableLanguages' => $this->resolveAvailableLanguages(
+ uuid: $uuid,
+ variant: $variant
+ ),
+ 'currentLanguage' => $variant['translation']->getLanguageCode(),
+ 'isFallback' => $variant['isFallback'],
+ ]
+ );
+ }//end resolved()
+
+ /**
+ * Resolve the translation variant this request should render.
+ *
+ * A usable `?lang=` query parameter selects the strict exact-match
+ * path (which may report "no such language" by returning null); its
+ * absence — or a blank / non-string value — selects the viewer's own
+ * locale, which always yields a variant. REQ-DASH-039.
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param Dashboard $dashboard The dashboard entity (legacy source).
+ * @param mixed $explicitLang The raw `lang` query parameter.
+ *
+ * @return array{translation: mixed, isFallback: bool}|null The variant,
+ * or null.
+ */
+ private function resolveVariant(
+ string $uuid,
+ Dashboard $dashboard,
+ mixed $explicitLang,
+ ): ?array {
+ if (is_string($explicitLang) === false || $explicitLang === '') {
+ return $this->resolveLocaleVariant(uuid: $uuid, dashboard: $dashboard);
+ }
+
+ return $this->resolveExactVariant(uuid: $uuid, explicitLang: $explicitLang);
+ }//end resolveVariant()
+
+ /**
+ * Resolve a variant that matches the requested code exactly.
+ *
+ * Strict mode for the explicit `?lang=` parameter — when no exact
+ * match exists for the requested code the caller must return 404
+ * instead of the primary-fallback envelope, so a near-miss (the
+ * service's own fallback) is reported as "no match" here.
+ * REQ-DASH-039 strict scenario.
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param string $explicitLang The requested language code.
+ *
+ * @return array{translation: mixed, isFallback: bool}|null The exact
+ * match, or
+ * null.
+ */
+ private function resolveExactVariant(string $uuid, string $explicitLang): ?array {
+ $variant = $this->translationService->resolveForLocale(
+ dashboardUuid: $uuid,
+ preferredLanguage: $explicitLang
+ );
+
+ $requested = DashboardTranslationMapper::normaliseLanguageCode(
+ raw: $explicitLang
+ );
+ $matched = null;
+ if ($variant !== null) {
+ $matched = (string)$variant['translation']->getLanguageCode();
+ }
+
+ if ($matched !== $requested) {
+ return null;
+ }
+
+ return $variant;
+ }//end resolveExactVariant()
+
+ /**
+ * Resolve the variant for the viewer's own locale.
+ *
+ * Legacy fallback — dashboards predating REQ-DASH-038 may have no
+ * translation rows yet. Materialise an in-memory variant from the
+ * dashboard's own fields so the response envelope shape stays
+ * uniform. REQ-DASH-044.
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param Dashboard $dashboard The dashboard entity (legacy source).
+ *
+ * @return array{translation: mixed, isFallback: bool} The variant.
+ */
+ private function resolveLocaleVariant(string $uuid, Dashboard $dashboard): array {
+ $variant = $this->translationService->resolveForLocale(
+ dashboardUuid: $uuid,
+ preferredLanguage: ''
+ );
+
+ if ($variant !== null) {
+ return $variant;
+ }
+
+ return [
+ 'translation' => $this->translationService
+ ->materialiseLegacyVariant(dashboard: $dashboard),
+ 'isFallback' => true,
+ ];
+ }//end resolveLocaleVariant()
+
+ /**
+ * List the language codes offered for this dashboard.
+ *
+ * A dashboard with no stored translation rows still advertises the
+ * one code the resolved variant carries, so the language switcher is
+ * never empty when content is being shown.
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param array{translation: mixed, isFallback: bool} $variant The resolved variant.
+ *
+ * @return array The available codes.
+ */
+ private function resolveAvailableLanguages(string $uuid, array $variant): array {
+ $available = $this->translationService->listAvailableLanguages(
+ dashboardUuid: $uuid
+ );
+ if (count($available) > 0) {
+ return $available;
+ }
+
+ $code = (string)$variant['translation']->getLanguageCode();
+ if ($code === '') {
+ return $available;
+ }
+
+ return [$code];
+ }//end resolveAvailableLanguages()
+
+ /**
+ * Look up the dashboard and verify the current user is the owner.
+ *
+ * Returns null when the check passes; an HTTP 403 / 404 envelope
+ * when it fails. Group-shared dashboards are not addressable via
+ * the personal-scope translation endpoints — they short-circuit to
+ * 403 (the group-scoped translation flow lives separately).
+ *
+ * @param string $uuid The dashboard UUID.
+ *
+ * @return JSONResponse|null The error envelope or null on success.
+ */
+ private function assertOwner(string $uuid): ?JSONResponse {
+ try {
+ $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'not_found',
+ ],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }
+
+ if ($dashboard->getUserId() !== $this->userId) {
+ return ResponseHelper::forbidden();
+ }
+
+ return null;
+ }//end assertOwner()
+
+ /**
+ * Build the patch payload from individual nullable parameters.
+ *
+ * `null` means "not in payload" (skip the key); anything else (incl.
+ * the empty string) means "set it explicitly". The service then
+ * inspects key presence with `array_key_exists`.
+ *
+ * @param string|null $name The new name.
+ * @param string|null $description The new description.
+ * @param string|null $widgetTreeJson The new widget tree JSON.
+ *
+ * @return array The patch payload.
+ */
+ private function buildPatch(
+ ?string $name,
+ ?string $description,
+ ?string $widgetTreeJson,
+ ): array {
+ $patch = [];
+ if ($name !== null) {
+ $patch['name'] = $name;
+ }
+
+ if ($description !== null) {
+ $patch['description'] = $description;
+ }
+
+ if ($widgetTreeJson !== null) {
+ $patch['widgetTreeJson'] = $widgetTreeJson;
+ }
+
+ return $patch;
+ }//end buildPatch()
}//end class
diff --git a/lib/Controller/DashboardVersionApiController.php b/lib/Controller/DashboardVersionApiController.php
index 3fd5ab57..79ff6067 100644
--- a/lib/Controller/DashboardVersionApiController.php
+++ b/lib/Controller/DashboardVersionApiController.php
@@ -48,292 +48,289 @@
/**
* Controller for dashboard version endpoints (REQ-VERS-001..009).
*/
-class DashboardVersionApiController extends Controller
-{
- /**
- * Constructor
- *
- * @param IRequest $request NC request.
- * @param DashboardMapper $dashboardMapper Dashboard row lookup.
- * @param DashboardVersionService $versionService Version service.
- * @param ActionAuthService $actionAuth ADR-023 action authorization.
- * @param IUserSession $userSession User session (IUser resolution).
- * @param LoggerInterface $logger PSR logger.
- * @param string|null $userId Current user ID.
- */
- public function __construct(
- IRequest $request,
- private readonly DashboardMapper $dashboardMapper,
- private readonly DashboardVersionService $versionService,
- private readonly ActionAuthService $actionAuth,
- private readonly IUserSession $userSession,
- private readonly LoggerInterface $logger,
- private readonly ?string $userId,
- ) {
- parent::__construct(
- appName: Application::APP_ID,
- request: $request
- );
- }//end __construct()
-
- /**
- * List the versions for a dashboard, newest-first (REQ-VERS-003).
- *
- * @param string $uuid The dashboard UUID.
- *
- * @return JSONResponse The version list envelope.
- *
- * @spec openspec/specs/dashboard-versioning/spec.md
- */
- #[NoAdminRequired]
- public function listVersions(string $uuid): JSONResponse
- {
- if ($this->userId === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- $user = $this->userSession->getUser();
- if ($user === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- try {
- $this->actionAuth->requireAction($user, 'dashboard-version.list-versions');
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- try {
- $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: ['error' => 'Dashboard not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- }
-
- try {
- $envelope = $this->versionService->listVersions(
- dashboard: $dashboard,
- requestingUser: $this->userId
- );
- } catch (Exception $e) {
- return $this->mapServiceException(exception: $e);
- }
-
- return new JSONResponse(data: $envelope, statusCode: Http::STATUS_OK);
- }//end listVersions()
-
- /**
- * Fetch a single snapshot body (REQ-VERS-004).
- *
- * @param string $uuid The dashboard UUID.
- * @param integer $versionNumber The version number.
- *
- * @return JSONResponse The full snapshot body.
- *
- * @spec openspec/specs/dashboard-versioning/spec.md
- */
- #[NoAdminRequired]
- public function fetchVersion(
- string $uuid,
- int $versionNumber
- ): JSONResponse {
- if ($this->userId === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- $user = $this->userSession->getUser();
- if ($user === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- try {
- $this->actionAuth->requireAction($user, 'dashboard-version.fetch-version');
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- try {
- $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: ['error' => 'Dashboard not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- }
-
- try {
- $version = $this->versionService->fetchSnapshot(
- dashboard: $dashboard,
- versionNumber: $versionNumber,
- requestingUser: $this->userId
- );
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: ['error' => 'Version not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- } catch (Exception $e) {
- return $this->mapServiceException(exception: $e);
- }
-
- return new JSONResponse(
- data: [
- 'version' => $version->jsonSerialize(),
- 'snapshot' => $version->getSnapshotJson(),
- ],
- statusCode: Http::STATUS_OK
- );
- }//end fetchVersion()
-
- /**
- * Create an explicit snapshot (REQ-VERS-002). Bypasses the
- * 60-second debounce window. The optional `note` field is read
- * from the request body.
- *
- * @param string $uuid The dashboard UUID.
- * @param string|null $note Optional snapshot note (request body).
- *
- * @return JSONResponse The persisted version row.
- *
- * @spec openspec/specs/dashboard-versioning/spec.md
- */
- #[NoAdminRequired]
- public function createVersion(
- string $uuid,
- ?string $note=null
- ): JSONResponse {
- if ($this->userId === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- $user = $this->userSession->getUser();
- if ($user === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- try {
- $this->actionAuth->requireAction($user, 'dashboard-version.create-version');
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- try {
- $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: ['error' => 'Dashboard not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- }
-
- try {
- $version = $this->versionService->createExplicitSnapshot(
- dashboard: $dashboard,
- requestingUser: $this->userId,
- note: $note
- );
- } catch (Exception $e) {
- return $this->mapServiceException(exception: $e);
- }
-
- return new JSONResponse(
- data: ['version' => $version->jsonSerialize()],
- statusCode: Http::STATUS_CREATED
- );
- }//end createVersion()
-
- /**
- * Restore a snapshot (REQ-VERS-005). Captures the pre-restore
- * state as a new snapshot before applying the historical body.
- *
- * @param string $uuid The dashboard UUID.
- * @param integer $versionNumber The version number to restore.
- *
- * @return JSONResponse The restored snapshot envelope.
- *
- * @spec openspec/specs/dashboard-versioning/spec.md
- */
- #[NoAdminRequired]
- public function restoreVersion(
- string $uuid,
- int $versionNumber
- ): JSONResponse {
- if ($this->userId === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- $user = $this->userSession->getUser();
- if ($user === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- try {
- $this->actionAuth->requireAction($user, 'dashboard-version.restore-version');
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- try {
- $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: ['error' => 'Dashboard not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- }
-
- try {
- $result = $this->versionService->restoreVersion(
- dashboard: $dashboard,
- versionNumber: $versionNumber,
- restoringUser: $this->userId
- );
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: ['error' => 'Version not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- } catch (Exception $e) {
- return $this->mapServiceException(exception: $e);
- }
-
- return new JSONResponse(
- data: [
- 'version' => $result['version']->jsonSerialize(),
- 'snapshot' => $result['snapshot'],
- ],
- statusCode: Http::STATUS_OK
- );
- }//end restoreVersion()
-
- /**
- * Map a service-layer Exception to the appropriate JSON envelope.
- *
- * @param Exception $exception The exception.
- *
- * @return JSONResponse The mapped HTTP response.
- */
- private function mapServiceException(Exception $exception): JSONResponse
- {
- $message = $exception->getMessage();
-
- if ($message === DashboardVersionService::ERR_FORBIDDEN_NOT_OWNER_OR_ADMIN) {
- return new JSONResponse(
- data: ['error' => 'forbidden'],
- statusCode: Http::STATUS_FORBIDDEN
- );
- }
-
- $this->logger->error(
- message: 'launchpad: version operation failed',
- context: ['exception' => $exception]
- );
-
- return new JSONResponse(
- data: ['error' => 'Operation failed'],
- statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
- );
- }//end mapServiceException()
+class DashboardVersionApiController extends Controller {
+ /**
+ * Constructor
+ *
+ * @param IRequest $request NC request.
+ * @param DashboardMapper $dashboardMapper Dashboard row lookup.
+ * @param DashboardVersionService $versionService Version service.
+ * @param ActionAuthService $actionAuth ADR-023 action authorization.
+ * @param IUserSession $userSession User session (IUser resolution).
+ * @param LoggerInterface $logger PSR logger.
+ * @param string|null $userId Current user ID.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly DashboardMapper $dashboardMapper,
+ private readonly DashboardVersionService $versionService,
+ private readonly ActionAuthService $actionAuth,
+ private readonly IUserSession $userSession,
+ private readonly LoggerInterface $logger,
+ private readonly ?string $userId,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
+
+ /**
+ * List the versions for a dashboard, newest-first (REQ-VERS-003).
+ *
+ * @param string $uuid The dashboard UUID.
+ *
+ * @return JSONResponse The version list envelope.
+ *
+ * @spec openspec/specs/dashboard-versioning/spec.md
+ */
+ #[NoAdminRequired]
+ public function listVersions(string $uuid): JSONResponse {
+ if ($this->userId === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'dashboard-version.list-versions');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ try {
+ $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: ['error' => 'Dashboard not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }
+
+ try {
+ $envelope = $this->versionService->listVersions(
+ dashboard: $dashboard,
+ requestingUser: $this->userId
+ );
+ } catch (Exception $e) {
+ return $this->mapServiceException(exception: $e);
+ }
+
+ return new JSONResponse(data: $envelope, statusCode: Http::STATUS_OK);
+ }//end listVersions()
+
+ /**
+ * Fetch a single snapshot body (REQ-VERS-004).
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param integer $versionNumber The version number.
+ *
+ * @return JSONResponse The full snapshot body.
+ *
+ * @spec openspec/specs/dashboard-versioning/spec.md
+ */
+ #[NoAdminRequired]
+ public function fetchVersion(
+ string $uuid,
+ int $versionNumber,
+ ): JSONResponse {
+ if ($this->userId === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'dashboard-version.fetch-version');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ try {
+ $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: ['error' => 'Dashboard not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }
+
+ try {
+ $version = $this->versionService->fetchSnapshot(
+ dashboard: $dashboard,
+ versionNumber: $versionNumber,
+ requestingUser: $this->userId
+ );
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: ['error' => 'Version not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ } catch (Exception $e) {
+ return $this->mapServiceException(exception: $e);
+ }
+
+ return new JSONResponse(
+ data: [
+ 'version' => $version->jsonSerialize(),
+ 'snapshot' => $version->getSnapshotJson(),
+ ],
+ statusCode: Http::STATUS_OK
+ );
+ }//end fetchVersion()
+
+ /**
+ * Create an explicit snapshot (REQ-VERS-002). Bypasses the
+ * 60-second debounce window. The optional `note` field is read
+ * from the request body.
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param string|null $note Optional snapshot note (request body).
+ *
+ * @return JSONResponse The persisted version row.
+ *
+ * @spec openspec/specs/dashboard-versioning/spec.md
+ */
+ #[NoAdminRequired]
+ public function createVersion(
+ string $uuid,
+ ?string $note = null,
+ ): JSONResponse {
+ if ($this->userId === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'dashboard-version.create-version');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ try {
+ $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: ['error' => 'Dashboard not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }
+
+ try {
+ $version = $this->versionService->createExplicitSnapshot(
+ dashboard: $dashboard,
+ requestingUser: $this->userId,
+ note: $note
+ );
+ } catch (Exception $e) {
+ return $this->mapServiceException(exception: $e);
+ }
+
+ return new JSONResponse(
+ data: ['version' => $version->jsonSerialize()],
+ statusCode: Http::STATUS_CREATED
+ );
+ }//end createVersion()
+
+ /**
+ * Restore a snapshot (REQ-VERS-005). Captures the pre-restore
+ * state as a new snapshot before applying the historical body.
+ *
+ * @param string $uuid The dashboard UUID.
+ * @param integer $versionNumber The version number to restore.
+ *
+ * @return JSONResponse The restored snapshot envelope.
+ *
+ * @spec openspec/specs/dashboard-versioning/spec.md
+ */
+ #[NoAdminRequired]
+ public function restoreVersion(
+ string $uuid,
+ int $versionNumber,
+ ): JSONResponse {
+ if ($this->userId === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'dashboard-version.restore-version');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ try {
+ $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: ['error' => 'Dashboard not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }
+
+ try {
+ $result = $this->versionService->restoreVersion(
+ dashboard: $dashboard,
+ versionNumber: $versionNumber,
+ restoringUser: $this->userId
+ );
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: ['error' => 'Version not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ } catch (Exception $e) {
+ return $this->mapServiceException(exception: $e);
+ }
+
+ return new JSONResponse(
+ data: [
+ 'version' => $result['version']->jsonSerialize(),
+ 'snapshot' => $result['snapshot'],
+ ],
+ statusCode: Http::STATUS_OK
+ );
+ }//end restoreVersion()
+
+ /**
+ * Map a service-layer Exception to the appropriate JSON envelope.
+ *
+ * @param Exception $exception The exception.
+ *
+ * @return JSONResponse The mapped HTTP response.
+ */
+ private function mapServiceException(Exception $exception): JSONResponse {
+ $message = $exception->getMessage();
+
+ if ($message === DashboardVersionService::ERR_FORBIDDEN_NOT_OWNER_OR_ADMIN) {
+ return new JSONResponse(
+ data: ['error' => 'forbidden'],
+ statusCode: Http::STATUS_FORBIDDEN
+ );
+ }
+
+ $this->logger->error(
+ message: 'launchpad: version operation failed',
+ context: ['exception' => $exception]
+ );
+
+ return new JSONResponse(
+ data: ['error' => 'Operation failed'],
+ statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }//end mapServiceException()
}//end class
diff --git a/lib/Controller/FileController.php b/lib/Controller/FileController.php
index 126b6c29..e7d94e8d 100644
--- a/lib/Controller/FileController.php
+++ b/lib/Controller/FileController.php
@@ -48,129 +48,126 @@
/**
* Controller for the link-button-widget createFile flow.
*/
-class FileController extends Controller
-{
- /**
- * Constructor.
- *
- * @param IRequest $request The HTTP request.
- * @param FileService $fileService File-creation pipeline.
- * @param IUserSession $userSession Session accessor.
- * @param LoggerInterface $logger PSR logger.
- */
- public function __construct(
- IRequest $request,
- private readonly FileService $fileService,
- private readonly IUserSession $userSession,
- private readonly LoggerInterface $logger,
- ) {
- parent::__construct(
- appName: Application::APP_ID,
- request: $request
- );
- }//end __construct()
+class FileController extends Controller {
+ /**
+ * Constructor.
+ *
+ * @param IRequest $request The HTTP request.
+ * @param FileService $fileService File-creation pipeline.
+ * @param IUserSession $userSession Session accessor.
+ * @param LoggerInterface $logger PSR logger.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly FileService $fileService,
+ private readonly IUserSession $userSession,
+ private readonly LoggerInterface $logger,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
- /**
- * Handle `POST /api/files/create` (REQ-LBN-004).
- *
- * @param string|null $filename Leaf filename.
- * @param string|null $dir Target subdirectory (default `/`).
- * @param string|null $content Bytes to write (default empty).
- *
- * @return JSONResponse Either `{status, fileId, url}` on HTTP 200
- * or `{status, error, message}` on failure.
- *
- * @NoCSRFRequired
- *
- * @spec openspec/specs/resource-uploads/spec.md
- */
- #[NoAdminRequired]
- public function createFile(
- ?string $filename=null,
- ?string $dir='/',
- ?string $content=''
- ): JSONResponse {
- try {
- $userId = $this->resolveUserId();
+ /**
+ * Handle `POST /api/files/create` (REQ-LBN-004).
+ *
+ * @param string|null $filename Leaf filename.
+ * @param string|null $dir Target subdirectory (default `/`).
+ * @param string|null $content Bytes to write (default empty).
+ *
+ * @return JSONResponse Either `{status, fileId, url}` on HTTP 200
+ * or `{status, error, message}` on failure.
+ *
+ * @NoCSRFRequired
+ *
+ * @spec openspec/specs/resource-uploads/spec.md
+ */
+ #[NoAdminRequired]
+ public function createFile(
+ ?string $filename = null,
+ ?string $dir = '/',
+ ?string $content = '',
+ ): JSONResponse {
+ try {
+ $userId = $this->resolveUserId();
- $result = $this->fileService->createFile(
- userId: $userId,
- filename: ($filename ?? ''),
- dir: ($dir ?? '/'),
- content: ($content ?? '')
- );
+ $result = $this->fileService->createFile(
+ userId: $userId,
+ filename: ($filename ?? ''),
+ dir: ($dir ?? '/'),
+ content: ($content ?? '')
+ );
- return new JSONResponse(
- data: $result,
- statusCode: Http::STATUS_OK
- );
- } catch (ForbiddenException $e) {
- return new JSONResponse(
- data: [
- 'status' => 'error',
- 'error' => 'forbidden',
- 'message' => 'Authentication required',
- ],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- } catch (ResourceException $e) {
- if ($e instanceof StorageFailureException) {
- $this->logger->error(
- message: 'File create storage failure',
- context: ['exception' => $e->getMessage()]
- );
- }
+ return new JSONResponse(
+ data: $result,
+ statusCode: Http::STATUS_OK
+ );
+ } catch (ForbiddenException $e) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'forbidden',
+ 'message' => 'Authentication required',
+ ],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ } catch (ResourceException $e) {
+ if ($e instanceof StorageFailureException) {
+ $this->logger->error(
+ message: 'File create storage failure',
+ context: ['exception' => $e->getMessage()]
+ );
+ }
- return $this->errorResponse(exception: $e);
- } catch (Throwable $e) {
- // Defence in depth — never leak raw messages on
- // truly unexpected paths.
- $this->logger->error(
- message: 'Unexpected file create failure',
- context: ['exception' => $e->getMessage()]
- );
+ return $this->errorResponse(exception: $e);
+ } catch (Throwable $e) {
+ // Defence in depth — never leak raw messages on
+ // truly unexpected paths.
+ $this->logger->error(
+ message: 'Unexpected file create failure',
+ context: ['exception' => $e->getMessage()]
+ );
- $fallback = new StorageFailureException(
- message: 'Failed to create file'
- );
+ $fallback = new StorageFailureException(
+ message: 'Failed to create file'
+ );
- return $this->errorResponse(exception: $fallback);
- }//end try
- }//end createFile()
+ return $this->errorResponse(exception: $fallback);
+ }//end try
+ }//end createFile()
- /**
- * Resolve the logged-in user's ID.
- *
- * @return string The user's UID.
- *
- * @throws ForbiddenException When the request is not authenticated.
- */
- private function resolveUserId(): string
- {
- $user = $this->userSession->getUser();
- if ($user === null) {
- throw new ForbiddenException();
- }
+ /**
+ * Resolve the logged-in user's ID.
+ *
+ * @return string The user's UID.
+ *
+ * @throws ForbiddenException When the request is not authenticated.
+ */
+ private function resolveUserId(): string {
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ throw new ForbiddenException();
+ }
- return $user->getUID();
- }//end resolveUserId()
+ return $user->getUID();
+ }//end resolveUserId()
- /**
- * Build the standardised error envelope from a typed exception.
- *
- * @param ResourceException $exception The typed exception.
- *
- * @return JSONResponse The error response.
- */
- private function errorResponse(ResourceException $exception): JSONResponse
- {
- return new JSONResponse(
- data: [
- 'status' => 'error',
- 'error' => $exception->getErrorCode(),
- 'message' => $exception->getDisplayMessage(),
- ],
- statusCode: $exception->getHttpStatus()
- );
- }//end errorResponse()
+ /**
+ * Build the standardised error envelope from a typed exception.
+ *
+ * @param ResourceException $exception The typed exception.
+ *
+ * @return JSONResponse The error response.
+ */
+ private function errorResponse(ResourceException $exception): JSONResponse {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => $exception->getErrorCode(),
+ 'message' => $exception->getDisplayMessage(),
+ ],
+ statusCode: $exception->getHttpStatus()
+ );
+ }//end errorResponse()
}//end class
diff --git a/lib/Controller/FilesWidgetController.php b/lib/Controller/FilesWidgetController.php
index 2221c01c..2ef0a299 100644
--- a/lib/Controller/FilesWidgetController.php
+++ b/lib/Controller/FilesWidgetController.php
@@ -61,405 +61,397 @@
* underlying service.
* @spec openspec/specs/files-widget/spec.md
*/
-class FilesWidgetController extends Controller
-{
- /**
- * Constructor.
- *
- * @param IRequest $request HTTP request.
- * @param FilesWidgetService $service Files widget service.
- * @param WidgetPlacementMapper $placementMapper Placement entity mapper.
- * @param PermissionService $permissionService Dashboard permission gate.
- * @param IUserSession $userSession Session accessor.
- * @param LoggerInterface $logger PSR logger.
- */
- public function __construct(
- IRequest $request,
- private readonly FilesWidgetService $service,
- private readonly WidgetPlacementMapper $placementMapper,
- private readonly PermissionService $permissionService,
- private readonly IUserSession $userSession,
- private readonly LoggerInterface $logger,
- ) {
- parent::__construct(
- appName: Application::APP_ID,
- request: $request
- );
- }//end __construct()
-
- /**
- * `GET /api/widgets/files/{placementId}/contents`
- *
- * Returns the configured folder's contents as
- * `{items: [...], nextCursor: ?string}`. Empty folder is HTTP 200
- * with `items: []`. Missing folder is HTTP 404. Read-denied folder
- * is HTTP 403.
- *
- * @param integer $placementId The widget placement id.
- * @param string $currentPath Sub-path inside the configured folder.
- * @param integer $limit Page size (capped server-side).
- * @param string $cursor Opaque pagination cursor.
- *
- * @return JSONResponse
- *
- * @spec openspec/specs/files-widget/spec.md
- */
- #[NoAdminRequired]
- #[NoCSRFRequired]
- public function contents(
- int $placementId,
- string $currentPath='/',
- int $limit=FilesWidgetService::DEFAULT_LIMIT,
- string $cursor=''
- ): JSONResponse {
- $userId = $this->resolveUserId();
- if ($userId === null) {
- return $this->unauthorised();
- }
-
- $config = $this->loadConfig(placementId: $placementId, userId: $userId);
- if ($config === null) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'forbidden'],
- statusCode: Http::STATUS_FORBIDDEN
- );
- }
-
- try {
- $page = $this->service->getContentsForPlacement(
- userId: $userId,
- config: $config,
- currentSubPath: $currentPath,
- limit: $limit,
- cursor: $cursor
- );
-
- return new JSONResponse(
- data: $page,
- statusCode: Http::STATUS_OK
- );
- } catch (FolderNotFoundException $e) {
- return $this->errorResponse(
- error: 'folder_not_found',
- status: Http::STATUS_NOT_FOUND,
- message: $e->getDisplayMessage()
- );
- } catch (NoAccessException $e) {
- return $this->errorResponse(
- error: 'no_access',
- status: Http::STATUS_FORBIDDEN,
- message: $e->getDisplayMessage()
- );
- } catch (Throwable $e) {
- $this->logger->error(
- message: 'Unexpected files widget contents failure',
- context: ['exception' => $e->getMessage()]
- );
- return $this->errorResponse(
- error: 'unknown_error',
- status: Http::STATUS_INTERNAL_SERVER_ERROR
- );
- }//end try
- }//end contents()
-
- /**
- * `POST /api/widgets/files/{placementId}/upload`
- *
- * Accepts `multipart/form-data` with one or more `files[]` entries
- * and writes them into the placement-configured folder (or a
- * sub-path of it, if `currentPath` is supplied).
- *
- * @param integer $placementId The widget placement id.
- * @param string $currentPath Sub-path inside the configured folder.
- *
- * @return JSONResponse
- *
- * @spec openspec/specs/files-widget/spec.md
- */
- #[NoAdminRequired]
- public function upload(int $placementId, string $currentPath='/'): JSONResponse
- {
- $userId = $this->resolveUserId();
- if ($userId === null) {
- return $this->unauthorised();
- }
-
- $config = $this->loadConfig(placementId: $placementId, userId: $userId);
- if ($config === null) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'forbidden'],
- statusCode: Http::STATUS_FORBIDDEN
- );
- }
-
- $files = $this->normaliseUploadedFiles();
-
- try {
- $result = $this->service->uploadFiles(
- userId: $userId,
- config: $config,
- currentSubPath: $currentPath,
- uploadedFiles: $files
- );
-
- return new JSONResponse(
- data: $result,
- statusCode: Http::STATUS_OK
- );
- } catch (FolderNotFoundException $e) {
- return $this->errorResponse(
- error: 'folder_not_found',
- status: Http::STATUS_NOT_FOUND,
- message: $e->getDisplayMessage()
- );
- } catch (NoAccessException $e) {
- return $this->errorResponse(
- error: 'no_access',
- status: Http::STATUS_FORBIDDEN,
- message: $e->getDisplayMessage()
- );
- } catch (Throwable $e) {
- $this->logger->error(
- message: 'Unexpected files widget upload failure',
- context: ['exception' => $e->getMessage()]
- );
- return $this->errorResponse(
- error: 'unknown_error',
- status: Http::STATUS_INTERNAL_SERVER_ERROR
- );
- }//end try
- }//end upload()
-
- /**
- * `DELETE /api/widgets/files/{placementId}/files/{fileId}`
- *
- * Moves the supplied file into the user's trash bin.
- *
- * @param integer $placementId The widget placement id.
- * @param integer $fileId File id (must live inside the
- * configured folder).
- *
- * @return JSONResponse
- *
- * @spec openspec/specs/files-widget/spec.md
- */
- #[NoAdminRequired]
- public function destroy(int $placementId, int $fileId): JSONResponse
- {
- $userId = $this->resolveUserId();
- if ($userId === null) {
- return $this->unauthorised();
- }
-
- $config = $this->loadConfig(placementId: $placementId, userId: $userId);
- if ($config === null) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'forbidden'],
- statusCode: Http::STATUS_FORBIDDEN
- );
- }
-
- try {
- $result = $this->service->deleteFile(
- userId: $userId,
- config: $config,
- fileId: $fileId
- );
-
- return new JSONResponse(
- data: $result,
- statusCode: Http::STATUS_OK
- );
- } catch (FolderNotFoundException $e) {
- return $this->errorResponse(
- error: 'folder_not_found',
- status: Http::STATUS_NOT_FOUND,
- message: $e->getDisplayMessage()
- );
- } catch (NoAccessException $e) {
- return $this->errorResponse(
- error: 'no_access',
- status: Http::STATUS_FORBIDDEN,
- message: $e->getDisplayMessage()
- );
- } catch (Throwable $e) {
- $this->logger->error(
- message: 'Unexpected files widget delete failure',
- context: ['exception' => $e->getMessage()]
- );
- return $this->errorResponse(
- error: 'unknown_error',
- status: Http::STATUS_INTERNAL_SERVER_ERROR
- );
- }//end try
- }//end destroy()
-
- /**
- * Resolve the active user's UID, or `null` for anonymous.
- *
- * @return string|null
- */
- private function resolveUserId(): ?string
- {
- $user = $this->userSession->getUser();
- if ($user === null) {
- return null;
- }
-
- return $user->getUID();
- }//end resolveUserId()
-
- /**
- * Load the placement, gate it through {@see PermissionService}, and
- * return the parsed `widgetContent` config blob.
- *
- * Returns `null` when the placement is missing OR the user cannot
- * view the underlying dashboard. The caller maps `null` to a
- * forbidden response so missing-vs-no-access is indistinguishable
- * to the client.
- *
- * @param integer $placementId Widget placement id.
- * @param string $userId Viewing user's UID.
- *
- * @return array|null
- */
- private function loadConfig(int $placementId, string $userId): ?array
- {
- try {
- $placement = $this->placementMapper->find(id: $placementId);
- } catch (Throwable $e) {
- return null;
- }
-
- // L2: upload is a write operation — require write-level permission
- // (canAddWidget), not read-level (canViewDashboard).
- if ($this->permissionService->canAddWidget(
- userId: $userId,
- dashboardId: $placement->getDashboardId()
- ) === false
- ) {
- return null;
- }
-
- // Registry-driven custom widgets persist their per-type config
- // in the `content` column (added in Version001025). Older rows
- // that pre-date the column may still carry the blob inside the
- // legacy `style_config.content` slot, so we fall back to that
- // shape when the dedicated column is empty.
- $content = $placement->getContentArray();
- if ($content !== []) {
- return $content;
- }
-
- $legacy = $placement->getStyleConfigArray();
- if (isset($legacy['content']) === true && is_array($legacy['content']) === true) {
- return $legacy['content'];
- }
-
- return $legacy;
- }//end loadConfig()
-
- /**
- * Convert PHP's `$_FILES` super-global into a flat list of
- * upload entries. Supports both single (`files=...`) and
- * multi-part (`files[]=...`) submissions.
- *
- * @return list
- *
- * @SuppressWarnings(PHPMD.Superglobals) — required for multipart file uploads.
- */
- private function normaliseUploadedFiles(): array
- {
- // @phpstan-ignore-next-line — superglobal access is mixed.
- $raw = $_FILES['files'] ?? null;
- if (is_array($raw) === false) {
- return [];
- }
-
- $names = ($raw['name'] ?? null);
- $tmps = ($raw['tmp_name'] ?? null);
- $sizes = ($raw['size'] ?? null);
- $errors = ($raw['error'] ?? null);
-
- $entries = [];
- if (is_array($names) === true) {
- $count = count($names);
- if (is_array($tmps) === false) {
- $tmps = [];
- }
-
- if (is_array($sizes) === false) {
- $sizes = [];
- }
-
- if (is_array($errors) === false) {
- $errors = [];
- }
-
- for ($i = 0; $i < $count; $i++) {
- $entries[] = [
- 'name' => (string) ($names[$i] ?? ''),
- 'tmp_name' => (string) ($tmps[$i] ?? ''),
- 'size' => (int) ($sizes[$i] ?? 0),
- 'error' => (int) ($errors[$i] ?? UPLOAD_ERR_NO_FILE),
- ];
- }
- } else if ($names !== null) {
- $entries[] = [
- 'name' => (string) $names,
- 'tmp_name' => (string) ($tmps ?? ''),
- 'size' => (int) ($sizes ?? 0),
- 'error' => (int) ($errors ?? UPLOAD_ERR_NO_FILE),
- ];
- }//end if
-
- return $entries;
- }//end normaliseUploadedFiles()
-
- /**
- * Build a 401 envelope for the anonymous case.
- *
- * @return JSONResponse
- */
- private function unauthorised(): JSONResponse
- {
- return new JSONResponse(
- data: [
- 'status' => 'error',
- 'error' => 'unauthorized',
- 'message' => 'Authentication required',
- ],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }//end unauthorised()
-
- /**
- * Build a typed error envelope.
- *
- * The status code is restricted to the union of HTTP status codes
- * accepted by {@see JSONResponse::__construct()} so that PHPStan
- * can verify the literal at every call-site.
- *
- * @param string $error Machine-readable error code.
- * @param int<100,511> $status HTTP status code.
- * @param string|null $message Optional human-readable message.
- *
- * @return JSONResponse
- */
- private function errorResponse(string $error, int $status=Http::STATUS_BAD_REQUEST, ?string $message=null): JSONResponse
- {
- $payload = [
- 'status' => 'error',
- 'error' => $error,
- ];
-
- if ($message !== null) {
- $payload['message'] = $message;
- }
-
- return new JSONResponse(
- data: $payload,
- statusCode: $status
- );
- }//end errorResponse()
+class FilesWidgetController extends Controller {
+ /**
+ * Constructor.
+ *
+ * @param IRequest $request HTTP request.
+ * @param FilesWidgetService $service Files widget service.
+ * @param WidgetPlacementMapper $placementMapper Placement entity mapper.
+ * @param PermissionService $permissionService Dashboard permission gate.
+ * @param IUserSession $userSession Session accessor.
+ * @param LoggerInterface $logger PSR logger.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly FilesWidgetService $service,
+ private readonly WidgetPlacementMapper $placementMapper,
+ private readonly PermissionService $permissionService,
+ private readonly IUserSession $userSession,
+ private readonly LoggerInterface $logger,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
+
+ /**
+ * `GET /api/widgets/files/{placementId}/contents`
+ *
+ * Returns the configured folder's contents as
+ * `{items: [...], nextCursor: ?string}`. Empty folder is HTTP 200
+ * with `items: []`. Missing folder is HTTP 404. Read-denied folder
+ * is HTTP 403.
+ *
+ * @param integer $placementId The widget placement id.
+ * @param string $currentPath Sub-path inside the configured folder.
+ * @param integer $limit Page size (capped server-side).
+ * @param string $cursor Opaque pagination cursor.
+ *
+ * @return JSONResponse
+ *
+ * @spec openspec/specs/files-widget/spec.md
+ */
+ #[NoAdminRequired]
+ #[NoCSRFRequired]
+ public function contents(
+ int $placementId,
+ string $currentPath = '/',
+ int $limit = FilesWidgetService::DEFAULT_LIMIT,
+ string $cursor = '',
+ ): JSONResponse {
+ $userId = $this->resolveUserId();
+ if ($userId === null) {
+ return $this->unauthorised();
+ }
+
+ $config = $this->loadConfig(placementId: $placementId, userId: $userId);
+ if ($config === null) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'forbidden'],
+ statusCode: Http::STATUS_FORBIDDEN
+ );
+ }
+
+ try {
+ $page = $this->service->getContentsForPlacement(
+ userId: $userId,
+ config: $config,
+ currentSubPath: $currentPath,
+ limit: $limit,
+ cursor: $cursor
+ );
+
+ return new JSONResponse(
+ data: $page,
+ statusCode: Http::STATUS_OK
+ );
+ } catch (FolderNotFoundException $e) {
+ return $this->errorResponse(
+ error: 'folder_not_found',
+ status: Http::STATUS_NOT_FOUND,
+ message: $e->getDisplayMessage()
+ );
+ } catch (NoAccessException $e) {
+ return $this->errorResponse(
+ error: 'no_access',
+ status: Http::STATUS_FORBIDDEN,
+ message: $e->getDisplayMessage()
+ );
+ } catch (Throwable $e) {
+ $this->logger->error(
+ message: 'Unexpected files widget contents failure',
+ context: ['exception' => $e->getMessage()]
+ );
+ return $this->errorResponse(
+ error: 'unknown_error',
+ status: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }//end try
+ }//end contents()
+
+ /**
+ * `POST /api/widgets/files/{placementId}/upload`
+ *
+ * Accepts `multipart/form-data` with one or more `files[]` entries
+ * and writes them into the placement-configured folder (or a
+ * sub-path of it, if `currentPath` is supplied).
+ *
+ * @param integer $placementId The widget placement id.
+ * @param string $currentPath Sub-path inside the configured folder.
+ *
+ * @return JSONResponse
+ *
+ * @spec openspec/specs/files-widget/spec.md
+ */
+ #[NoAdminRequired]
+ public function upload(int $placementId, string $currentPath = '/'): JSONResponse {
+ $userId = $this->resolveUserId();
+ if ($userId === null) {
+ return $this->unauthorised();
+ }
+
+ $config = $this->loadConfig(placementId: $placementId, userId: $userId);
+ if ($config === null) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'forbidden'],
+ statusCode: Http::STATUS_FORBIDDEN
+ );
+ }
+
+ $files = $this->normaliseUploadedFiles();
+
+ try {
+ $result = $this->service->uploadFiles(
+ userId: $userId,
+ config: $config,
+ currentSubPath: $currentPath,
+ uploadedFiles: $files
+ );
+
+ return new JSONResponse(
+ data: $result,
+ statusCode: Http::STATUS_OK
+ );
+ } catch (FolderNotFoundException $e) {
+ return $this->errorResponse(
+ error: 'folder_not_found',
+ status: Http::STATUS_NOT_FOUND,
+ message: $e->getDisplayMessage()
+ );
+ } catch (NoAccessException $e) {
+ return $this->errorResponse(
+ error: 'no_access',
+ status: Http::STATUS_FORBIDDEN,
+ message: $e->getDisplayMessage()
+ );
+ } catch (Throwable $e) {
+ $this->logger->error(
+ message: 'Unexpected files widget upload failure',
+ context: ['exception' => $e->getMessage()]
+ );
+ return $this->errorResponse(
+ error: 'unknown_error',
+ status: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }//end try
+ }//end upload()
+
+ /**
+ * `DELETE /api/widgets/files/{placementId}/files/{fileId}`
+ *
+ * Moves the supplied file into the user's trash bin.
+ *
+ * @param integer $placementId The widget placement id.
+ * @param integer $fileId File id (must live inside the
+ * configured folder).
+ *
+ * @return JSONResponse
+ *
+ * @spec openspec/specs/files-widget/spec.md
+ */
+ #[NoAdminRequired]
+ public function destroy(int $placementId, int $fileId): JSONResponse {
+ $userId = $this->resolveUserId();
+ if ($userId === null) {
+ return $this->unauthorised();
+ }
+
+ $config = $this->loadConfig(placementId: $placementId, userId: $userId);
+ if ($config === null) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'forbidden'],
+ statusCode: Http::STATUS_FORBIDDEN
+ );
+ }
+
+ try {
+ $result = $this->service->deleteFile(
+ userId: $userId,
+ config: $config,
+ fileId: $fileId
+ );
+
+ return new JSONResponse(
+ data: $result,
+ statusCode: Http::STATUS_OK
+ );
+ } catch (FolderNotFoundException $e) {
+ return $this->errorResponse(
+ error: 'folder_not_found',
+ status: Http::STATUS_NOT_FOUND,
+ message: $e->getDisplayMessage()
+ );
+ } catch (NoAccessException $e) {
+ return $this->errorResponse(
+ error: 'no_access',
+ status: Http::STATUS_FORBIDDEN,
+ message: $e->getDisplayMessage()
+ );
+ } catch (Throwable $e) {
+ $this->logger->error(
+ message: 'Unexpected files widget delete failure',
+ context: ['exception' => $e->getMessage()]
+ );
+ return $this->errorResponse(
+ error: 'unknown_error',
+ status: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }//end try
+ }//end destroy()
+
+ /**
+ * Resolve the active user's UID, or `null` for anonymous.
+ *
+ * @return string|null
+ */
+ private function resolveUserId(): ?string {
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ return null;
+ }
+
+ return $user->getUID();
+ }//end resolveUserId()
+
+ /**
+ * Load the placement, gate it through {@see PermissionService}, and
+ * return the parsed `widgetContent` config blob.
+ *
+ * Returns `null` when the placement is missing OR the user cannot
+ * view the underlying dashboard. The caller maps `null` to a
+ * forbidden response so missing-vs-no-access is indistinguishable
+ * to the client.
+ *
+ * @param integer $placementId Widget placement id.
+ * @param string $userId Viewing user's UID.
+ *
+ * @return array|null
+ */
+ private function loadConfig(int $placementId, string $userId): ?array {
+ try {
+ $placement = $this->placementMapper->find(id: $placementId);
+ } catch (Throwable $e) {
+ return null;
+ }
+
+ // L2: upload is a write operation — require write-level permission
+ // (canAddWidget), not read-level (canViewDashboard).
+ if ($this->permissionService->canAddWidget(
+ userId: $userId,
+ dashboardId: $placement->getDashboardId()
+ ) === false
+ ) {
+ return null;
+ }
+
+ // Registry-driven custom widgets persist their per-type config
+ // in the `content` column (added in Version001025). Older rows
+ // that pre-date the column may still carry the blob inside the
+ // legacy `style_config.content` slot, so we fall back to that
+ // shape when the dedicated column is empty.
+ $content = $placement->getContentArray();
+ if ($content !== []) {
+ return $content;
+ }
+
+ $legacy = $placement->getStyleConfigArray();
+ if (isset($legacy['content']) === true && is_array($legacy['content']) === true) {
+ return $legacy['content'];
+ }
+
+ return $legacy;
+ }//end loadConfig()
+
+ /**
+ * Convert PHP's `$_FILES` super-global into a flat list of
+ * upload entries. Supports both single (`files=...`) and
+ * multi-part (`files[]=...`) submissions.
+ *
+ * @return list
+ *
+ * @SuppressWarnings(PHPMD.Superglobals) — required for multipart file uploads.
+ */
+ private function normaliseUploadedFiles(): array {
+ // @phpstan-ignore-next-line — superglobal access is mixed.
+ $raw = $_FILES['files'] ?? null;
+ if (is_array($raw) === false) {
+ return [];
+ }
+
+ $names = ($raw['name'] ?? null);
+ $tmps = ($raw['tmp_name'] ?? null);
+ $sizes = ($raw['size'] ?? null);
+ $errors = ($raw['error'] ?? null);
+
+ $entries = [];
+ if (is_array($names) === true) {
+ $count = count($names);
+ if (is_array($tmps) === false) {
+ $tmps = [];
+ }
+
+ if (is_array($sizes) === false) {
+ $sizes = [];
+ }
+
+ if (is_array($errors) === false) {
+ $errors = [];
+ }
+
+ for ($i = 0; $i < $count; $i++) {
+ $entries[] = [
+ 'name' => (string)($names[$i] ?? ''),
+ 'tmp_name' => (string)($tmps[$i] ?? ''),
+ 'size' => (int)($sizes[$i] ?? 0),
+ 'error' => (int)($errors[$i] ?? UPLOAD_ERR_NO_FILE),
+ ];
+ }
+ } elseif ($names !== null) {
+ $entries[] = [
+ 'name' => (string)$names,
+ 'tmp_name' => (string)($tmps ?? ''),
+ 'size' => (int)($sizes ?? 0),
+ 'error' => (int)($errors ?? UPLOAD_ERR_NO_FILE),
+ ];
+ }//end if
+
+ return $entries;
+ }//end normaliseUploadedFiles()
+
+ /**
+ * Build a 401 envelope for the anonymous case.
+ *
+ * @return JSONResponse
+ */
+ private function unauthorised(): JSONResponse {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'unauthorized',
+ 'message' => 'Authentication required',
+ ],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }//end unauthorised()
+
+ /**
+ * Build a typed error envelope.
+ *
+ * The status code is restricted to the union of HTTP status codes
+ * accepted by {@see JSONResponse::__construct()} so that PHPStan
+ * can verify the literal at every call-site.
+ *
+ * @param string $error Machine-readable error code.
+ * @param int<100,511> $status HTTP status code.
+ * @param string|null $message Optional human-readable message.
+ *
+ * @return JSONResponse
+ */
+ private function errorResponse(string $error, int $status = Http::STATUS_BAD_REQUEST, ?string $message = null): JSONResponse {
+ $payload = [
+ 'status' => 'error',
+ 'error' => $error,
+ ];
+
+ if ($message !== null) {
+ $payload['message'] = $message;
+ }
+
+ return new JSONResponse(
+ data: $payload,
+ statusCode: $status
+ );
+ }//end errorResponse()
}//end class
diff --git a/lib/Controller/HealthController.php b/lib/Controller/HealthController.php
index a6ecc1e8..2f721958 100644
--- a/lib/Controller/HealthController.php
+++ b/lib/Controller/HealthController.php
@@ -49,88 +49,86 @@
*
* @spec openspec/changes/adopt-apphost/specs/prometheus-metrics/spec.md — Requirement: Health Check Endpoint (REQ-PROM-007)
*/
-class HealthController extends Controller
-{
- /**
- * Constructor.
- *
- * @param string $appName This leaf's app id (`launchpad`).
- * @param IRequest $request The HTTP request.
- * @param object|null $manifestLoader OpenRegister's ManifestLoader, or null when
- * OpenRegister is unavailable. Untyped on
- * purpose: a parameter TYPE is also a
- * compile-time reference to a class that may
- * not exist.
- * @param object|null $executor OpenRegister's HealthCheckExecutor, or null.
- */
- public function __construct(
- string $appName,
- IRequest $request,
- private readonly ?object $manifestLoader=null,
- private readonly ?object $executor=null,
- ) {
- parent::__construct(appName: $appName, request: $request);
- }//end __construct()
+class HealthController extends Controller {
+ /**
+ * Constructor.
+ *
+ * @param string $appName This leaf's app id (`launchpad`).
+ * @param IRequest $request The HTTP request.
+ * @param object|null $manifestLoader OpenRegister's ManifestLoader, or null when
+ * OpenRegister is unavailable. Untyped on
+ * purpose: a parameter TYPE is also a
+ * compile-time reference to a class that may
+ * not exist.
+ * @param object|null $executor OpenRegister's HealthCheckExecutor, or null.
+ */
+ public function __construct(
+ string $appName,
+ IRequest $request,
+ private readonly ?object $manifestLoader = null,
+ private readonly ?object $executor = null,
+ ) {
+ parent::__construct(appName: $appName, request: $request);
+ }//end __construct()
- /**
- * GET /api/health — declarative health check (ADR-006), public.
- *
- * Reports `status: unavailable` with HTTP 503 when the engine is absent,
- * which is a meaningful answer for a monitoring probe: the app is reachable,
- * its declarative health engine is not.
- *
- * @return JSONResponse `{status, app, version, checks}`.
- *
- * @spec openspec/changes/adopt-apphost/specs/prometheus-metrics/spec.md — Requirement: Health Check Endpoint (REQ-PROM-007)
- */
- #[PublicPage]
- #[NoCSRFRequired]
- public function index(): JSONResponse
- {
- $appId = $this->appName;
+ /**
+ * GET /api/health — declarative health check (ADR-006), public.
+ *
+ * Reports `status: unavailable` with HTTP 503 when the engine is absent,
+ * which is a meaningful answer for a monitoring probe: the app is reachable,
+ * its declarative health engine is not.
+ *
+ * @return JSONResponse `{status, app, version, checks}`.
+ *
+ * @spec openspec/changes/adopt-apphost/specs/prometheus-metrics/spec.md — Requirement: Health Check Endpoint (REQ-PROM-007)
+ */
+ #[PublicPage]
+ #[NoCSRFRequired]
+ public function index(): JSONResponse {
+ $appId = $this->appName;
- if ($this->manifestLoader === null || $this->executor === null) {
- return new JSONResponse(
- [
- 'status' => 'unavailable',
- 'app' => $appId,
- 'error' => 'OpenRegister AppHost observability engine unavailable',
- 'checks' => [],
- ],
- Http::STATUS_SERVICE_UNAVAILABLE
- );
- }
+ if ($this->manifestLoader === null || $this->executor === null) {
+ return new JSONResponse(
+ [
+ 'status' => 'unavailable',
+ 'app' => $appId,
+ 'error' => 'OpenRegister AppHost observability engine unavailable',
+ 'checks' => [],
+ ],
+ Http::STATUS_SERVICE_UNAVAILABLE
+ );
+ }
- try {
- $manifest = $this->manifestLoader->load(appId: $appId);
- $result = $this->executor->execute(manifest: $manifest);
+ try {
+ $manifest = $this->manifestLoader->load(appId: $appId);
+ $result = $this->executor->execute(manifest: $manifest);
- $response = new JSONResponse(
- [
- 'status' => $result->status,
- 'app' => $appId,
- 'version' => $this->manifestLoader->appVersion(appId: $appId),
- 'checks' => $result->checks,
- ],
- $result->httpStatusCode
- );
+ $response = new JSONResponse(
+ [
+ 'status' => $result->status,
+ 'app' => $appId,
+ 'version' => $this->manifestLoader->appVersion(appId: $appId),
+ 'checks' => $result->checks,
+ ],
+ $result->httpStatusCode
+ );
- if ($manifest->cors === true) {
- $response->addHeader('Access-Control-Allow-Origin', '*');
- $response->addHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
- }
+ if ($manifest->cors === true) {
+ $response->addHeader('Access-Control-Allow-Origin', '*');
+ $response->addHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+ }
- return $response;
- } catch (Throwable $e) {
- return new JSONResponse(
- [
- 'status' => 'unavailable',
- 'app' => $appId,
- 'error' => $e->getMessage(),
- 'checks' => [],
- ],
- Http::STATUS_SERVICE_UNAVAILABLE
- );
- }//end try
- }//end index()
+ return $response;
+ } catch (Throwable $e) {
+ return new JSONResponse(
+ [
+ 'status' => 'unavailable',
+ 'app' => $appId,
+ 'error' => $e->getMessage(),
+ 'checks' => [],
+ ],
+ Http::STATUS_SERVICE_UNAVAILABLE
+ );
+ }//end try
+ }//end index()
}//end class
diff --git a/lib/Controller/HealthPingController.php b/lib/Controller/HealthPingController.php
index 033a0b7a..afdbc393 100644
--- a/lib/Controller/HealthPingController.php
+++ b/lib/Controller/HealthPingController.php
@@ -51,140 +51,136 @@
*
* @spec openspec/specs/service-health-ping/spec.md
*/
-class HealthPingController extends Controller
-{
- /**
- * Constructor.
- *
- * @param IRequest $request HTTP request.
- * @param HealthPingService $healthPingService Resolves + caches + validates health-ping badges.
- * @param PermissionService $permissionService Dashboard/placement permission gate.
- * @param IUserSession $userSession Session accessor.
- * @param LoggerInterface $logger PSR logger.
- */
- public function __construct(
- IRequest $request,
- private readonly HealthPingService $healthPingService,
- private readonly PermissionService $permissionService,
- private readonly IUserSession $userSession,
- private readonly LoggerInterface $logger,
- ) {
- parent::__construct(
- appName: Application::APP_ID,
- request: $request
- );
- }//end __construct()
-
- /**
- * `GET /api/health-ping/{placementId}`
- *
- * Returns the health badge for one placement. Returns 401 when
- * anonymous, 403 when the caller may not view the underlying
- * dashboard (REQ-HPING-003 "Caller authorization" — the ping is NEVER
- * performed in that case), 404 when the placement does not exist or
- * has no ping configured, else 200 with the badge (possibly
- * `stale: true`).
- *
- * @param integer $placementId The widget placement id.
- *
- * @return JSONResponse
- *
- * @spec openspec/specs/service-health-ping/spec.md
- */
- #[NoAdminRequired]
- #[NoCSRFRequired]
- public function show(int $placementId): JSONResponse
- {
- $userId = $this->resolveUserId();
- if ($userId === null) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'unauthorized'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
-
- // REQ-HPING-003 "Caller authorization" — the auth guard runs
- // BEFORE any resolution/ping is attempted.
- if ($this->permissionService->canViewPlacement(userId: $userId, placementId: $placementId) === false) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'forbidden'],
- statusCode: Http::STATUS_FORBIDDEN
- );
- }
-
- try {
- $badge = $this->healthPingService->resolveForPlacement(placementId: $placementId);
- } catch (Throwable $exception) {
- $this->logger->error(
- message: 'Unexpected health-ping resolution failure',
- context: ['app' => Application::APP_ID, 'exception' => $exception->getMessage()]
- );
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'unknown_error'],
- statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
- );
- }
-
- if (isset($badge['error']) === true) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => $badge['error']],
- statusCode: Http::STATUS_NOT_FOUND
- );
- }
-
- return new JSONResponse(
- data: $badge,
- statusCode: Http::STATUS_OK
- );
- }//end show()
-
- /**
- * `POST /api/health-ping/validate`
- *
- * Validates a candidate health-ping config before the author saves
- * the placement (REQ-HPING-001 "rejected at save time" — host
- * allow-list, fail-closed). Performs NO ping — only the allow-list
- * check that `resolveForPlacement()` would apply.
- *
- * @return JSONResponse `{valid: bool, errors: string[]}`.
- *
- * @spec openspec/specs/service-health-ping/spec.md
- */
- #[NoAdminRequired]
- public function validate(): JSONResponse
- {
- if ($this->resolveUserId() === null) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'unauthorized'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
-
- $config = $this->request->getParam(key: 'config');
- if (is_array(value: $config) === false) {
- $config = [];
- }
-
- $errors = $this->healthPingService->validateConfig(config: $config);
-
- return new JSONResponse(
- data: ['valid' => ($errors === []), 'errors' => $errors],
- statusCode: Http::STATUS_OK
- );
- }//end validate()
-
- /**
- * Resolve the active user's UID, or `null` for anonymous.
- *
- * @return string|null
- */
- private function resolveUserId(): ?string
- {
- $user = $this->userSession->getUser();
- if ($user === null) {
- return null;
- }
-
- return $user->getUID();
- }//end resolveUserId()
+class HealthPingController extends Controller {
+ /**
+ * Constructor.
+ *
+ * @param IRequest $request HTTP request.
+ * @param HealthPingService $healthPingService Resolves + caches + validates health-ping badges.
+ * @param PermissionService $permissionService Dashboard/placement permission gate.
+ * @param IUserSession $userSession Session accessor.
+ * @param LoggerInterface $logger PSR logger.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly HealthPingService $healthPingService,
+ private readonly PermissionService $permissionService,
+ private readonly IUserSession $userSession,
+ private readonly LoggerInterface $logger,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
+
+ /**
+ * `GET /api/health-ping/{placementId}`
+ *
+ * Returns the health badge for one placement. Returns 401 when
+ * anonymous, 403 when the caller may not view the underlying
+ * dashboard (REQ-HPING-003 "Caller authorization" — the ping is NEVER
+ * performed in that case), 404 when the placement does not exist or
+ * has no ping configured, else 200 with the badge (possibly
+ * `stale: true`).
+ *
+ * @param integer $placementId The widget placement id.
+ *
+ * @return JSONResponse
+ *
+ * @spec openspec/specs/service-health-ping/spec.md
+ */
+ #[NoAdminRequired]
+ #[NoCSRFRequired]
+ public function show(int $placementId): JSONResponse {
+ $userId = $this->resolveUserId();
+ if ($userId === null) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'unauthorized'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
+
+ // REQ-HPING-003 "Caller authorization" — the auth guard runs
+ // BEFORE any resolution/ping is attempted.
+ if ($this->permissionService->canViewPlacement(userId: $userId, placementId: $placementId) === false) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'forbidden'],
+ statusCode: Http::STATUS_FORBIDDEN
+ );
+ }
+
+ try {
+ $badge = $this->healthPingService->resolveForPlacement(placementId: $placementId);
+ } catch (Throwable $exception) {
+ $this->logger->error(
+ message: 'Unexpected health-ping resolution failure',
+ context: ['app' => Application::APP_ID, 'exception' => $exception->getMessage()]
+ );
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'unknown_error'],
+ statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }
+
+ if (isset($badge['error']) === true) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => $badge['error']],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }
+
+ return new JSONResponse(
+ data: $badge,
+ statusCode: Http::STATUS_OK
+ );
+ }//end show()
+
+ /**
+ * `POST /api/health-ping/validate`
+ *
+ * Validates a candidate health-ping config before the author saves
+ * the placement (REQ-HPING-001 "rejected at save time" — host
+ * allow-list, fail-closed). Performs NO ping — only the allow-list
+ * check that `resolveForPlacement()` would apply.
+ *
+ * @return JSONResponse `{valid: bool, errors: string[]}`.
+ *
+ * @spec openspec/specs/service-health-ping/spec.md
+ */
+ #[NoAdminRequired]
+ public function validate(): JSONResponse {
+ if ($this->resolveUserId() === null) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'unauthorized'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
+
+ $config = $this->request->getParam(key: 'config');
+ if (is_array(value: $config) === false) {
+ $config = [];
+ }
+
+ $errors = $this->healthPingService->validateConfig(config: $config);
+
+ return new JSONResponse(
+ data: ['valid' => ($errors === []), 'errors' => $errors],
+ statusCode: Http::STATUS_OK
+ );
+ }//end validate()
+
+ /**
+ * Resolve the active user's UID, or `null` for anonymous.
+ *
+ * @return string|null
+ */
+ private function resolveUserId(): ?string {
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ return null;
+ }
+
+ return $user->getUID();
+ }//end resolveUserId()
}//end class
diff --git a/lib/Controller/IframeController.php b/lib/Controller/IframeController.php
index 36d58e09..5b96a05b 100644
--- a/lib/Controller/IframeController.php
+++ b/lib/Controller/IframeController.php
@@ -46,112 +46,108 @@
*
* @spec openspec/specs/iframe-embed-widget/spec.md
*/
-class IframeController extends Controller
-{
- /**
- * Constructor.
- *
- * @param IRequest $request HTTP request.
- * @param IframeService $iframeService Allow-list validation + sandbox sanitisation.
- * @param IUserSession $userSession Session accessor.
- */
- public function __construct(
- IRequest $request,
- private readonly IframeService $iframeService,
- private readonly IUserSession $userSession,
- ) {
- parent::__construct(
- appName: Application::APP_ID,
- request: $request
- );
- }//end __construct()
+class IframeController extends Controller {
+ /**
+ * Constructor.
+ *
+ * @param IRequest $request HTTP request.
+ * @param IframeService $iframeService Allow-list validation + sandbox sanitisation.
+ * @param IUserSession $userSession Session accessor.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly IframeService $iframeService,
+ private readonly IUserSession $userSession,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
- /**
- * `POST /api/iframe/validate-url`
- *
- * Validates a candidate iframe config before the author saves the
- * placement (REQ-IFRAME-002 "rejected at save time" — host allow-list,
- * fail-closed). Requires only an authenticated caller — the allow-list
- * itself is admin-controlled, not per-user.
- *
- * @return JSONResponse `{valid: bool, errors: string[]}`.
- *
- * @spec openspec/specs/iframe-embed-widget/spec.md
- */
- #[NoAdminRequired]
- public function validateUrl(): JSONResponse
- {
- if ($this->resolveUserId() === null) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'unauthorized'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
+ /**
+ * `POST /api/iframe/validate-url`
+ *
+ * Validates a candidate iframe config before the author saves the
+ * placement (REQ-IFRAME-002 "rejected at save time" — host allow-list,
+ * fail-closed). Requires only an authenticated caller — the allow-list
+ * itself is admin-controlled, not per-user.
+ *
+ * @return JSONResponse `{valid: bool, errors: string[]}`.
+ *
+ * @spec openspec/specs/iframe-embed-widget/spec.md
+ */
+ #[NoAdminRequired]
+ public function validateUrl(): JSONResponse {
+ if ($this->resolveUserId() === null) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'unauthorized'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
- $config = $this->request->getParam(key: 'config');
- if (is_array(value: $config) === false) {
- $config = [];
- }
+ $config = $this->request->getParam(key: 'config');
+ if (is_array(value: $config) === false) {
+ $config = [];
+ }
- $errors = $this->iframeService->validateConfig(config: $config);
+ $errors = $this->iframeService->validateConfig(config: $config);
- return new JSONResponse(
- data: ['valid' => ($errors === []), 'errors' => $errors],
- statusCode: Http::STATUS_OK
- );
- }//end validateUrl()
+ return new JSONResponse(
+ data: ['valid' => ($errors === []), 'errors' => $errors],
+ statusCode: Http::STATUS_OK
+ );
+ }//end validateUrl()
- /**
- * `POST /api/iframe/framable`
- *
- * Server-side check of whether a URL may actually be framed
- * (REQ-IFRAME-003 "graceful degradation"). The browser cannot tell an
- * `X-Frame-Options: DENY` / `frame-ancestors 'none'` refusal apart from a
- * normal cross-origin embed, so the widget calls this on mount and shows
- * the fallback card up front when the target refuses framing, instead of
- * a permanently blank frame. Allow-list fail-closed; never leaks the
- * target's response body.
- *
- * @return JSONResponse `{framable: bool, reason: string}`.
- *
- * @spec openspec/specs/iframe-embed-widget/spec.md
- */
- #[NoAdminRequired]
- public function checkFramable(): JSONResponse
- {
- if ($this->resolveUserId() === null) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'unauthorized'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
+ /**
+ * `POST /api/iframe/framable`
+ *
+ * Server-side check of whether a URL may actually be framed
+ * (REQ-IFRAME-003 "graceful degradation"). The browser cannot tell an
+ * `X-Frame-Options: DENY` / `frame-ancestors 'none'` refusal apart from a
+ * normal cross-origin embed, so the widget calls this on mount and shows
+ * the fallback card up front when the target refuses framing, instead of
+ * a permanently blank frame. Allow-list fail-closed; never leaks the
+ * target's response body.
+ *
+ * @return JSONResponse `{framable: bool, reason: string}`.
+ *
+ * @spec openspec/specs/iframe-embed-widget/spec.md
+ */
+ #[NoAdminRequired]
+ public function checkFramable(): JSONResponse {
+ if ($this->resolveUserId() === null) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'unauthorized'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
- $url = trim(string: (string) $this->request->getParam(key: 'url', default: ''));
- if ($url === '') {
- return new JSONResponse(
- data: ['framable' => false, 'reason' => 'url_required'],
- statusCode: Http::STATUS_OK
- );
- }
+ $url = trim(string: (string)$this->request->getParam(key: 'url', default: ''));
+ if ($url === '') {
+ return new JSONResponse(
+ data: ['framable' => false, 'reason' => 'url_required'],
+ statusCode: Http::STATUS_OK
+ );
+ }
- return new JSONResponse(
- data: $this->iframeService->checkFramable(url: $url),
- statusCode: Http::STATUS_OK
- );
- }//end checkFramable()
+ return new JSONResponse(
+ data: $this->iframeService->checkFramable(url: $url),
+ statusCode: Http::STATUS_OK
+ );
+ }//end checkFramable()
- /**
- * Resolve the active user's UID, or `null` for anonymous.
- *
- * @return string|null
- */
- private function resolveUserId(): ?string
- {
- $user = $this->userSession->getUser();
- if ($user === null) {
- return null;
- }
+ /**
+ * Resolve the active user's UID, or `null` for anonymous.
+ *
+ * @return string|null
+ */
+ private function resolveUserId(): ?string {
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ return null;
+ }
- return $user->getUID();
- }//end resolveUserId()
+ return $user->getUID();
+ }//end resolveUserId()
}//end class
diff --git a/lib/Controller/KioskController.php b/lib/Controller/KioskController.php
index 96c3166e..a2fb497b 100644
--- a/lib/Controller/KioskController.php
+++ b/lib/Controller/KioskController.php
@@ -50,267 +50,262 @@
*
* @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
*/
-class KioskController extends Controller
-{
- /**
- * Constructor.
- *
- * @param IRequest $request The incoming request.
- * @param KioskService $kioskService The kiosk-playlist service.
- * @param PublicShareContext $shareContext Request-scoped read-only bearer marker.
- * @param LoggerInterface $logger PSR-3 logger.
- * @param string|null $userId Authenticated user ID (null on public route).
- */
- public function __construct(
- IRequest $request,
- private readonly KioskService $kioskService,
- private readonly PublicShareContext $shareContext,
- private readonly LoggerInterface $logger,
- private readonly ?string $userId,
- ) {
- parent::__construct(
- appName: Application::APP_ID,
- request: $request
- );
- }//end __construct()
+class KioskController extends Controller {
+ /**
+ * Constructor.
+ *
+ * @param IRequest $request The incoming request.
+ * @param KioskService $kioskService The kiosk-playlist service.
+ * @param PublicShareContext $shareContext Request-scoped read-only bearer marker.
+ * @param LoggerInterface $logger PSR-3 logger.
+ * @param string|null $userId Authenticated user ID (null on public route).
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly KioskService $kioskService,
+ private readonly PublicShareContext $shareContext,
+ private readonly LoggerInterface $logger,
+ private readonly ?string $userId,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
- /**
- * Create a kiosk playlist.
- *
- * Owner-or-admin per referenced dashboard (REQ-KIOSK-002).
- *
- * @param string|null $name Playlist name.
- * @param array|null $entries Entries [{dashboardUuid, dwellSeconds}, ...].
- * @param int|null $refreshSeconds Requested refresh interval.
- *
- * @return DataResponse HTTP 201 with playlist payload, 403, or 401.
- *
- * @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
- */
- #[NoAdminRequired]
- public function create(
- ?string $name=null,
- ?array $entries=null,
- ?int $refreshSeconds=null
- ): DataResponse {
- if ($this->userId === null) {
- return new DataResponse(
- data: ['error' => 'Not logged in'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
+ /**
+ * Create a kiosk playlist.
+ *
+ * Owner-or-admin per referenced dashboard (REQ-KIOSK-002).
+ *
+ * @param string|null $name Playlist name.
+ * @param array|null $entries Entries [{dashboardUuid, dwellSeconds}, ...].
+ * @param int|null $refreshSeconds Requested refresh interval.
+ *
+ * @return DataResponse HTTP 201 with playlist payload, 403, or 401.
+ *
+ * @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
+ */
+ #[NoAdminRequired]
+ public function create(
+ ?string $name = null,
+ ?array $entries = null,
+ ?int $refreshSeconds = null,
+ ): DataResponse {
+ if ($this->userId === null) {
+ return new DataResponse(
+ data: ['error' => 'Not logged in'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
- try {
- $playlist = $this->kioskService->createPlaylist(
- name: (string) ($name ?? ''),
- entries: ($entries ?? []),
- refresh: (int) ($refreshSeconds ?? KioskService::REFRESH_DEFAULT),
- callerId: $this->userId
- );
- return new DataResponse(
- data: $playlist->jsonSerialize(),
- statusCode: Http::STATUS_CREATED
- );
- } catch (OCSForbiddenException) {
- return new DataResponse(
- data: ['error' => 'Not authorized'],
- statusCode: Http::STATUS_FORBIDDEN
- );
- } catch (Exception $e) {
- $this->logError(message: $e->getMessage());
- return new DataResponse(
- data: ['error' => 'Internal error'],
- statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
- );
- }//end try
- }//end create()
+ try {
+ $playlist = $this->kioskService->createPlaylist(
+ name: (string)($name ?? ''),
+ entries: ($entries ?? []),
+ refresh: (int)($refreshSeconds ?? KioskService::REFRESH_DEFAULT),
+ callerId: $this->userId
+ );
+ return new DataResponse(
+ data: $playlist->jsonSerialize(),
+ statusCode: Http::STATUS_CREATED
+ );
+ } catch (OCSForbiddenException) {
+ return new DataResponse(
+ data: ['error' => 'Not authorized'],
+ statusCode: Http::STATUS_FORBIDDEN
+ );
+ } catch (Exception $e) {
+ $this->logError(message: $e->getMessage());
+ return new DataResponse(
+ data: ['error' => 'Internal error'],
+ statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }//end try
+ }//end create()
- /**
- * List playlists visible to the caller.
- *
- * Own playlists for users, all playlists for admins (REQ-KIOSK-002).
- *
- * @return DataResponse HTTP 200 array of playlists or 401.
- *
- * @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
- */
- #[NoAdminRequired]
- public function index(): DataResponse
- {
- if ($this->userId === null) {
- return new DataResponse(
- data: ['error' => 'Not logged in'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
+ /**
+ * List playlists visible to the caller.
+ *
+ * Own playlists for users, all playlists for admins (REQ-KIOSK-002).
+ *
+ * @return DataResponse HTTP 200 array of playlists or 401.
+ *
+ * @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
+ */
+ #[NoAdminRequired]
+ public function index(): DataResponse {
+ if ($this->userId === null) {
+ return new DataResponse(
+ data: ['error' => 'Not logged in'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
- $playlists = $this->kioskService->listPlaylists(callerId: $this->userId);
- return new DataResponse(
- data: array_map(
- callback: static fn ($playlist) => $playlist->jsonSerialize(),
- array: $playlists
- )
- );
- }//end index()
+ $playlists = $this->kioskService->listPlaylists(callerId: $this->userId);
+ return new DataResponse(
+ data: array_map(
+ callback: static fn ($playlist) => $playlist->jsonSerialize(),
+ array: $playlists
+ )
+ );
+ }//end index()
- /**
- * Update a kiosk playlist.
- *
- * Owner-or-admin, re-validates every referenced dashboard (REQ-KIOSK-002).
- *
- * @param int $id Playlist primary key.
- * @param string|null $name Playlist name.
- * @param array|null $entries Entries [{dashboardUuid, dwellSeconds}, ...].
- * @param int|null $refreshSeconds Requested refresh interval.
- *
- * @return DataResponse HTTP 200 with playlist payload, 403, 404, or 401.
- *
- * @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
- */
- #[NoAdminRequired]
- public function update(
- int $id,
- ?string $name=null,
- ?array $entries=null,
- ?int $refreshSeconds=null
- ): DataResponse {
- if ($this->userId === null) {
- return new DataResponse(
- data: ['error' => 'Not logged in'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
+ /**
+ * Update a kiosk playlist.
+ *
+ * Owner-or-admin, re-validates every referenced dashboard (REQ-KIOSK-002).
+ *
+ * @param int $id Playlist primary key.
+ * @param string|null $name Playlist name.
+ * @param array|null $entries Entries [{dashboardUuid, dwellSeconds}, ...].
+ * @param int|null $refreshSeconds Requested refresh interval.
+ *
+ * @return DataResponse HTTP 200 with playlist payload, 403, 404, or 401.
+ *
+ * @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
+ */
+ #[NoAdminRequired]
+ public function update(
+ int $id,
+ ?string $name = null,
+ ?array $entries = null,
+ ?int $refreshSeconds = null,
+ ): DataResponse {
+ if ($this->userId === null) {
+ return new DataResponse(
+ data: ['error' => 'Not logged in'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
- try {
- $playlist = $this->kioskService->updatePlaylist(
- id: $id,
- name: (string) ($name ?? ''),
- entries: ($entries ?? []),
- refresh: (int) ($refreshSeconds ?? KioskService::REFRESH_DEFAULT),
- callerId: $this->userId
- );
- return new DataResponse(data: $playlist->jsonSerialize());
- } catch (PlaylistNotFoundException) {
- return new DataResponse(
- data: ['error' => 'Not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- } catch (OCSForbiddenException) {
- return new DataResponse(
- data: ['error' => 'Not authorized'],
- statusCode: Http::STATUS_FORBIDDEN
- );
- } catch (Exception $e) {
- $this->logError(message: $e->getMessage());
- return new DataResponse(
- data: ['error' => 'Internal error'],
- statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
- );
- }//end try
- }//end update()
+ try {
+ $playlist = $this->kioskService->updatePlaylist(
+ id: $id,
+ name: (string)($name ?? ''),
+ entries: ($entries ?? []),
+ refresh: (int)($refreshSeconds ?? KioskService::REFRESH_DEFAULT),
+ callerId: $this->userId
+ );
+ return new DataResponse(data: $playlist->jsonSerialize());
+ } catch (PlaylistNotFoundException) {
+ return new DataResponse(
+ data: ['error' => 'Not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ } catch (OCSForbiddenException) {
+ return new DataResponse(
+ data: ['error' => 'Not authorized'],
+ statusCode: Http::STATUS_FORBIDDEN
+ );
+ } catch (Exception $e) {
+ $this->logError(message: $e->getMessage());
+ return new DataResponse(
+ data: ['error' => 'Internal error'],
+ statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }//end try
+ }//end update()
- /**
- * Soft-revoke a kiosk playlist.
- *
- * Owner-or-admin only, idempotent (REQ-KIOSK-002).
- *
- * @param int $id Playlist primary key.
- *
- * @return DataResponse HTTP 204, 403, 404, or 401.
- *
- * @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
- */
- #[NoAdminRequired]
- public function destroy(int $id): DataResponse
- {
- if ($this->userId === null) {
- return new DataResponse(
- data: ['error' => 'Not logged in'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
+ /**
+ * Soft-revoke a kiosk playlist.
+ *
+ * Owner-or-admin only, idempotent (REQ-KIOSK-002).
+ *
+ * @param int $id Playlist primary key.
+ *
+ * @return DataResponse HTTP 204, 403, 404, or 401.
+ *
+ * @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
+ */
+ #[NoAdminRequired]
+ public function destroy(int $id): DataResponse {
+ if ($this->userId === null) {
+ return new DataResponse(
+ data: ['error' => 'Not logged in'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
- try {
- $this->kioskService->revokePlaylist(id: $id, callerId: $this->userId);
- return new DataResponse(data: [], statusCode: Http::STATUS_NO_CONTENT);
- } catch (PlaylistNotFoundException) {
- return new DataResponse(
- data: ['error' => 'Not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- } catch (OCSForbiddenException) {
- return new DataResponse(
- data: ['error' => 'Not authorized'],
- statusCode: Http::STATUS_FORBIDDEN
- );
- } catch (Exception $e) {
- $this->logError(message: $e->getMessage());
- return new DataResponse(
- data: ['error' => 'Internal error'],
- statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
- );
- }//end try
- }//end destroy()
+ try {
+ $this->kioskService->revokePlaylist(id: $id, callerId: $this->userId);
+ return new DataResponse(data: [], statusCode: Http::STATUS_NO_CONTENT);
+ } catch (PlaylistNotFoundException) {
+ return new DataResponse(
+ data: ['error' => 'Not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ } catch (OCSForbiddenException) {
+ return new DataResponse(
+ data: ['error' => 'Not authorized'],
+ statusCode: Http::STATUS_FORBIDDEN
+ );
+ } catch (Exception $e) {
+ $this->logError(message: $e->getMessage());
+ return new DataResponse(
+ data: ['error' => 'Internal error'],
+ statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }//end try
+ }//end destroy()
- /**
- * Anonymously render a kiosk playlist via its token.
- *
- * Returns the playlist descriptor and the read-only render payload for
- * every entry whose dashboard still exists. Unknown or revoked tokens
- * return HTTP 404 with an identical shape (no existence leak). Shares the
- * `launchpad_share_access` brute-force bucket with public-share renders.
- *
- * @param string $token The playlist token from the URL.
- *
- * @return DataResponse HTTP 200 render payload, 404 if invalid, 429 when throttled.
- *
- * @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
- */
- #[PublicPage]
- #[NoCSRFRequired]
- #[AnonRateLimit(limit: 60, period: 60)]
- #[BruteForceProtection(action: PublicShareService::ACTION_SHARE_ACCESS)]
- public function render(string $token): DataResponse
- {
- try {
- $result = $this->kioskService->renderPlaylist(token: $token);
+ /**
+ * Anonymously render a kiosk playlist via its token.
+ *
+ * Returns the playlist descriptor and the read-only render payload for
+ * every entry whose dashboard still exists. Unknown or revoked tokens
+ * return HTTP 404 with an identical shape (no existence leak). Shares the
+ * `launchpad_share_access` brute-force bucket with public-share renders.
+ *
+ * @param string $token The playlist token from the URL.
+ *
+ * @return DataResponse HTTP 200 render payload, 404 if invalid, 429 when throttled.
+ *
+ * @spec openspec/changes/dashboard-kiosk-mode/tasks.md#task-4
+ */
+ #[PublicPage]
+ #[NoCSRFRequired]
+ #[AnonRateLimit(limit: 60, period: 60)]
+ #[BruteForceProtection(action: PublicShareService::ACTION_SHARE_ACCESS)]
+ public function render(string $token): DataResponse {
+ try {
+ $result = $this->kioskService->renderPlaylist(token: $token);
- // Mark the request as a read-only bearer so any mutation service
- // touched during render-payload hydration trips
- // ShareReadOnlyException, mirroring public-share REQ-PSHR-006.
- $this->shareContext->markBearer(token: $token);
+ // Mark the request as a read-only bearer so any mutation service
+ // touched during render-payload hydration trips
+ // ShareReadOnlyException, mirroring public-share REQ-PSHR-006.
+ $this->shareContext->markBearer(token: $token);
- return new DataResponse(data: $result);
- } catch (PlaylistNotFoundException) {
- $response = new DataResponse(
- data: ['error' => 'Not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- // Register a brute-force attempt on the shared bucket so token
- // scanning the kiosk route counts toward the same throttle.
- $response->throttle(['action' => PublicShareService::ACTION_SHARE_ACCESS]);
- return $response;
- } catch (Exception $e) {
- $this->logError(message: $e->getMessage());
- return new DataResponse(
- data: ['error' => 'Internal error'],
- statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
- );
- }//end try
- }//end render()
+ return new DataResponse(data: $result);
+ } catch (PlaylistNotFoundException) {
+ $response = new DataResponse(
+ data: ['error' => 'Not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ // Register a brute-force attempt on the shared bucket so token
+ // scanning the kiosk route counts toward the same throttle.
+ $response->throttle(['action' => PublicShareService::ACTION_SHARE_ACCESS]);
+ return $response;
+ } catch (Exception $e) {
+ $this->logError(message: $e->getMessage());
+ return new DataResponse(
+ data: ['error' => 'Internal error'],
+ statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }//end try
+ }//end render()
- /**
- * Log a non-sensitive error message.
- *
- * @param string $message The error message.
- *
- * @return void
- */
- private function logError(string $message): void
- {
- $this->logger->warning(
- message: 'KioskController error: '.$message,
- context: ['app' => Application::APP_ID]
- );
- }//end logError()
+ /**
+ * Log a non-sensitive error message.
+ *
+ * @param string $message The error message.
+ *
+ * @return void
+ */
+ private function logError(string $message): void {
+ $this->logger->warning(
+ message: 'KioskController error: ' . $message,
+ context: ['app' => Application::APP_ID]
+ );
+ }//end logError()
}//end class
diff --git a/lib/Controller/LiveTileController.php b/lib/Controller/LiveTileController.php
index 98bce948..b9fba652 100644
--- a/lib/Controller/LiveTileController.php
+++ b/lib/Controller/LiveTileController.php
@@ -55,168 +55,163 @@
*
* @spec openspec/specs/live-data-tile-widget/spec.md
*/
-class LiveTileController extends Controller
-{
- /**
- * Constructor.
- *
- * @param IRequest $request HTTP request.
- * @param LiveTileService $liveTileService Resolves + caches + validates live-tile values.
- * @param PermissionService $permissionService Dashboard/placement permission gate.
- * @param IUserSession $userSession Session accessor.
- * @param LoggerInterface $logger PSR logger.
- */
- public function __construct(
- IRequest $request,
- private readonly LiveTileService $liveTileService,
- private readonly PermissionService $permissionService,
- private readonly IUserSession $userSession,
- private readonly LoggerInterface $logger,
- ) {
- parent::__construct(
- appName: Application::APP_ID,
- request: $request
- );
- }//end __construct()
-
- /**
- * `GET /api/livetile/{placementId}`
- *
- * Returns the live-tile value for one placement. Returns 401 when
- * anonymous, 403 when the caller may not view the underlying
- * dashboard (REQ-LIVETILE-003 "Caller authorization" — the fetch is
- * NEVER performed in that case), 404 when the placement does not
- * exist, else 200 with the value (possibly `stale: true`).
- *
- * @param integer $placementId The widget placement id.
- *
- * @return JSONResponse
- *
- * @spec openspec/specs/live-data-tile-widget/spec.md
- */
- #[NoAdminRequired]
- #[NoCSRFRequired]
- public function show(int $placementId): JSONResponse
- {
- $userId = $this->resolveUserId();
- if ($userId === null) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'unauthorized'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
-
- // REQ-LIVETILE-003 "Caller authorization" — the auth guard runs
- // BEFORE any resolution/fetch is attempted.
- if ($this->permissionService->canViewPlacement(userId: $userId, placementId: $placementId) === false) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'forbidden'],
- statusCode: Http::STATUS_FORBIDDEN
- );
- }
-
- try {
- $reading = $this->liveTileService->resolveForPlacement(placementId: $placementId);
- } catch (Throwable $exception) {
- $this->logger->error(
- message: 'Unexpected live-tile resolution failure',
- context: ['app' => Application::APP_ID, 'exception' => $exception->getMessage()]
- );
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'unknown_error'],
- statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
- );
- }
-
- if (isset($reading['error']) === true) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => $reading['error']],
- statusCode: Http::STATUS_NOT_FOUND
- );
- }
-
- return new JSONResponse(
- data: $reading,
- statusCode: Http::STATUS_OK
- );
- }//end show()
-
- /**
- * `GET /api/livetile/connector/status`
- *
- * Reports whether the OpenConnector `dashboard-http-datasource`
- * capability is currently available, so the config form can hide or
- * disable `connector` source mode (REQ-LIVETILE-005). Requires only
- * an authenticated caller — carries no placement-specific data.
- *
- * @return JSONResponse `{available: bool}`.
- *
- * @spec openspec/specs/live-data-tile-widget/spec.md
- */
- #[NoAdminRequired]
- #[NoCSRFRequired]
- public function connectorStatus(): JSONResponse
- {
- if ($this->resolveUserId() === null) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'unauthorized'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
-
- return new JSONResponse(
- data: ['available' => $this->liveTileService->isConnectorAvailable()],
- statusCode: Http::STATUS_OK
- );
- }//end connectorStatus()
-
- /**
- * `POST /api/livetile/validate-source`
- *
- * Validates a candidate source config before the author saves the
- * placement (REQ-LIVETILE-002 "rejected at save time" — host
- * allow-list, fail-closed). Performs NO fetch — only the allow-list
- * / capability-probe checks that `resolveForPlacement()` would apply.
- *
- * @return JSONResponse `{valid: bool, errors: string[]}`.
- *
- * @spec openspec/specs/live-data-tile-widget/spec.md
- */
- #[NoAdminRequired]
- public function validateSource(): JSONResponse
- {
- if ($this->resolveUserId() === null) {
- return new JSONResponse(
- data: ['status' => 'error', 'error' => 'unauthorized'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
-
- $config = $this->request->getParam(key: 'config');
- if (is_array(value: $config) === false) {
- $config = [];
- }
-
- $errors = $this->liveTileService->validateSourceConfig(config: $config);
-
- return new JSONResponse(
- data: ['valid' => ($errors === []), 'errors' => $errors],
- statusCode: Http::STATUS_OK
- );
- }//end validateSource()
-
- /**
- * Resolve the active user's UID, or `null` for anonymous.
- *
- * @return string|null
- */
- private function resolveUserId(): ?string
- {
- $user = $this->userSession->getUser();
- if ($user === null) {
- return null;
- }
-
- return $user->getUID();
- }//end resolveUserId()
+class LiveTileController extends Controller {
+ /**
+ * Constructor.
+ *
+ * @param IRequest $request HTTP request.
+ * @param LiveTileService $liveTileService Resolves + caches + validates live-tile values.
+ * @param PermissionService $permissionService Dashboard/placement permission gate.
+ * @param IUserSession $userSession Session accessor.
+ * @param LoggerInterface $logger PSR logger.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly LiveTileService $liveTileService,
+ private readonly PermissionService $permissionService,
+ private readonly IUserSession $userSession,
+ private readonly LoggerInterface $logger,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
+
+ /**
+ * `GET /api/livetile/{placementId}`
+ *
+ * Returns the live-tile value for one placement. Returns 401 when
+ * anonymous, 403 when the caller may not view the underlying
+ * dashboard (REQ-LIVETILE-003 "Caller authorization" — the fetch is
+ * NEVER performed in that case), 404 when the placement does not
+ * exist, else 200 with the value (possibly `stale: true`).
+ *
+ * @param integer $placementId The widget placement id.
+ *
+ * @return JSONResponse
+ *
+ * @spec openspec/specs/live-data-tile-widget/spec.md
+ */
+ #[NoAdminRequired]
+ #[NoCSRFRequired]
+ public function show(int $placementId): JSONResponse {
+ $userId = $this->resolveUserId();
+ if ($userId === null) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'unauthorized'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
+
+ // REQ-LIVETILE-003 "Caller authorization" — the auth guard runs
+ // BEFORE any resolution/fetch is attempted.
+ if ($this->permissionService->canViewPlacement(userId: $userId, placementId: $placementId) === false) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'forbidden'],
+ statusCode: Http::STATUS_FORBIDDEN
+ );
+ }
+
+ try {
+ $reading = $this->liveTileService->resolveForPlacement(placementId: $placementId);
+ } catch (Throwable $exception) {
+ $this->logger->error(
+ message: 'Unexpected live-tile resolution failure',
+ context: ['app' => Application::APP_ID, 'exception' => $exception->getMessage()]
+ );
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'unknown_error'],
+ statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }
+
+ if (isset($reading['error']) === true) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => $reading['error']],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }
+
+ return new JSONResponse(
+ data: $reading,
+ statusCode: Http::STATUS_OK
+ );
+ }//end show()
+
+ /**
+ * `GET /api/livetile/connector/status`
+ *
+ * Reports whether the OpenConnector `dashboard-http-datasource`
+ * capability is currently available, so the config form can hide or
+ * disable `connector` source mode (REQ-LIVETILE-005). Requires only
+ * an authenticated caller — carries no placement-specific data.
+ *
+ * @return JSONResponse `{available: bool}`.
+ *
+ * @spec openspec/specs/live-data-tile-widget/spec.md
+ */
+ #[NoAdminRequired]
+ #[NoCSRFRequired]
+ public function connectorStatus(): JSONResponse {
+ if ($this->resolveUserId() === null) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'unauthorized'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
+
+ return new JSONResponse(
+ data: ['available' => $this->liveTileService->isConnectorAvailable()],
+ statusCode: Http::STATUS_OK
+ );
+ }//end connectorStatus()
+
+ /**
+ * `POST /api/livetile/validate-source`
+ *
+ * Validates a candidate source config before the author saves the
+ * placement (REQ-LIVETILE-002 "rejected at save time" — host
+ * allow-list, fail-closed). Performs NO fetch — only the allow-list
+ * / capability-probe checks that `resolveForPlacement()` would apply.
+ *
+ * @return JSONResponse `{valid: bool, errors: string[]}`.
+ *
+ * @spec openspec/specs/live-data-tile-widget/spec.md
+ */
+ #[NoAdminRequired]
+ public function validateSource(): JSONResponse {
+ if ($this->resolveUserId() === null) {
+ return new JSONResponse(
+ data: ['status' => 'error', 'error' => 'unauthorized'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
+
+ $config = $this->request->getParam(key: 'config');
+ if (is_array(value: $config) === false) {
+ $config = [];
+ }
+
+ $errors = $this->liveTileService->validateSourceConfig(config: $config);
+
+ return new JSONResponse(
+ data: ['valid' => ($errors === []), 'errors' => $errors],
+ statusCode: Http::STATUS_OK
+ );
+ }//end validateSource()
+
+ /**
+ * Resolve the active user's UID, or `null` for anonymous.
+ *
+ * @return string|null
+ */
+ private function resolveUserId(): ?string {
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ return null;
+ }
+
+ return $user->getUID();
+ }//end resolveUserId()
}//end class
diff --git a/lib/Controller/ManifestController.php b/lib/Controller/ManifestController.php
index abda58eb..1160278c 100644
--- a/lib/Controller/ManifestController.php
+++ b/lib/Controller/ManifestController.php
@@ -49,473 +49,463 @@
* rather than the individual manifest contributors precisely to keep this
* count from growing as sections are added.
*/
-class ManifestController extends Controller
-{
- /**
- * OpenRegister register slug for launchpad dashboards.
- *
- * @var string
- */
- private const REGISTER = 'launchpad';
-
- /**
- * OpenRegister schema slug for dashboard objects.
- *
- * @var string
- */
- private const SCHEMA = 'dashboard';
-
- /**
- * V2 manifest schema URL.
- *
- * @var string
- */
- private const SCHEMA_URL = 'https://raw.githubusercontent.com/ConductionNL/nextcloud-vue/main/src/schemas/app-manifest-v2.schema.json';
-
- /**
- * Constructor.
- *
- * @param IRequest $request The HTTP request.
- * @param ContainerInterface $container The Nextcloud DI container; used to
- * lazy-load ObjectService so that launchpad
- * degrades gracefully when OpenRegister
- * is not yet active.
- * @param ActionAuthService $actionAuth ADR-023 action authorization.
- * @param IUserSession $userSession User session (IUser resolution).
- * @param LoggerInterface $logger PSR logger.
- * @param string|null $userId The authenticated user ID, injected
- * by the DI container.
- */
- public function __construct(
- IRequest $request,
- private readonly ContainerInterface $container,
- private readonly ActionAuthService $actionAuth,
- private readonly IUserSession $userSession,
- private readonly LoggerInterface $logger,
- private readonly ?string $userId,
- ) {
- parent::__construct(
- appName: Application::APP_ID,
- request: $request
- );
- }//end __construct()
-
- /**
- * Build and return the v2 app manifest for the authenticated user.
- *
- * Reads the user's dashboard objects from OpenRegister. Each object with
- * a `slug` and `title` property becomes one page entry and one menu entry.
- * Objects the user owns, plus objects explicitly granted to them via
- * OpenRegister's per-object sharing primitive, are included.
- *
- * Route: GET /apps/launchpad/api/manifest
- *
- * @return JSONResponse A JSON document conforming to the v2 manifest
- * schema. Returns HTTP 401 when no user is
- * authenticated, HTTP 503 when OpenRegister is
- * unavailable.
- *
- * @spec manifest-v2-runtime:REQ-MVR-001
- * @spec openspec/specs/runtime-shell/spec.md
- */
- #[NoAdminRequired]
- #[NoCSRFRequired]
- public function index(): JSONResponse
- {
- if ($this->userId === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- $user = $this->userSession->getUser();
- if ($user === null) {
- return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
- }
-
- try {
- $this->actionAuth->requireAction($user, 'manifest.index');
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- // Retrieve ObjectService lazily — OpenRegister may not be enabled on
- // every instance. Returning an empty manifest (not an error) lets the
- // frontend render its "no dashboards yet" CTA without a red alert.
- try {
- /*
- * @var \OCA\OpenRegister\Service\ObjectService $objectService
- */
-
- $objectService = $this->container->get('OCA\OpenRegister\Service\ObjectService');
- } catch (\Throwable $e) {
- $this->logger->warning(
- 'LaunchPad: OpenRegister ObjectService unavailable — returning empty manifest. '.$e->getMessage(),
- ['app' => Application::APP_ID]
- );
-
- return new JSONResponse($this->buildManifest(dashboards: [], userId: $this->userId));
- }//end try
-
- // Fetch all dashboard objects owned by or shared with the current user.
- $dashboards = $this->fetchUserDashboards(objectService: $objectService, userId: $this->userId);
-
- return new JSONResponse($this->buildManifest(dashboards: $dashboards, userId: $this->userId));
-
- }//end index()
-
- /**
- * Maximum number of granted dashboards folded into one manifest.
- *
- * A bound, not a policy: the grant lookup is cheap but the follow-up load is
- * one IN(...) query whose parameter list should not grow without limit. If a
- * user ever exceeds this, the manifest is truncated rather than slow — and
- * the truncation is logged rather than silent, so it cannot be mistaken for
- * "the user has no shared dashboards".
- *
- * @var int
- */
- private const MAX_GRANTED = 200;
-
- /**
- * Fetch dashboard objects from OpenRegister for the given user.
- *
- * C5 fix (REQ-MVR-001): replaces the non-existent `findObjects()` call
- * (which caused a BadMethodCallException silently swallowed by Throwable)
- * with the real `ObjectService::findAll()` API. The `owner` filter
- * constrains results to the calling user's records — without it every
- * user would receive the full dataset (latent IDOR on top of the API drift).
- *
- * Two sources, deduplicated: dashboards the user OWNS, and dashboards
- * explicitly GRANTED to them through OpenRegister's per-object sharing
- * primitive. The owner filter is deliberately kept on the first query rather
- * than replaced by "let RBAC decide" — see fetchGrantedDashboards() for why
- * the additive shape is the safe one.
- *
- * @param object $objectService The OpenRegister ObjectService instance.
- * @param string $userId The authenticated Nextcloud user ID.
- *
- * @return array> Flat list of dashboard data arrays.
- */
- private function fetchUserDashboards(object $objectService, string $userId): array
- {
- $dashboards = [];
- $seen = [];
-
- try {
- // C5 fix: use the real ObjectService::findAll() API.
- // `findObjects()` does not exist; the old call threw
- // BadMethodCallException that was silently swallowed, causing the
- // manifest to always return empty pages/menu arrays.
- //
- // The owner filter MUST be NESTED under `@self`. OpenRegister splits
- // filters into metadata filters (the magic table's `_`-prefixed
- // columns, addressed as a nested `@self` array) and property filters
- // (matched against the schema's own properties). A bare `owner` is
- // therefore read as a property filter on an `owner` property, which
- // the dashboard schema does not have — so it matched nothing and
- // this endpoint returned an EMPTY MANIFEST to every user, including
- // the owner of the dashboards.
- //
- // Measured on a live instance with admin owning two dashboards: no
- // owner filter returned 2; a bare `owner => admin` returned 0; a
- // DOTTED `@self.owner => admin` also returned 0; the nested
- // `@self => [owner => admin]` returned 2. The control was a nested
- // filter with a nonexistent user, which returned 0 — without it,
- // "nested returns 2" could not be distinguished from "the filter was
- // ignored, here is everything", which is the failure mode that
- // produced the always-empty manifest in the first place.
- $ownedResults = $objectService->findAll(
- config: [
- 'filters' => [
- 'register' => self::REGISTER,
- 'schema' => self::SCHEMA,
- '@self' => ['owner' => $userId],
- ],
- 'limit' => 500,
- ]
- );
-
- if (is_array($ownedResults) === true) {
- $this->foldInto(rows: $ownedResults, dashboards: $dashboards, seen: $seen, extract: true);
- }
- } catch (DoesNotExistException $e) {
- // The 'mydash' register or 'dashboard' schema has not been
- // provisioned in OpenRegister on this instance yet. That simply
- // means the user has no dashboards — degrade to an empty manifest
- // so the frontend renders its "no dashboards yet" CTA instead of a
- // 500 (OpenRegister surfaces this as DoesNotExistException, which
- // extends \Exception and so is not a RuntimeException).
- $this->logger->info(
- 'MyDash: OpenRegister register/schema not provisioned — returning empty manifest. '.$e->getMessage(),
- ['app' => Application::APP_ID, 'userId' => $userId]
- );
- } catch (\RuntimeException | \InvalidArgumentException $e) {
- // Narrow catch: only handle recoverable OR API errors. Let
- // unexpected errors propagate so they are visible in the logs.
- $this->logger->error(
- 'LaunchPad: failed to fetch dashboards from OpenRegister: '.$e->getMessage(),
- ['app' => Application::APP_ID, 'userId' => $userId]
- );
- }//end try
-
- // Second source: dashboards explicitly granted to this user. Additive,
- // and folded through the SAME $seen map so a dashboard the user both
- // owns and was granted appears once.
- $this->foldInto(
- rows: $this->fetchGrantedDashboards(objectService: $objectService, userId: $userId),
- dashboards: $dashboards,
- seen: $seen,
- extract: false
- );
-
- return $dashboards;
-
- }//end fetchUserDashboards()
-
- /**
- * Fold one source's rows into the accumulator, skipping ones already seen.
- *
- * Shared by both sources on purpose: the owned query and the grant query must
- * dedupe by the SAME identity rule, or a dashboard the user both owns and was
- * granted would appear twice in the manifest.
- *
- * @param array $rows Rows from one source.
- * @param array> $dashboards Accumulator, by reference.
- * @param array $seen Identity map, by reference.
- * @param bool $extract Whether the rows still
- * need extractData() —
- * the granted source has
- * already normalised
- * them.
- *
- * @return void
- */
- private function foldInto(array $rows, array &$dashboards, array &$seen, bool $extract): void
- {
- foreach ($rows as $row) {
- $data = $row;
- if ($extract === true) {
- $data = $this->extractData(item: $row);
- }
-
- if (is_array($data) === false || empty($data) === true) {
- continue;
- }
-
- $id = ($data['id'] ?? $data['uuid'] ?? $data['slug'] ?? null);
- if ($id !== null && isset($seen[$id]) === false) {
- $seen[$id] = true;
- $dashboards[] = $data;
- }
- }
-
- }//end foldInto()
-
- /**
- * Dashboard objects explicitly granted to this user, via OpenRegister.
- *
- * WHY THIS IS ADDITIVE, rather than "drop the owner filter and let RBAC
- * decide". Letting RBAC decide is the tidier design and it is what the
- * OpenRegister `private` scope exists for — but it is only safe once the
- * `dashboard` schema actually carries `scope: private`. A register-descriptor
- * change lands through a repair step on upgrade, so there is necessarily a
- * window (and, on any instance where that import did not apply, an
- * indefinite one) in which the schema is still unscoped. An unfiltered
- * findAll() against an unscoped schema returns EVERY user's dashboards. So
- * the owner filter stays, and grants only ever ADD rows. The failure mode of
- * this shape is a missing dashboard; the failure mode of the other is a
- * cross-tenant leak in the manifest.
- *
- * `read` is the verb, because appearing in someone's manifest is exactly a
- * read. The resolver answers only for the five core permission verbs and
- * refuses anything else, so this cannot silently widen.
- *
- * Fails soft and empty: OpenRegister may be present without the sharing
- * primitive (an older release), in which case the class is simply absent and
- * the manifest degrades to owned-only — the behaviour before this change.
- *
- * @param object $objectService The OpenRegister ObjectService instance.
- * @param string $userId The authenticated Nextcloud user ID.
- *
- * @return array> Granted dashboard data arrays.
- */
- private function fetchGrantedDashboards(object $objectService, string $userId): array
- {
- try {
- $grantResolver = $this->container->get('OCA\OpenRegister\Service\Rbac\ObjectGrantResolver');
- } catch (\Throwable $e) {
- // OpenRegister without the per-object sharing primitive. Not an
- // error: degrade to owned-only, which is the pre-existing behaviour.
- $this->logger->debug(
- 'LaunchPad: OpenRegister object-grant resolver unavailable — manifest is owned-only. '.$e->getMessage(),
- ['app' => Application::APP_ID]
- );
-
- return [];
- }
-
- try {
- // Keys, not values: the resolver returns uuid => permission
- // bitmask, so array_values() would yield the bitmasks.
- $grantedUuids = array_keys($grantResolver->grantedObjectUuidsFor($userId, 'read'));
- if (empty($grantedUuids) === true) {
- return [];
- }
-
- if (count($grantedUuids) > self::MAX_GRANTED) {
- // Logged, never silent: a truncated manifest must not be
- // indistinguishable from "nothing is shared with this user".
- $this->logger->warning(
- sprintf(
- 'LaunchPad: %d granted dashboards exceeds the %d cap — manifest truncated.',
- count($grantedUuids),
- self::MAX_GRANTED
- ),
- ['app' => Application::APP_ID, 'userId' => $userId]
- );
- $grantedUuids = array_slice($grantedUuids, 0, self::MAX_GRANTED);
- }
-
- // `ids` is a first-class config key that matches `_uuid` OR `_slug`.
- // A `filters['uuid']` entry would instead be read as a property
- // filter on a `uuid` property — the same trap that made the owner
- // query above return nothing.
- $results = $objectService->findAll(
- config: [
- 'filters' => [
- 'register' => self::REGISTER,
- 'schema' => self::SCHEMA,
- ],
- 'ids' => $grantedUuids,
- 'limit' => self::MAX_GRANTED,
- ]
- );
-
- if (is_array($results) === false) {
- return [];
- }
-
- $granted = [];
- foreach ($results as $item) {
- $data = $this->extractData(item: $item);
- if (empty($data) === false) {
- $granted[] = $data;
- }
- }
-
- return $granted;
- } catch (DoesNotExistException $e) {
- // Register/schema not provisioned — same benign case the owned
- // query already handles.
- return [];
- } catch (\RuntimeException | \InvalidArgumentException $e) {
- $this->logger->error(
- 'LaunchPad: failed to fetch granted dashboards from OpenRegister: '.$e->getMessage(),
- ['app' => Application::APP_ID, 'userId' => $userId]
- );
-
- return [];
- }//end try
-
- }//end fetchGrantedDashboards()
-
- /**
- * Normalise a raw ObjectService result item to a plain data array.
- *
- * OpenRegister items may be returned as objects with a `getObject()`
- * method or as plain associative arrays.
- *
- * @param mixed $item A single result from ObjectService::findAll().
- *
- * @return array The plain data array, or [] on failure.
- */
- private function extractData(mixed $item): array
- {
- if (is_array($item) === true) {
- return $item;
- }
-
- if (is_object($item) === true && method_exists($item, 'getObject') === true) {
- $data = $item->getObject();
- if (is_array($data) === true) {
- return $data;
- }
-
- return [];
- }
-
- if (is_object($item) === true && method_exists($item, 'jsonSerialize') === true) {
- $data = $item->jsonSerialize();
- if (is_array($data) === true) {
- return $data;
- }
-
- return [];
- }
-
- return [];
-
- }//end extractData()
-
- /**
- * Build the v2 manifest array from a list of dashboard data arrays.
- *
- * @param array> $dashboards Flat list of dashboard data.
- * @param string $userId The current user ID.
- *
- * @return array The v2 manifest document.
- */
- private function buildManifest(array $dashboards, string $userId): array
- {
- $pages = [];
- $menu = [];
- $order = 0;
-
- foreach ($dashboards as $data) {
- $slug = $data['slug'] ?? null;
- $title = $data['title'] ?? null;
-
- if (empty($slug) === true || empty($title) === true) {
- continue;
- }
-
- $pageId = 'dashboard-'.$slug;
-
- $pages[] = [
- 'id' => $pageId,
- 'route' => '/'.$slug,
- 'type' => 'dashboard',
- 'title' => $title,
- 'widgets' => $data['widgets'] ?? [],
- ];
-
- $menu[] = [
- 'id' => 'menu-'.$slug,
- 'label' => $title,
- 'route' => $pageId,
- 'order' => $order,
- // ADR-077 Tier A concept `dashboard`. These entries are
- // dashboards, so `icon-home` was both the wrong concept and a
- // legacy `icon-*` CSS class — which renders as an invisible
- // white glyph on NC34+ light themes. The name is registered in
- // src/icons.js; CnIcon has no fallback for one that is not.
- 'icon' => 'ViewDashboardOutline',
- ];
-
- $order++;
- }//end foreach
-
- return [
- '$schema' => self::SCHEMA_URL,
- 'version' => '1.0.0',
- 'dependencies' => ['openregister'],
- 'menu' => $menu,
- 'pages' => $pages,
- 'runtime' => [
- 'user' => [
- 'id' => $userId,
- ],
- ],
- ];
-
- }//end buildManifest()
+class ManifestController extends Controller {
+ /**
+ * OpenRegister register slug for launchpad dashboards.
+ *
+ * @var string
+ */
+ private const REGISTER = 'launchpad';
+
+ /**
+ * OpenRegister schema slug for dashboard objects.
+ *
+ * @var string
+ */
+ private const SCHEMA = 'dashboard';
+
+ /**
+ * V2 manifest schema URL.
+ *
+ * @var string
+ */
+ private const SCHEMA_URL = 'https://raw.githubusercontent.com/ConductionNL/nextcloud-vue/main/src/schemas/app-manifest-v2.schema.json';
+
+ /**
+ * Constructor.
+ *
+ * @param IRequest $request The HTTP request.
+ * @param ContainerInterface $container The Nextcloud DI container; used to
+ * lazy-load ObjectService so that launchpad
+ * degrades gracefully when OpenRegister
+ * is not yet active.
+ * @param ActionAuthService $actionAuth ADR-023 action authorization.
+ * @param IUserSession $userSession User session (IUser resolution).
+ * @param LoggerInterface $logger PSR logger.
+ * @param string|null $userId The authenticated user ID, injected
+ * by the DI container.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly ContainerInterface $container,
+ private readonly ActionAuthService $actionAuth,
+ private readonly IUserSession $userSession,
+ private readonly LoggerInterface $logger,
+ private readonly ?string $userId,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
+
+ /**
+ * Build and return the v2 app manifest for the authenticated user.
+ *
+ * Reads the user's dashboard objects from OpenRegister. Each object with
+ * a `slug` and `title` property becomes one page entry and one menu entry.
+ * Objects the user owns, plus objects explicitly granted to them via
+ * OpenRegister's per-object sharing primitive, are included.
+ *
+ * Route: GET /apps/launchpad/api/manifest
+ *
+ * @return JSONResponse A JSON document conforming to the v2 manifest
+ * schema. Returns HTTP 401 when no user is
+ * authenticated, HTTP 503 when OpenRegister is
+ * unavailable.
+ *
+ * @spec manifest-v2-runtime:REQ-MVR-001
+ * @spec openspec/specs/runtime-shell/spec.md
+ */
+ #[NoAdminRequired]
+ #[NoCSRFRequired]
+ public function index(): JSONResponse {
+ if ($this->userId === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ return new JSONResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+ }
+
+ try {
+ $this->actionAuth->requireAction($user, 'manifest.index');
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ // Retrieve ObjectService lazily — OpenRegister may not be enabled on
+ // every instance. Returning an empty manifest (not an error) lets the
+ // frontend render its "no dashboards yet" CTA without a red alert.
+ try {
+ /*
+ * @var \OCA\OpenRegister\Service\ObjectService $objectService
+ */
+
+ $objectService = $this->container->get('OCA\OpenRegister\Service\ObjectService');
+ } catch (\Throwable $e) {
+ $this->logger->warning(
+ 'LaunchPad: OpenRegister ObjectService unavailable — returning empty manifest. ' . $e->getMessage(),
+ ['app' => Application::APP_ID]
+ );
+
+ return new JSONResponse($this->buildManifest(dashboards: [], userId: $this->userId));
+ }//end try
+
+ // Fetch all dashboard objects owned by or shared with the current user.
+ $dashboards = $this->fetchUserDashboards(objectService: $objectService, userId: $this->userId);
+
+ return new JSONResponse($this->buildManifest(dashboards: $dashboards, userId: $this->userId));
+ }//end index()
+
+ /**
+ * Maximum number of granted dashboards folded into one manifest.
+ *
+ * A bound, not a policy: the grant lookup is cheap but the follow-up load is
+ * one IN(...) query whose parameter list should not grow without limit. If a
+ * user ever exceeds this, the manifest is truncated rather than slow — and
+ * the truncation is logged rather than silent, so it cannot be mistaken for
+ * "the user has no shared dashboards".
+ *
+ * @var int
+ */
+ private const MAX_GRANTED = 200;
+
+ /**
+ * Fetch dashboard objects from OpenRegister for the given user.
+ *
+ * C5 fix (REQ-MVR-001): replaces the non-existent `findObjects()` call
+ * (which caused a BadMethodCallException silently swallowed by Throwable)
+ * with the real `ObjectService::findAll()` API. The `owner` filter
+ * constrains results to the calling user's records — without it every
+ * user would receive the full dataset (latent IDOR on top of the API drift).
+ *
+ * Two sources, deduplicated: dashboards the user OWNS, and dashboards
+ * explicitly GRANTED to them through OpenRegister's per-object sharing
+ * primitive. The owner filter is deliberately kept on the first query rather
+ * than replaced by "let RBAC decide" — see fetchGrantedDashboards() for why
+ * the additive shape is the safe one.
+ *
+ * @param object $objectService The OpenRegister ObjectService instance.
+ * @param string $userId The authenticated Nextcloud user ID.
+ *
+ * @return array> Flat list of dashboard data arrays.
+ */
+ private function fetchUserDashboards(object $objectService, string $userId): array {
+ $dashboards = [];
+ $seen = [];
+
+ try {
+ // C5 fix: use the real ObjectService::findAll() API.
+ // `findObjects()` does not exist; the old call threw
+ // BadMethodCallException that was silently swallowed, causing the
+ // manifest to always return empty pages/menu arrays.
+ //
+ // The owner filter MUST be NESTED under `@self`. OpenRegister splits
+ // filters into metadata filters (the magic table's `_`-prefixed
+ // columns, addressed as a nested `@self` array) and property filters
+ // (matched against the schema's own properties). A bare `owner` is
+ // therefore read as a property filter on an `owner` property, which
+ // the dashboard schema does not have — so it matched nothing and
+ // this endpoint returned an EMPTY MANIFEST to every user, including
+ // the owner of the dashboards.
+ //
+ // Measured on a live instance with admin owning two dashboards: no
+ // owner filter returned 2; a bare `owner => admin` returned 0; a
+ // DOTTED `@self.owner => admin` also returned 0; the nested
+ // `@self => [owner => admin]` returned 2. The control was a nested
+ // filter with a nonexistent user, which returned 0 — without it,
+ // "nested returns 2" could not be distinguished from "the filter was
+ // ignored, here is everything", which is the failure mode that
+ // produced the always-empty manifest in the first place.
+ $ownedResults = $objectService->findAll(
+ config: [
+ 'filters' => [
+ 'register' => self::REGISTER,
+ 'schema' => self::SCHEMA,
+ '@self' => ['owner' => $userId],
+ ],
+ 'limit' => 500,
+ ]
+ );
+
+ if (is_array($ownedResults) === true) {
+ $this->foldInto(rows: $ownedResults, dashboards: $dashboards, seen: $seen, extract: true);
+ }
+ } catch (DoesNotExistException $e) {
+ // The 'mydash' register or 'dashboard' schema has not been
+ // provisioned in OpenRegister on this instance yet. That simply
+ // means the user has no dashboards — degrade to an empty manifest
+ // so the frontend renders its "no dashboards yet" CTA instead of a
+ // 500 (OpenRegister surfaces this as DoesNotExistException, which
+ // extends \Exception and so is not a RuntimeException).
+ $this->logger->info(
+ 'MyDash: OpenRegister register/schema not provisioned — returning empty manifest. ' . $e->getMessage(),
+ ['app' => Application::APP_ID, 'userId' => $userId]
+ );
+ } catch (\RuntimeException|\InvalidArgumentException $e) {
+ // Narrow catch: only handle recoverable OR API errors. Let
+ // unexpected errors propagate so they are visible in the logs.
+ $this->logger->error(
+ 'LaunchPad: failed to fetch dashboards from OpenRegister: ' . $e->getMessage(),
+ ['app' => Application::APP_ID, 'userId' => $userId]
+ );
+ }//end try
+
+ // Second source: dashboards explicitly granted to this user. Additive,
+ // and folded through the SAME $seen map so a dashboard the user both
+ // owns and was granted appears once.
+ $this->foldInto(
+ rows: $this->fetchGrantedDashboards(objectService: $objectService, userId: $userId),
+ dashboards: $dashboards,
+ seen: $seen,
+ extract: false
+ );
+
+ return $dashboards;
+ }//end fetchUserDashboards()
+
+ /**
+ * Fold one source's rows into the accumulator, skipping ones already seen.
+ *
+ * Shared by both sources on purpose: the owned query and the grant query must
+ * dedupe by the SAME identity rule, or a dashboard the user both owns and was
+ * granted would appear twice in the manifest.
+ *
+ * @param array $rows Rows from one source.
+ * @param array> $dashboards Accumulator, by reference.
+ * @param array $seen Identity map, by reference.
+ * @param bool $extract Whether the rows still
+ * need extractData() —
+ * the granted source has
+ * already normalised
+ * them.
+ *
+ * @return void
+ */
+ private function foldInto(array $rows, array &$dashboards, array &$seen, bool $extract): void {
+ foreach ($rows as $row) {
+ $data = $row;
+ if ($extract === true) {
+ $data = $this->extractData(item: $row);
+ }
+
+ if (is_array($data) === false || empty($data) === true) {
+ continue;
+ }
+
+ $id = ($data['id'] ?? $data['uuid'] ?? $data['slug'] ?? null);
+ if ($id !== null && isset($seen[$id]) === false) {
+ $seen[$id] = true;
+ $dashboards[] = $data;
+ }
+ }
+
+ }//end foldInto()
+
+ /**
+ * Dashboard objects explicitly granted to this user, via OpenRegister.
+ *
+ * WHY THIS IS ADDITIVE, rather than "drop the owner filter and let RBAC
+ * decide". Letting RBAC decide is the tidier design and it is what the
+ * OpenRegister `private` scope exists for — but it is only safe once the
+ * `dashboard` schema actually carries `scope: private`. A register-descriptor
+ * change lands through a repair step on upgrade, so there is necessarily a
+ * window (and, on any instance where that import did not apply, an
+ * indefinite one) in which the schema is still unscoped. An unfiltered
+ * findAll() against an unscoped schema returns EVERY user's dashboards. So
+ * the owner filter stays, and grants only ever ADD rows. The failure mode of
+ * this shape is a missing dashboard; the failure mode of the other is a
+ * cross-tenant leak in the manifest.
+ *
+ * `read` is the verb, because appearing in someone's manifest is exactly a
+ * read. The resolver answers only for the five core permission verbs and
+ * refuses anything else, so this cannot silently widen.
+ *
+ * Fails soft and empty: OpenRegister may be present without the sharing
+ * primitive (an older release), in which case the class is simply absent and
+ * the manifest degrades to owned-only — the behaviour before this change.
+ *
+ * @param object $objectService The OpenRegister ObjectService instance.
+ * @param string $userId The authenticated Nextcloud user ID.
+ *
+ * @return array> Granted dashboard data arrays.
+ */
+ private function fetchGrantedDashboards(object $objectService, string $userId): array {
+ try {
+ $grantResolver = $this->container->get('OCA\OpenRegister\Service\Rbac\ObjectGrantResolver');
+ } catch (\Throwable $e) {
+ // OpenRegister without the per-object sharing primitive. Not an
+ // error: degrade to owned-only, which is the pre-existing behaviour.
+ $this->logger->debug(
+ 'LaunchPad: OpenRegister object-grant resolver unavailable — manifest is owned-only. ' . $e->getMessage(),
+ ['app' => Application::APP_ID]
+ );
+
+ return [];
+ }
+
+ try {
+ // Keys, not values: the resolver returns uuid => permission
+ // bitmask, so array_values() would yield the bitmasks.
+ $grantedUuids = array_keys($grantResolver->grantedObjectUuidsFor($userId, 'read'));
+ if (empty($grantedUuids) === true) {
+ return [];
+ }
+
+ if (count($grantedUuids) > self::MAX_GRANTED) {
+ // Logged, never silent: a truncated manifest must not be
+ // indistinguishable from "nothing is shared with this user".
+ $this->logger->warning(
+ sprintf(
+ 'LaunchPad: %d granted dashboards exceeds the %d cap — manifest truncated.',
+ count($grantedUuids),
+ self::MAX_GRANTED
+ ),
+ ['app' => Application::APP_ID, 'userId' => $userId]
+ );
+ $grantedUuids = array_slice($grantedUuids, 0, self::MAX_GRANTED);
+ }
+
+ // `ids` is a first-class config key that matches `_uuid` OR `_slug`.
+ // A `filters['uuid']` entry would instead be read as a property
+ // filter on a `uuid` property — the same trap that made the owner
+ // query above return nothing.
+ $results = $objectService->findAll(
+ config: [
+ 'filters' => [
+ 'register' => self::REGISTER,
+ 'schema' => self::SCHEMA,
+ ],
+ 'ids' => $grantedUuids,
+ 'limit' => self::MAX_GRANTED,
+ ]
+ );
+
+ if (is_array($results) === false) {
+ return [];
+ }
+
+ $granted = [];
+ foreach ($results as $item) {
+ $data = $this->extractData(item: $item);
+ if (empty($data) === false) {
+ $granted[] = $data;
+ }
+ }
+
+ return $granted;
+ } catch (DoesNotExistException $e) {
+ // Register/schema not provisioned — same benign case the owned
+ // query already handles.
+ return [];
+ } catch (\RuntimeException|\InvalidArgumentException $e) {
+ $this->logger->error(
+ 'LaunchPad: failed to fetch granted dashboards from OpenRegister: ' . $e->getMessage(),
+ ['app' => Application::APP_ID, 'userId' => $userId]
+ );
+
+ return [];
+ }//end try
+
+ }//end fetchGrantedDashboards()
+
+ /**
+ * Normalise a raw ObjectService result item to a plain data array.
+ *
+ * OpenRegister items may be returned as objects with a `getObject()`
+ * method or as plain associative arrays.
+ *
+ * @param mixed $item A single result from ObjectService::findAll().
+ *
+ * @return array The plain data array, or [] on failure.
+ */
+ private function extractData(mixed $item): array {
+ if (is_array($item) === true) {
+ return $item;
+ }
+
+ if (is_object($item) === true && method_exists($item, 'getObject') === true) {
+ $data = $item->getObject();
+ if (is_array($data) === true) {
+ return $data;
+ }
+
+ return [];
+ }
+
+ if (is_object($item) === true && method_exists($item, 'jsonSerialize') === true) {
+ $data = $item->jsonSerialize();
+ if (is_array($data) === true) {
+ return $data;
+ }
+
+ return [];
+ }
+
+ return [];
+ }//end extractData()
+
+ /**
+ * Build the v2 manifest array from a list of dashboard data arrays.
+ *
+ * @param array> $dashboards Flat list of dashboard data.
+ * @param string $userId The current user ID.
+ *
+ * @return array The v2 manifest document.
+ */
+ private function buildManifest(array $dashboards, string $userId): array {
+ $pages = [];
+ $menu = [];
+ $order = 0;
+
+ foreach ($dashboards as $data) {
+ $slug = $data['slug'] ?? null;
+ $title = $data['title'] ?? null;
+
+ if (empty($slug) === true || empty($title) === true) {
+ continue;
+ }
+
+ $pageId = 'dashboard-' . $slug;
+
+ $pages[] = [
+ 'id' => $pageId,
+ 'route' => '/' . $slug,
+ 'type' => 'dashboard',
+ 'title' => $title,
+ 'widgets' => $data['widgets'] ?? [],
+ ];
+
+ $menu[] = [
+ 'id' => 'menu-' . $slug,
+ 'label' => $title,
+ 'route' => $pageId,
+ 'order' => $order,
+ // ADR-077 Tier A concept `dashboard`. These entries are
+ // dashboards, so `icon-home` was both the wrong concept and a
+ // legacy `icon-*` CSS class — which renders as an invisible
+ // white glyph on NC34+ light themes. The name is registered in
+ // src/icons.js; CnIcon has no fallback for one that is not.
+ 'icon' => 'ViewDashboardOutline',
+ ];
+
+ $order++;
+ }//end foreach
+
+ return [
+ '$schema' => self::SCHEMA_URL,
+ 'version' => '1.0.0',
+ 'dependencies' => ['openregister'],
+ 'menu' => $menu,
+ 'pages' => $pages,
+ 'runtime' => [
+ 'user' => [
+ 'id' => $userId,
+ ],
+ ],
+ ];
+
+ }//end buildManifest()
}//end class
diff --git a/lib/Controller/MetadataAdminController.php b/lib/Controller/MetadataAdminController.php
index bba8e061..ebc90e34 100644
--- a/lib/Controller/MetadataAdminController.php
+++ b/lib/Controller/MetadataAdminController.php
@@ -51,370 +51,364 @@
*
* @spec openspec/specs/dashboard-metadata-fields/spec.md
*/
-class MetadataAdminController extends Controller
-{
- /**
- * Constructor.
- *
- * @param IRequest $request The HTTP request.
- * @param MetadataService $metadataService The metadata service facade.
- * @param IGroupManager $groupManager Admin checker.
- * @param IUserSession $userSession Current user session.
- * @param ActionAuthService $actionAuth ADR-023 action authorization.
- */
- public function __construct(
- IRequest $request,
- private readonly MetadataService $metadataService,
- private readonly IGroupManager $groupManager,
- private readonly IUserSession $userSession,
- private readonly ActionAuthService $actionAuth,
- ) {
- parent::__construct(
- appName: Application::APP_ID,
- request: $request
- );
- }//end __construct()
-
- /**
- * Inline admin guard.
- *
- * @return JSONResponse|null Non-null = caller must be rejected.
- */
- private function assertAdmin(): ?JSONResponse
- {
- $user = $this->userSession->getUser();
- if ($user === null) {
- return new JSONResponse(
- data: ['error' => 'Not authenticated'],
- statusCode: Http::STATUS_UNAUTHORIZED
- );
- }
-
- if ($this->groupManager->isAdmin(userId: $user->getUID()) === false) {
- return new JSONResponse(
- data: ['error' => 'Admin required'],
- statusCode: Http::STATUS_FORBIDDEN
- );
- }
-
- return null;
- }//end assertAdmin()
-
- /**
- * `GET /api/admin/metadata-fields` — list all field definitions
- * (REQ-MDFL-001).
- *
- * @return JSONResponse The fields array + count, or 403.
- *
- * @spec openspec/specs/dashboard-metadata-fields/spec.md
- */
- #[AuthorizedAdminSetting(LaunchPadAdmin::class)]
- public function listFields(): JSONResponse
- {
- $guard = $this->assertAdmin();
- if ($guard !== null) {
- return $guard;
- }
-
- try {
- $this->actionAuth->requireAction(
- $this->userSession->getUser(),
- 'metadata-admin.list-fields'
- );
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- $fields = $this->metadataService->listFields();
-
- return ResponseHelper::success(
- data: [
- 'fields' => ResponseHelper::serializeList(entities: $fields),
- 'count' => count($fields),
- ]
- );
- }//end listFields()
-
- /**
- * `POST /api/admin/metadata-fields` — create a new field definition
- * (REQ-MDFL-001).
- *
- * @param string $key The slug.
- * @param string $label The display label.
- * @param string $type The field type.
- * @param array|null $options Option set (select types).
- * @param int $required 0 / 1.
- * @param int $sortOrder UI sort order.
- *
- * @return JSONResponse 201 + field, 400 on validation failure,
- * 403 for non-admins.
- *
- * @spec openspec/specs/dashboard-metadata-fields/spec.md
- */
- #[AuthorizedAdminSetting(LaunchPadAdmin::class)]
- public function createField(
- string $key='',
- string $label='',
- string $type='',
- ?array $options=null,
- int $required=0,
- int $sortOrder=0
- ): JSONResponse {
- $guard = $this->assertAdmin();
- if ($guard !== null) {
- return $guard;
- }
-
- try {
- $this->actionAuth->requireAction(
- $this->userSession->getUser(),
- 'metadata-admin.create-field'
- );
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- try {
- $field = $this->metadataService->createFieldDefinition(
- key: $key,
- label: $label,
- type: $type,
- options: $options,
- required: $required,
- sortOrder: $sortOrder
- );
- } catch (InvalidMetadataFieldException $exception) {
- return self::badRequest(message: $exception->getMessage());
- }
-
- return new JSONResponse(
- data: $field->jsonSerialize(),
- statusCode: Http::STATUS_CREATED
- );
- }//end createField()
-
- /**
- * `GET /api/admin/metadata-fields/{id}` — fetch a single field
- * definition (REQ-MDFL-001).
- *
- * @param int $id The field id.
- *
- * @return JSONResponse 200 + field, 404 when missing, 403 for non-admins.
- *
- * @spec openspec/specs/dashboard-metadata-fields/spec.md
- */
- #[AuthorizedAdminSetting(LaunchPadAdmin::class)]
- public function getField(int $id): JSONResponse
- {
- $guard = $this->assertAdmin();
- if ($guard !== null) {
- return $guard;
- }
-
- try {
- $this->actionAuth->requireAction(
- $this->userSession->getUser(),
- 'metadata-admin.get-field'
- );
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- try {
- $field = $this->metadataService->getField(id: $id);
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: ['error' => 'Field not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- }
-
- return ResponseHelper::success(data: $field->jsonSerialize());
- }//end getField()
-
- /**
- * `PUT /api/admin/metadata-fields/{id}` — update label / sortOrder
- * / required / options. Forbids `key` rename (REQ-MDFL-002).
- *
- * @param int $id The field id.
- * @param string|null $label The new label.
- * @param int|null $sortOrder The new sort order.
- * @param int|null $required The new required flag.
- * @param array|null $options The new option set.
- * @param string|null $key Forbidden — triggers 400.
- *
- * @return JSONResponse 200 + field, 400 on validation failure,
- * 404 when missing, 403 for non-admins.
- *
- * @spec openspec/specs/dashboard-metadata-fields/spec.md
- */
- #[AuthorizedAdminSetting(LaunchPadAdmin::class)]
- public function updateField(
- int $id,
- ?string $label=null,
- ?int $sortOrder=null,
- ?int $required=null,
- ?array $options=null,
- ?string $key=null
- ): JSONResponse {
- $guard = $this->assertAdmin();
- if ($guard !== null) {
- return $guard;
- }
-
- try {
- $this->actionAuth->requireAction(
- $this->userSession->getUser(),
- 'metadata-admin.update-field'
- );
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- $patch = self::buildPatch(
- key: $key,
- label: $label,
- sortOrder: $sortOrder,
- required: $required,
- options: $options
- );
-
- try {
- $field = $this->metadataService->updateFieldDefinition(
- id: $id,
- patch: $patch
- );
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: ['error' => 'Field not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- } catch (InvalidMetadataFieldException $exception) {
- return self::badRequest(message: $exception->getMessage());
- }
-
- return ResponseHelper::success(data: $field->jsonSerialize());
- }//end updateField()
-
- /**
- * `DELETE /api/admin/metadata-fields/{id}?cascade=true` —
- * REQ-MDFL-003.
- *
- * @param int $id The field id.
- * @param bool $cascade Whether to cascade-delete dependent values.
- *
- * @return JSONResponse 200 on success, 409 when soft-deletion blocked,
- * 404 when missing, 403 for non-admins.
- *
- * @spec openspec/specs/dashboard-metadata-fields/spec.md
- */
- #[AuthorizedAdminSetting(LaunchPadAdmin::class)]
- public function deleteField(int $id, bool $cascade=false): JSONResponse
- {
- $guard = $this->assertAdmin();
- if ($guard !== null) {
- return $guard;
- }
-
- try {
- $this->actionAuth->requireAction(
- $this->userSession->getUser(),
- 'metadata-admin.delete-field'
- );
- } catch (OCSForbiddenException) {
- return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
- }
-
- try {
- $this->metadataService->deleteFieldDefinition(
- id: $id,
- cascade: $cascade
- );
- } catch (DoesNotExistException) {
- return new JSONResponse(
- data: ['error' => 'Field not found'],
- statusCode: Http::STATUS_NOT_FOUND
- );
- } catch (MetadataFieldHasValuesException $exception) {
- return new JSONResponse(
- data: [
- 'error' => MetadataFieldHasValuesException::ERROR_CODE,
- 'message' => $exception->getMessage(),
- 'valueCount' => $exception->getValueCount(),
- ],
- statusCode: Http::STATUS_CONFLICT
- );
- }
-
- return ResponseHelper::success(data: ['status' => 'ok']);
- }//end deleteField()
-
- /**
- * Build the update patch from the individual nullable parameters.
- *
- * `null` means "not supplied" and the key is left out entirely, so
- * the service can distinguish an omitted field from an explicit
- * value. The router delivers `null` when the body omits the key;
- * any explicit array (including an empty one) counts as "set
- * options", so admins can clear an option set on non-select types.
- *
- * The forbidden `key` rename is deliberately forwarded rather than
- * dropped — the service rejects it with the documented 400.
- *
- * @param string|null $key The (forbidden) new slug.
- * @param string|null $label The new label.
- * @param int|null $sortOrder The new sort order.
- * @param int|null $required The new required flag.
- * @param array|null $options The new option set.
- *
- * @return array The patch payload.
- */
- private static function buildPatch(
- ?string $key,
- ?string $label,
- ?int $sortOrder,
- ?int $required,
- ?array $options
- ): array {
- $patch = [];
- if ($key !== null) {
- $patch['key'] = $key;
- }
-
- if ($label !== null) {
- $patch['label'] = $label;
- }
-
- if ($sortOrder !== null) {
- $patch['sortOrder'] = $sortOrder;
- }
-
- if ($required !== null) {
- $patch['required'] = $required;
- }
-
- if ($options !== null) {
- $patch['options'] = $options;
- }
-
- return $patch;
- }//end buildPatch()
-
- /**
- * Build a 400-with-error envelope.
- *
- * @param string $message The validation message.
- *
- * @return JSONResponse The 400 response.
- */
- private static function badRequest(string $message): JSONResponse
- {
- return new JSONResponse(
- data: [
- 'error' => InvalidMetadataFieldException::ERROR_CODE,
- 'message' => $message,
- ],
- statusCode: Http::STATUS_BAD_REQUEST
- );
- }//end badRequest()
+class MetadataAdminController extends Controller {
+ /**
+ * Constructor.
+ *
+ * @param IRequest $request The HTTP request.
+ * @param MetadataService $metadataService The metadata service facade.
+ * @param IGroupManager $groupManager Admin checker.
+ * @param IUserSession $userSession Current user session.
+ * @param ActionAuthService $actionAuth ADR-023 action authorization.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly MetadataService $metadataService,
+ private readonly IGroupManager $groupManager,
+ private readonly IUserSession $userSession,
+ private readonly ActionAuthService $actionAuth,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
+
+ /**
+ * Inline admin guard.
+ *
+ * @return JSONResponse|null Non-null = caller must be rejected.
+ */
+ private function assertAdmin(): ?JSONResponse {
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ return new JSONResponse(
+ data: ['error' => 'Not authenticated'],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
+
+ if ($this->groupManager->isAdmin(userId: $user->getUID()) === false) {
+ return new JSONResponse(
+ data: ['error' => 'Admin required'],
+ statusCode: Http::STATUS_FORBIDDEN
+ );
+ }
+
+ return null;
+ }//end assertAdmin()
+
+ /**
+ * `GET /api/admin/metadata-fields` — list all field definitions
+ * (REQ-MDFL-001).
+ *
+ * @return JSONResponse The fields array + count, or 403.
+ *
+ * @spec openspec/specs/dashboard-metadata-fields/spec.md
+ */
+ #[AuthorizedAdminSetting(LaunchPadAdmin::class)]
+ public function listFields(): JSONResponse {
+ $guard = $this->assertAdmin();
+ if ($guard !== null) {
+ return $guard;
+ }
+
+ try {
+ $this->actionAuth->requireAction(
+ $this->userSession->getUser(),
+ 'metadata-admin.list-fields'
+ );
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ $fields = $this->metadataService->listFields();
+
+ return ResponseHelper::success(
+ data: [
+ 'fields' => ResponseHelper::serializeList(entities: $fields),
+ 'count' => count($fields),
+ ]
+ );
+ }//end listFields()
+
+ /**
+ * `POST /api/admin/metadata-fields` — create a new field definition
+ * (REQ-MDFL-001).
+ *
+ * @param string $key The slug.
+ * @param string $label The display label.
+ * @param string $type The field type.
+ * @param array|null $options Option set (select types).
+ * @param int $required 0 / 1.
+ * @param int $sortOrder UI sort order.
+ *
+ * @return JSONResponse 201 + field, 400 on validation failure,
+ * 403 for non-admins.
+ *
+ * @spec openspec/specs/dashboard-metadata-fields/spec.md
+ */
+ #[AuthorizedAdminSetting(LaunchPadAdmin::class)]
+ public function createField(
+ string $key = '',
+ string $label = '',
+ string $type = '',
+ ?array $options = null,
+ int $required = 0,
+ int $sortOrder = 0,
+ ): JSONResponse {
+ $guard = $this->assertAdmin();
+ if ($guard !== null) {
+ return $guard;
+ }
+
+ try {
+ $this->actionAuth->requireAction(
+ $this->userSession->getUser(),
+ 'metadata-admin.create-field'
+ );
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ try {
+ $field = $this->metadataService->createFieldDefinition(
+ key: $key,
+ label: $label,
+ type: $type,
+ options: $options,
+ required: $required,
+ sortOrder: $sortOrder
+ );
+ } catch (InvalidMetadataFieldException $exception) {
+ return self::badRequest(message: $exception->getMessage());
+ }
+
+ return new JSONResponse(
+ data: $field->jsonSerialize(),
+ statusCode: Http::STATUS_CREATED
+ );
+ }//end createField()
+
+ /**
+ * `GET /api/admin/metadata-fields/{id}` — fetch a single field
+ * definition (REQ-MDFL-001).
+ *
+ * @param int $id The field id.
+ *
+ * @return JSONResponse 200 + field, 404 when missing, 403 for non-admins.
+ *
+ * @spec openspec/specs/dashboard-metadata-fields/spec.md
+ */
+ #[AuthorizedAdminSetting(LaunchPadAdmin::class)]
+ public function getField(int $id): JSONResponse {
+ $guard = $this->assertAdmin();
+ if ($guard !== null) {
+ return $guard;
+ }
+
+ try {
+ $this->actionAuth->requireAction(
+ $this->userSession->getUser(),
+ 'metadata-admin.get-field'
+ );
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ try {
+ $field = $this->metadataService->getField(id: $id);
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: ['error' => 'Field not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }
+
+ return ResponseHelper::success(data: $field->jsonSerialize());
+ }//end getField()
+
+ /**
+ * `PUT /api/admin/metadata-fields/{id}` — update label / sortOrder
+ * / required / options. Forbids `key` rename (REQ-MDFL-002).
+ *
+ * @param int $id The field id.
+ * @param string|null $label The new label.
+ * @param int|null $sortOrder The new sort order.
+ * @param int|null $required The new required flag.
+ * @param array|null $options The new option set.
+ * @param string|null $key Forbidden — triggers 400.
+ *
+ * @return JSONResponse 200 + field, 400 on validation failure,
+ * 404 when missing, 403 for non-admins.
+ *
+ * @spec openspec/specs/dashboard-metadata-fields/spec.md
+ */
+ #[AuthorizedAdminSetting(LaunchPadAdmin::class)]
+ public function updateField(
+ int $id,
+ ?string $label = null,
+ ?int $sortOrder = null,
+ ?int $required = null,
+ ?array $options = null,
+ ?string $key = null,
+ ): JSONResponse {
+ $guard = $this->assertAdmin();
+ if ($guard !== null) {
+ return $guard;
+ }
+
+ try {
+ $this->actionAuth->requireAction(
+ $this->userSession->getUser(),
+ 'metadata-admin.update-field'
+ );
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ $patch = self::buildPatch(
+ key: $key,
+ label: $label,
+ sortOrder: $sortOrder,
+ required: $required,
+ options: $options
+ );
+
+ try {
+ $field = $this->metadataService->updateFieldDefinition(
+ id: $id,
+ patch: $patch
+ );
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: ['error' => 'Field not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ } catch (InvalidMetadataFieldException $exception) {
+ return self::badRequest(message: $exception->getMessage());
+ }
+
+ return ResponseHelper::success(data: $field->jsonSerialize());
+ }//end updateField()
+
+ /**
+ * `DELETE /api/admin/metadata-fields/{id}?cascade=true` —
+ * REQ-MDFL-003.
+ *
+ * @param int $id The field id.
+ * @param bool $cascade Whether to cascade-delete dependent values.
+ *
+ * @return JSONResponse 200 on success, 409 when soft-deletion blocked,
+ * 404 when missing, 403 for non-admins.
+ *
+ * @spec openspec/specs/dashboard-metadata-fields/spec.md
+ */
+ #[AuthorizedAdminSetting(LaunchPadAdmin::class)]
+ public function deleteField(int $id, bool $cascade = false): JSONResponse {
+ $guard = $this->assertAdmin();
+ if ($guard !== null) {
+ return $guard;
+ }
+
+ try {
+ $this->actionAuth->requireAction(
+ $this->userSession->getUser(),
+ 'metadata-admin.delete-field'
+ );
+ } catch (OCSForbiddenException) {
+ return new JSONResponse(['error' => 'Forbidden'], Http::STATUS_FORBIDDEN);
+ }
+
+ try {
+ $this->metadataService->deleteFieldDefinition(
+ id: $id,
+ cascade: $cascade
+ );
+ } catch (DoesNotExistException) {
+ return new JSONResponse(
+ data: ['error' => 'Field not found'],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ } catch (MetadataFieldHasValuesException $exception) {
+ return new JSONResponse(
+ data: [
+ 'error' => MetadataFieldHasValuesException::ERROR_CODE,
+ 'message' => $exception->getMessage(),
+ 'valueCount' => $exception->getValueCount(),
+ ],
+ statusCode: Http::STATUS_CONFLICT
+ );
+ }
+
+ return ResponseHelper::success(data: ['status' => 'ok']);
+ }//end deleteField()
+
+ /**
+ * Build the update patch from the individual nullable parameters.
+ *
+ * `null` means "not supplied" and the key is left out entirely, so
+ * the service can distinguish an omitted field from an explicit
+ * value. The router delivers `null` when the body omits the key;
+ * any explicit array (including an empty one) counts as "set
+ * options", so admins can clear an option set on non-select types.
+ *
+ * The forbidden `key` rename is deliberately forwarded rather than
+ * dropped — the service rejects it with the documented 400.
+ *
+ * @param string|null $key The (forbidden) new slug.
+ * @param string|null $label The new label.
+ * @param int|null $sortOrder The new sort order.
+ * @param int|null $required The new required flag.
+ * @param array|null $options The new option set.
+ *
+ * @return array The patch payload.
+ */
+ private static function buildPatch(
+ ?string $key,
+ ?string $label,
+ ?int $sortOrder,
+ ?int $required,
+ ?array $options,
+ ): array {
+ $patch = [];
+ if ($key !== null) {
+ $patch['key'] = $key;
+ }
+
+ if ($label !== null) {
+ $patch['label'] = $label;
+ }
+
+ if ($sortOrder !== null) {
+ $patch['sortOrder'] = $sortOrder;
+ }
+
+ if ($required !== null) {
+ $patch['required'] = $required;
+ }
+
+ if ($options !== null) {
+ $patch['options'] = $options;
+ }
+
+ return $patch;
+ }//end buildPatch()
+
+ /**
+ * Build a 400-with-error envelope.
+ *
+ * @param string $message The validation message.
+ *
+ * @return JSONResponse The 400 response.
+ */
+ private static function badRequest(string $message): JSONResponse {
+ return new JSONResponse(
+ data: [
+ 'error' => InvalidMetadataFieldException::ERROR_CODE,
+ 'message' => $message,
+ ],
+ statusCode: Http::STATUS_BAD_REQUEST
+ );
+ }//end badRequest()
}//end class
diff --git a/lib/Controller/MetricsController.php b/lib/Controller/MetricsController.php
index 61c2c1c0..b0ad0174 100644
--- a/lib/Controller/MetricsController.php
+++ b/lib/Controller/MetricsController.php
@@ -66,71 +66,69 @@
*
* @spec openspec/changes/adopt-apphost/specs/prometheus-metrics/spec.md — Requirement: Metrics Endpoint (REQ-PROM-001)
*/
-class MetricsController extends Controller
-{
- /**
- * Prometheus text exposition content type.
- *
- * Inlined rather than read from `PrometheusRenderer::CONTENT_TYPE`, because
- * referencing that constant is itself a compile-time dependency on a class
- * that may not be installed — the same trap as the old `extends`.
- *
- * @var string
- */
- public const CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
+class MetricsController extends Controller {
+ /**
+ * Prometheus text exposition content type.
+ *
+ * Inlined rather than read from `PrometheusRenderer::CONTENT_TYPE`, because
+ * referencing that constant is itself a compile-time dependency on a class
+ * that may not be installed — the same trap as the old `extends`.
+ *
+ * @var string
+ */
+ public const CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
- /**
- * Constructor.
- *
- * @param string $appName This leaf's app id (`launchpad`), which the
- * engine uses to locate the manifest and to
- * prefix the emitted metrics.
- * @param IRequest $request The HTTP request.
- * @param object|null $manifestLoader OpenRegister's ManifestLoader, or null when
- * OpenRegister is unavailable. Untyped on
- * purpose — see the class docblock.
- * @param object|null $engine OpenRegister's MetricsEngine, or null.
- */
- public function __construct(
- string $appName,
- IRequest $request,
- private readonly ?object $manifestLoader=null,
- private readonly ?object $engine=null,
- ) {
- parent::__construct(appName: $appName, request: $request);
- }//end __construct()
+ /**
+ * Constructor.
+ *
+ * @param string $appName This leaf's app id (`launchpad`), which the
+ * engine uses to locate the manifest and to
+ * prefix the emitted metrics.
+ * @param IRequest $request The HTTP request.
+ * @param object|null $manifestLoader OpenRegister's ManifestLoader, or null when
+ * OpenRegister is unavailable. Untyped on
+ * purpose — see the class docblock.
+ * @param object|null $engine OpenRegister's MetricsEngine, or null.
+ */
+ public function __construct(
+ string $appName,
+ IRequest $request,
+ private readonly ?object $manifestLoader = null,
+ private readonly ?object $engine = null,
+ ) {
+ parent::__construct(appName: $appName, request: $request);
+ }//end __construct()
- /**
- * GET /api/metrics — declarative Prometheus metrics (admin-only, ADR-006).
- *
- * @return TextPlainResponse Prometheus text exposition 0.0.4, or a plain 503
- * body when the engine is unavailable.
- *
- * @spec openspec/changes/adopt-apphost/specs/prometheus-metrics/spec.md — Requirement: Metrics Endpoint (REQ-PROM-001)
- */
- #[NoCSRFRequired]
- public function index(): TextPlainResponse
- {
- if ($this->manifestLoader === null || $this->engine === null) {
- return new TextPlainResponse(
- '# OpenRegister AppHost observability engine unavailable'."\n",
- Http::STATUS_SERVICE_UNAVAILABLE
- );
- }
+ /**
+ * GET /api/metrics — declarative Prometheus metrics (admin-only, ADR-006).
+ *
+ * @return TextPlainResponse Prometheus text exposition 0.0.4, or a plain 503
+ * body when the engine is unavailable.
+ *
+ * @spec openspec/changes/adopt-apphost/specs/prometheus-metrics/spec.md — Requirement: Metrics Endpoint (REQ-PROM-001)
+ */
+ #[NoCSRFRequired]
+ public function index(): TextPlainResponse {
+ if ($this->manifestLoader === null || $this->engine === null) {
+ return new TextPlainResponse(
+ '# OpenRegister AppHost observability engine unavailable' . "\n",
+ Http::STATUS_SERVICE_UNAVAILABLE
+ );
+ }
- try {
- $manifest = $this->manifestLoader->load(appId: $this->appName);
- $body = $this->engine->render(manifest: $manifest);
- } catch (Throwable $e) {
- return new TextPlainResponse(
- '# metrics unavailable: '.$e->getMessage()."\n",
- Http::STATUS_SERVICE_UNAVAILABLE
- );
- }
+ try {
+ $manifest = $this->manifestLoader->load(appId: $this->appName);
+ $body = $this->engine->render(manifest: $manifest);
+ } catch (Throwable $e) {
+ return new TextPlainResponse(
+ '# metrics unavailable: ' . $e->getMessage() . "\n",
+ Http::STATUS_SERVICE_UNAVAILABLE
+ );
+ }
- $response = new TextPlainResponse($body);
- $response->addHeader('Content-Type', self::CONTENT_TYPE);
+ $response = new TextPlainResponse($body);
+ $response->addHeader('Content-Type', self::CONTENT_TYPE);
- return $response;
- }//end index()
+ return $response;
+ }//end index()
}//end class
diff --git a/lib/Controller/PageController.php b/lib/Controller/PageController.php
index bc78857d..151a69cc 100644
--- a/lib/Controller/PageController.php
+++ b/lib/Controller/PageController.php
@@ -57,527 +57,515 @@
* group services to fill
* the contract.
*/
-class PageController extends Controller
-{
- /**
- * Constructor.
- *
- * @param IRequest $request The request.
- * @param IManager $dashboardManager Nextcloud dashboard widget manager.
- * @param IInitialState $initialState The Nextcloud initial-state service.
- * @param IUserSession $userSession Active user session.
- * @param WidgetService $widgetService Available-widgets descriptor formatter.
- * @param DashboardService $dashboardService Dashboard listing + resolver
- * (also exposes the
- * `allow_user_dashboards` flag
- * — REQ-ASET-003).
- * @param AdminTemplateService $adminTemplateService Primary-group routing
- * resolver (REQ-TMPL-012,
- * REQ-TMPL-013).
- * @param RoleFeaturePermissionService $roleFeaturePerm Per-user widget
- * allow-list source
- * (REQ-RFP-009..010).
- * @param DashboardTreeService $treeService Slug-chain
- * resolver used by the
- * deep-link route.
- * @param LoggerInterface $logger Used to record
- * silent fallback
- * when a deep-link
- * path doesn't
- * resolve to a
- * visible dashboard.
- * @param AdminSettingsService $adminSettingsService Source of the
- * quick-search
- * no-match
- * fallback-target
- * admin setting
- * (tile-quick-search
- * REQ-QSEARCH-004).
- */
- public function __construct(
- IRequest $request,
- private readonly IManager $dashboardManager,
- private readonly IInitialState $initialState,
- private readonly IUserSession $userSession,
- private readonly WidgetService $widgetService,
- private readonly DashboardService $dashboardService,
- private readonly AdminTemplateService $adminTemplateService,
- private readonly RoleFeaturePermissionService $roleFeaturePerm,
- private readonly DashboardTreeService $treeService,
- private readonly LoggerInterface $logger,
- private readonly AdminSettingsService $adminSettingsService,
- ) {
- parent::__construct(appName: Application::APP_ID, request: $request);
- }//end __construct()
-
- /**
- * Deep-link entry point — `/apps/launchpad/{deepLink}`.
- *
- * Symfony binds the captured slug-chain into `$deepLink`. Delegating
- * to {@see self::index()} keeps the workspace render path single-
- * sourced; the optional path argument merely overrides the active
- * dashboard before initial-state assembly.
- *
- * @param string $deepLink Slug-chain captured from the URL (may
- * contain `/` separators).
- *
- * @return TemplateResponse The workspace template response.
- *
- * @spec openspec/specs/runtime-shell/spec.md
- */
- #[NoAdminRequired]
- #[NoCSRFRequired]
- public function deepLink(string $deepLink=''): TemplateResponse
- {
- return $this->index(deepLink: $deepLink);
- }//end deepLink()
-
- /**
- * Render the workspace page.
- *
- * Wires the full workspace initial-state contract into the template via
- * {@see InitialStateBuilder}. Every key declared in REQ-INIT-002 is set
- * before `apply()` runs; missing keys raise
- * {@see \OCA\LaunchPad\Exception\MissingInitialStateException} so the page
- * never renders with a partial payload.
- *
- * Deep-link path: when `$deepLink` resolves through the tree service
- * to a dashboard the user can read, that dashboard is used as the
- * active one (overriding the resolver's seven-step fallback). When
- * the path doesn't resolve (renamed, deleted, never existed, or not
- * visible to the caller), the controller logs a warning and falls
- * back silently — bookmarks of stale slug chains still land on
- * something instead of 404'ing.
- *
- * @param string $deepLink Optional slug-chain selecting the active
- * dashboard. Empty string ⇒ default resolver.
- *
- * @return TemplateResponse The template response.
- *
- * @spec openspec/specs/runtime-shell/spec.md
- */
- #[NoAdminRequired]
- #[NoCSRFRequired]
- public function index(string $deepLink=''): TemplateResponse
- {
- Util::addScript(application: Application::APP_ID, file: 'launchpad-main');
- Util::addStyle(application: Application::APP_ID, file: 'launchpad');
-
- // Load all widget scripts so legacy widgets can register their callbacks.
- $this->loadWidgetScripts();
-
- $userId = $this->resolveUserId();
-
- $routingGroup = $this->resolveRoutingGroup(userId: $userId);
- $primaryGroupId = $routingGroup['id'];
- $primaryGroupName = $routingGroup['name'];
-
- $isAdmin = false;
- $visible = [];
- $active = null;
- if ($userId !== '') {
- $isAdmin = $this->dashboardService->isAdmin(userId: $userId);
- $visible = $this->dashboardService->getVisibleToUser(userId: $userId);
- $active = $this->resolveActive(
- userId: $userId,
- deepLink: $deepLink,
- primaryGroupId: $primaryGroupId
- );
- }
-
- $descriptors = $this->splitDescriptors(visible: $visible);
- $activeState = $this->describeActive(active: $active);
-
- $allowUserDashboards = $this->dashboardService->getAllowUserDashboards();
-
- $builder = new InitialStateBuilder(
- initialState: $this->initialState,
- page: Page::WORKSPACE
- );
-
- $builder
- ->setWidgets($this->widgetService->getAvailableWidgets())
- ->setLayout($activeState['layout'])
- ->setPrimaryGroup($primaryGroupId)
- ->setPrimaryGroupName($primaryGroupName)
- ->setIsAdmin($isAdmin)
- ->setActiveDashboardId($activeState['activeDashboardId'])
- ->setDashboardSource($activeState['dashboardSource'])
- ->setGroupDashboards($descriptors['group'])
- ->setUserDashboards($descriptors['user'])
- ->setAllowUserDashboards($allowUserDashboards);
-
- // PR #95 (role-based-content): per-user widget allow-list.
- // `null` = no admin policy for this user (unlimited).
- $allowedWidgets = null;
- if ($userId !== '') {
- $allowedWidgets = $this->roleFeaturePerm->getAllowedWidgetIds(
- userId: $userId
- );
- }
-
- // Tile-quick-search REQ-QSEARCH-004: read the admin-configured
- // no-match fallback target. `getSettings()` already resolves the
- // safe 'none' default when unset/invalid, so this never throws.
- $quicksearchFallback = (string) (
- $this->adminSettingsService->getSettings()['quicksearchFallbackTarget'] ?? AdminSettingsService::DEFAULT_QUICKSEARCH_FALLBACK_TARGET
- );
-
- $builder
- ->setAllowedWidgets($allowedWidgets)
- ->setDeepLinkPath($activeState['deepLinkPath'])
- ->setQuicksearchFallbackTarget($quicksearchFallback)
- ->apply();
-
- // REQ-SHELL-001: pass the chrome slot ids so Nextcloud treats
- // `#app-workspace` as the main content slot and allocates no left
- // navigation panel (the runtime shell renders its own slide-in
- // sidebar via `dashboard-switcher-sidebar`). Renderer parameter
- // names match the Nextcloud chrome conventions.
- $response = new TemplateResponse(
- appName: Application::APP_ID,
- templateName: 'index',
- params: [
- 'id-app-content' => '#app-workspace',
- 'id-app-navigation' => null,
- ]
- );
-
- $response->setContentSecurityPolicy(csp: $this->buildWorkspaceCsp());
-
- return $response;
- }//end index()
-
- /**
- * Resolve the primary group this request routes through.
- *
- * Routing resolver — REQ-TMPL-012 / REQ-TMPL-013. The
- * `AdminTemplateService` walks the admin-configured `group_order`
- * priority list and returns the first group the user belongs to, OR
- * the literal `'default'` sentinel when nothing matches. The display
- * name comes from the same service so the lookup lives in exactly one
- * place.
- *
- * @param string $userId The caller's uid, or '' when anonymous.
- *
- * @return array{id: string, name: string} The group id and its
- * display name.
- */
- private function resolveRoutingGroup(string $userId): array
- {
- $primaryGroupId = Dashboard::DEFAULT_GROUP_ID;
- $primaryGroupName = $this->adminTemplateService->resolvePrimaryGroupDisplayName(
- groupId: Dashboard::DEFAULT_GROUP_ID
- );
- if ($userId !== '') {
- $primaryGroupId = $this->adminTemplateService->resolvePrimaryGroup(
- userId: $userId
- );
- $primaryGroupName = $this->adminTemplateService->resolvePrimaryGroupDisplayName(
- groupId: $primaryGroupId
- );
- }
-
- return [
- 'id' => $primaryGroupId,
- 'name' => $primaryGroupName,
- ];
- }//end resolveRoutingGroup()
-
- /**
- * Resolve the active session's user id.
- *
- * @return string The uid, or an empty string for an anonymous caller.
- */
- private function resolveUserId(): string
- {
- $user = $this->userSession->getUser();
- if ($user === null) {
- return '';
- }
-
- return $user->getUID();
- }//end resolveUserId()
-
- /**
- * Split the visible dashboards into the group and user descriptor
- * lists the initial-state contract expects (REQ-INIT-002).
- *
- * User-sourced entries drop the `source` key — the frontend infers it
- * from the list the descriptor arrived in.
- *
- * @param array $visible The visible entries.
- *
- * @return array{group: list>, user: list>}
- */
- private function splitDescriptors(array $visible): array
- {
- $groupDashboards = [];
- $userDashboards = [];
- foreach ($visible as $entry) {
- $dashboard = $entry['dashboard'];
- // Dashboard entity has no icon column today — surface an empty
- // string so the frontend descriptor shape matches REQ-INIT-002.
- $descriptor = [
- 'id' => (string) $dashboard->getUuid(),
- 'name' => (string) $dashboard->getName(),
- 'icon' => '',
- 'source' => $entry['source'],
- ];
-
- if ($entry['source'] === Dashboard::SOURCE_USER) {
- unset($descriptor['source']);
- $userDashboards[] = $descriptor;
- continue;
- }
-
- $groupDashboards[] = $descriptor;
- }
-
- return [
- 'group' => $groupDashboards,
- 'user' => $userDashboards,
- ];
- }//end splitDescriptors()
-
- /**
- * Resolve the dashboard that should open for this request.
- *
- * Deep-link override: when the URL carries a slug-chain we try to land
- * the user on that dashboard before consulting the seven-step
- * resolver. Failures (path doesn't resolve, not visible, throws) are
- * swallowed so a stale bookmark still opens *something* instead of
- * breaking.
- *
- * @param string $userId The caller's uid (never empty here).
- * @param string $deepLink The slug-chain from the URL, or ''.
- * @param string $primaryGroupId The resolved primary group id.
- *
- * @return array{dashboard: Dashboard, source: string}|null The active
- * entry, or
- * null.
- */
- private function resolveActive(
- string $userId,
- string $deepLink,
- string $primaryGroupId
- ): ?array {
- $active = null;
- if ($deepLink !== '') {
- $active = $this->resolveDeepLink(userId: $userId, deepLink: $deepLink);
- }
-
- if ($active !== null) {
- return $active;
- }
-
- return $this->dashboardService->resolveActiveDashboard(
- userId: $userId,
- primaryGroupId: $primaryGroupId
- );
- }//end resolveActive()
-
- /**
- * Resolve a slug-chain to a dashboard the caller may read.
- *
- * Every failure mode — unresolvable path, dashboard not visible, or a
- * throwing resolver — returns null after logging, so the caller can
- * fall back to the default resolver.
- *
- * @param string $userId The caller's uid.
- * @param string $deepLink The slug-chain from the URL.
- *
- * @return array{dashboard: Dashboard, source: string}|null The matched
- * entry, or
- * null.
- */
- private function resolveDeepLink(string $userId, string $deepLink): ?array
- {
- $active = null;
- try {
- $resolved = $this->treeService->resolvePath(path: $deepLink);
- if ($resolved !== null) {
- $active = $this->dashboardService->getDashboardForUser(
- dashboardId: $resolved->getId(),
- userId: $userId
- );
- }
- } catch (Throwable $t) {
- $this->logger->warning(
- message: 'launchpad: deep-link resolution failed for path "{path}": {message}',
- context: [
- 'path' => $deepLink,
- 'message' => $t->getMessage(),
- ]
- );
- }
-
- if ($active === null) {
- $this->logger->info(
- message: 'launchpad: deep-link path "{path}" not visible — falling back to default resolver',
- context: ['path' => $deepLink]
- );
- }
-
- return $active;
- }//end resolveDeepLink()
-
- /**
- * Derive the initial-state keys that describe the active dashboard.
- *
- * Returns the documented empty defaults when nothing is active, so
- * the contract is fully populated either way.
- *
- * @param array{dashboard: Dashboard, source: string}|null $active The active entry.
- *
- * @return array{activeDashboardId: string, dashboardSource: string, layout: array, deepLinkPath: string}
- */
- private function describeActive(?array $active): array
- {
- if ($active === null) {
- return [
- 'activeDashboardId' => '',
- 'dashboardSource' => Dashboard::SOURCE_GROUP,
- 'layout' => [],
- 'deepLinkPath' => '',
- ];
- }
-
- $activeDashboard = $active['dashboard'];
- $placements = $this->widgetService->getDashboardPlacements(
- dashboardId: $activeDashboard->getId()
- );
-
- return [
- 'activeDashboardId' => (string) $activeDashboard->getUuid(),
- 'dashboardSource' => (string) $active['source'],
- 'layout' => array_map(
- callback: function ($placement) {
- return $placement->jsonSerialize();
- },
- array: $placements
- ),
- 'deepLinkPath' => $this->computeDeepLinkPath(dashboard: $activeDashboard),
- ];
- }//end describeActive()
-
- /**
- * Compute the canonical slug-chain for the active dashboard.
- *
- * The frontend reads this to keep the URL in sync (e.g. after a
- * parent rename, a stale bookmarked path is normalised in-place via
- * `history.replaceState`). A failure is logged and degrades to an
- * empty path rather than breaking the render.
- *
- * @param Dashboard $dashboard The active dashboard.
- *
- * @return string The slug-chain, or '' when it could not be computed.
- */
- private function computeDeepLinkPath(Dashboard $dashboard): string
- {
- try {
- return $this->treeService->computePath(
- uuid: (string) $dashboard->getUuid()
- );
- } catch (Throwable $t) {
- $this->logger->warning(
- message: 'launchpad: failed to compute path for active dashboard {uuid}: {message}',
- context: [
- 'uuid' => (string) $dashboard->getUuid(),
- 'message' => $t->getMessage(),
- ]
- );
- }
-
- return '';
- }//end computeDeepLinkPath()
-
- /**
- * Build the workspace content-security policy.
- *
- * REQ-VID: the video widget embeds YouTube/Vimeo players in an
- * `';
-
- $clean = $this->service->sanitiseSummaryHtml(html: $html);
-
- $this->assertStringNotContainsString('assertStringNotContainsString('service->sanitiseSummaryHtml(html: $html);
-
- $this->assertStringContainsString('rel="noopener noreferrer"', $clean);
- }//end testSanitiseSummaryForcesRelOnLinks()
-
- public function testSanitiseSummaryNeutralisesJavascriptHref(): void
- {
- $html = 'danger';
-
- $clean = $this->service->sanitiseSummaryHtml(html: $html);
-
- $this->assertStringNotContainsString('javascript:', $clean);
- $this->assertStringContainsString('href="#"', $clean);
- }//end testSanitiseSummaryNeutralisesJavascriptHref()
-
- public function testCheckAllowListAcceptsAllWhenEmpty(): void
- {
- $this->appConfig
- ->method('getValueString')
- ->willReturn('');
-
- $this->assertTrue($this->service->checkAllowList(url: 'https://anything.example.com/feed'));
- }//end testCheckAllowListAcceptsAllWhenEmpty()
-
- public function testCheckAllowListMatchesCaseInsensitively(): void
- {
- $this->appConfig
- ->method('getValueString')
- ->willReturn(json_encode(value: ['Example.Org']));
-
- $this->assertTrue($this->service->checkAllowList(url: 'https://example.org/feed'));
- }//end testCheckAllowListMatchesCaseInsensitively()
-
- public function testCheckAllowListRejectsHostnamesNotInList(): void
- {
- $this->appConfig
- ->method('getValueString')
- ->willReturn(json_encode(value: ['allowed.example.com']));
-
- $this->assertFalse($this->service->checkAllowList(url: 'https://blocked.example.org/feed'));
- }//end testCheckAllowListRejectsHostnamesNotInList()
-
- public function testCheckAllowListSubdomainNotImplied(): void
- {
- $this->appConfig
- ->method('getValueString')
- ->willReturn(json_encode(value: ['example.org']));
-
- // Per spec REQ-NEWS-006: exact hostname required, no wildcard
- // subdomain expansion.
- $this->assertFalse($this->service->checkAllowList(url: 'https://news.example.org/feed'));
- }//end testCheckAllowListSubdomainNotImplied()
-
- public function testCheckMetadataFilterRejectsWhenSpecNotImplemented(): void
- {
- // dashboard-metadata-fields capability not on this branch — the
- // filter must conservatively return false (treat missing field
- // as null which never matches a configured equality).
- $this->assertFalse(
- $this->service->checkMetadataFilter(
- dashboardId: 1,
- metadataFilter: ['fieldKey' => 'department', 'value' => 'marketing']
- )
- );
- }//end testCheckMetadataFilterRejectsWhenSpecNotImplemented()
-
- public function testFetchAndMergeFeedsWithEmptyListReturnsEmptyResponse(): void
- {
- $response = $this->service->fetchAndMergeFeeds(feedUrls: [], limit: 10);
-
- $this->assertSame([], $response['items']);
- $this->assertSame(0, $response['feedsFailed']);
- $this->assertSame([], $response['failedUrls']);
- }//end testFetchAndMergeFeedsWithEmptyListReturnsEmptyResponse()
-
- /**
- * C1 SSRF: http:// URLs MUST be rejected before any allow-list check.
- * The UrlSafetyValidator rejects non-HTTPS, so fetchAndMergeFeeds must
- * count the URL as failed without attempting a network request.
- */
- public function testFetchAndMergeFeedsRejectsHttpUrls(): void
- {
- // No HTTP client interaction expected — SSRF guard fires first.
- $this->clientService->expects($this->never())->method('newClient');
-
- $response = $this->service->fetchAndMergeFeeds(
- feedUrls: ['http://attacker.internal/feed.rss'],
- limit: 10
- );
-
- $this->assertSame([], $response['items']);
- $this->assertSame(1, $response['feedsFailed']);
- }//end testFetchAndMergeFeedsRejectsHttpUrls()
-
- /**
- * C1 SSRF: extractFeedUrls MUST drop http:// entries (HTTPS-only).
- */
- public function testExtractNewsConfigDropsHttpFeedUrls(): void
- {
- $placement = new WidgetPlacement();
- $placement->setStyleConfig(json_encode([
- 'feedUrls' => [
- 'https://valid.example.com/feed',
- 'http://insecure.example.com/feed',
- 'ftp://nope.example.com/feed',
- ],
- ]));
-
- $config = $this->service->extractNewsConfig(placement: $placement);
-
- $this->assertSame(['https://valid.example.com/feed'], $config['feedUrls']);
- }//end testExtractNewsConfigDropsHttpFeedUrls()
+ $items = $this->service->parseRssFeed(
+ feedContent: $atom,
+ sourceUrl: 'https://example.com/atom',
+ sourceTitle: 'fallback'
+ );
+
+ $this->assertCount(1, $items);
+ $this->assertSame('urn:1', $items[0]['guid']);
+ $this->assertSame('Atom one', $items[0]['title']);
+ $this->assertSame('https://example.com/atom-one', $items[0]['link']);
+ $this->assertSame('Atom Source', $items[0]['sourceTitle']);
+ }//end testParseRssFeedAcceptsAtom()
+
+ public function testParseRssFeedReturnsEmptyOnGarbage(): void {
+ $items = $this->service->parseRssFeed(
+ feedContent: '<>',
+ sourceUrl: 'https://x.example.com/bad',
+ sourceTitle: 'bad'
+ );
+
+ $this->assertSame([], $items);
+ }//end testParseRssFeedReturnsEmptyOnGarbage()
+
+ public function testDeduplicateItemsKeepsFirstOccurrence(): void {
+ $items = [
+ ['guid' => 'a', 'title' => 'first'],
+ ['guid' => 'b', 'title' => 'second'],
+ ['guid' => 'a', 'title' => 'duplicate'],
+ ];
+
+ $out = $this->service->deduplicateItems(items: $items);
+
+ $this->assertCount(2, $out);
+ $this->assertSame('first', $out[0]['title']);
+ $this->assertSame('second', $out[1]['title']);
+ }//end testDeduplicateItemsKeepsFirstOccurrence()
+
+ public function testSortItemsByDateDescending(): void {
+ $items = [
+ ['guid' => '1', 'pubDate' => '2026-04-30T10:00:00Z'],
+ ['guid' => '2', 'pubDate' => '2026-05-01T16:00:00Z'],
+ ['guid' => '3', 'pubDate' => '2026-05-01T14:00:00Z'],
+ ];
+
+ $sorted = $this->service->sortItemsByDate(items: $items);
+
+ $this->assertSame('2', $sorted[0]['guid']);
+ $this->assertSame('3', $sorted[1]['guid']);
+ $this->assertSame('1', $sorted[2]['guid']);
+ }//end testSortItemsByDateDescending()
+
+ public function testSanitiseSummaryHtmlAllowsWhitelistedTags(): void {
+ $html = 'Read our latest post
';
+
+ $clean = $this->service->sanitiseSummaryHtml(html: $html);
+
+ $this->assertStringContainsString('', $clean);
+ $this->assertStringContainsString('', $clean);
+ }//end testSanitiseSummaryHtmlAllowsWhitelistedTags()
+
+ public function testSanitiseSummaryStripsScriptTags(): void {
+ $html = 'Hi
';
+
+ $clean = $this->service->sanitiseSummaryHtml(html: $html);
+
+ $this->assertStringNotContainsString('assertStringNotContainsString('service->sanitiseSummaryHtml(html: $html);
+
+ $this->assertStringContainsString('rel="noopener noreferrer"', $clean);
+ }//end testSanitiseSummaryForcesRelOnLinks()
+
+ public function testSanitiseSummaryNeutralisesJavascriptHref(): void {
+ $html = 'danger';
+
+ $clean = $this->service->sanitiseSummaryHtml(html: $html);
+
+ $this->assertStringNotContainsString('javascript:', $clean);
+ $this->assertStringContainsString('href="#"', $clean);
+ }//end testSanitiseSummaryNeutralisesJavascriptHref()
+
+ public function testCheckAllowListAcceptsAllWhenEmpty(): void {
+ $this->appConfig
+ ->method('getValueString')
+ ->willReturn('');
+
+ $this->assertTrue($this->service->checkAllowList(url: 'https://anything.example.com/feed'));
+ }//end testCheckAllowListAcceptsAllWhenEmpty()
+
+ public function testCheckAllowListMatchesCaseInsensitively(): void {
+ $this->appConfig
+ ->method('getValueString')
+ ->willReturn(json_encode(value: ['Example.Org']));
+
+ $this->assertTrue($this->service->checkAllowList(url: 'https://example.org/feed'));
+ }//end testCheckAllowListMatchesCaseInsensitively()
+
+ public function testCheckAllowListRejectsHostnamesNotInList(): void {
+ $this->appConfig
+ ->method('getValueString')
+ ->willReturn(json_encode(value: ['allowed.example.com']));
+
+ $this->assertFalse($this->service->checkAllowList(url: 'https://blocked.example.org/feed'));
+ }//end testCheckAllowListRejectsHostnamesNotInList()
+
+ public function testCheckAllowListSubdomainNotImplied(): void {
+ $this->appConfig
+ ->method('getValueString')
+ ->willReturn(json_encode(value: ['example.org']));
+
+ // Per spec REQ-NEWS-006: exact hostname required, no wildcard
+ // subdomain expansion.
+ $this->assertFalse($this->service->checkAllowList(url: 'https://news.example.org/feed'));
+ }//end testCheckAllowListSubdomainNotImplied()
+
+ public function testCheckMetadataFilterRejectsWhenSpecNotImplemented(): void {
+ // dashboard-metadata-fields capability not on this branch — the
+ // filter must conservatively return false (treat missing field
+ // as null which never matches a configured equality).
+ $this->assertFalse(
+ $this->service->checkMetadataFilter(
+ dashboardId: 1,
+ metadataFilter: ['fieldKey' => 'department', 'value' => 'marketing']
+ )
+ );
+ }//end testCheckMetadataFilterRejectsWhenSpecNotImplemented()
+
+ public function testFetchAndMergeFeedsWithEmptyListReturnsEmptyResponse(): void {
+ $response = $this->service->fetchAndMergeFeeds(feedUrls: [], limit: 10);
+
+ $this->assertSame([], $response['items']);
+ $this->assertSame(0, $response['feedsFailed']);
+ $this->assertSame([], $response['failedUrls']);
+ }//end testFetchAndMergeFeedsWithEmptyListReturnsEmptyResponse()
+
+ /**
+ * C1 SSRF: http:// URLs MUST be rejected before any allow-list check.
+ * The UrlSafetyValidator rejects non-HTTPS, so fetchAndMergeFeeds must
+ * count the URL as failed without attempting a network request.
+ */
+ public function testFetchAndMergeFeedsRejectsHttpUrls(): void {
+ // No HTTP client interaction expected — SSRF guard fires first.
+ $this->clientService->expects($this->never())->method('newClient');
+
+ $response = $this->service->fetchAndMergeFeeds(
+ feedUrls: ['http://attacker.internal/feed.rss'],
+ limit: 10
+ );
+
+ $this->assertSame([], $response['items']);
+ $this->assertSame(1, $response['feedsFailed']);
+ }//end testFetchAndMergeFeedsRejectsHttpUrls()
+
+ /**
+ * C1 SSRF: extractFeedUrls MUST drop http:// entries (HTTPS-only).
+ */
+ public function testExtractNewsConfigDropsHttpFeedUrls(): void {
+ $placement = new WidgetPlacement();
+ $placement->setStyleConfig(json_encode([
+ 'feedUrls' => [
+ 'https://valid.example.com/feed',
+ 'http://insecure.example.com/feed',
+ 'ftp://nope.example.com/feed',
+ ],
+ ]));
+
+ $config = $this->service->extractNewsConfig(placement: $placement);
+
+ $this->assertSame(['https://valid.example.com/feed'], $config['feedUrls']);
+ }//end testExtractNewsConfigDropsHttpFeedUrls()
}//end class
diff --git a/tests/Unit/Service/OrgNavigationServiceTest.php b/tests/Unit/Service/OrgNavigationServiceTest.php
index 381e1715..7b963437 100644
--- a/tests/Unit/Service/OrgNavigationServiceTest.php
+++ b/tests/Unit/Service/OrgNavigationServiceTest.php
@@ -41,444 +41,400 @@
/**
* Tests for the org-wide navigation editor service.
*/
-class OrgNavigationServiceTest extends TestCase
-{
-
- /** @var IAppData&MockObject */
- private $appData;
-
- /** @var AdminTemplateService&MockObject */
- private $templateService;
-
- private OrgNavigationService $service;
-
-
- protected function setUp(): void
- {
- $this->appData = $this->createMock(IAppData::class);
- $this->templateService = $this->createMock(AdminTemplateService::class);
-
- $this->service = new OrgNavigationService(
- appData: $this->appData,
- templateService: $this->templateService,
- );
-
- }//end setUp()
-
-
- /**
- * Build a deterministic UUID v4 derived from the given seed so
- * fixtures stay readable.
- *
- * @param string $seed The seed.
- *
- * @return string A canonical UUID string.
- */
- private function uuid(string $seed): string
- {
- $hash = md5($seed);
- return sprintf(
- '%s-%s-4%s-8%s-%s',
- substr($hash, 0, 8),
- substr($hash, 8, 4),
- substr($hash, 12, 3),
- substr($hash, 15, 3),
- substr($hash, 18, 12)
- );
-
- }//end uuid()
-
-
- public function testValidateAcceptsWellFormedTree(): void
- {
- $tree = [
- [
- 'id' => $this->uuid('a'),
- 'label' => 'Section A',
- 'icon' => 'folder',
- 'url' => null,
- 'openInNewTab' => false,
- 'groupVisibility' => null,
- 'children' => [
- [
- 'id' => $this->uuid('a.1'),
- 'label' => 'Child',
- 'url' => '/apps/launchpad/dashboards',
- 'children' => [],
- ],
- ],
- ],
- ];
-
- $this->service->validateTree(tree: $tree);
- $this->assertTrue(true);
-
- }//end testValidateAcceptsWellFormedTree()
-
-
- public function testValidateRejectsTreeExceedingDepth(): void
- {
- $tree = [
- [
- 'id' => $this->uuid('l1'),
- 'label' => 'L1',
- 'children' => [
- [
- 'id' => $this->uuid('l2'),
- 'label' => 'L2',
- 'children' => [
- [
- 'id' => $this->uuid('l3'),
- 'label' => 'L3',
- 'children' => [
- [
- 'id' => $this->uuid('l4'),
- 'label' => 'L4 too deep',
- 'children' => [],
- ],
- ],
- ],
- ],
- ],
- ],
- ],
- ];
-
- $this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('Tree depth cannot exceed 3 levels');
- $this->service->validateTree(tree: $tree);
-
- }//end testValidateRejectsTreeExceedingDepth()
-
-
- public function testValidateRejectsDuplicateIds(): void
- {
- $shared = $this->uuid('shared');
- $tree = [
- ['id' => $shared, 'label' => 'A'],
- ['id' => $shared, 'label' => 'B'],
- ];
-
- $this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessageMatches('/duplicate.*id/i');
- $this->service->validateTree(tree: $tree);
-
- }//end testValidateRejectsDuplicateIds()
-
-
- public function testValidateRejectsJavascriptUrl(): void
- {
- $tree = [
- ['id' => $this->uuid('x'), 'label' => 'X', 'url' => 'JavaScript:alert(1)'],
- ];
-
- $this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('URL scheme is not allowed');
- $this->service->validateTree(tree: $tree);
-
- }//end testValidateRejectsJavascriptUrl()
-
-
- public function testValidateRejectsDataUrl(): void
- {
- $tree = [
- ['id' => $this->uuid('x'), 'label' => 'X', 'url' => 'data:text/html,'],
- ];
-
- $this->expectException(InvalidArgumentException::class);
- $this->service->validateTree(tree: $tree);
-
- }//end testValidateRejectsDataUrl()
-
-
- public function testValidateRejectsEmptyLabel(): void
- {
- $tree = [
- ['id' => $this->uuid('x'), 'label' => ' '],
- ];
-
- $this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('label is required');
- $this->service->validateTree(tree: $tree);
-
- }//end testValidateRejectsEmptyLabel()
-
-
- public function testValidateRejectsNonUuidId(): void
- {
- $tree = [
- ['id' => 'not-a-uuid', 'label' => 'X'],
- ];
-
- $this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('Node id must be a valid UUID');
- $this->service->validateTree(tree: $tree);
-
- }//end testValidateRejectsNonUuidId()
-
-
- public function testFilterReturnsFullTreeWhenAllNodesAreUnrestricted(): void
- {
- $tree = [
- [
- 'id' => $this->uuid('a'),
- 'label' => 'A',
- 'groupVisibility' => null,
- 'children' => [
- [
- 'id' => $this->uuid('a.1'),
- 'label' => 'A.1',
- 'groupVisibility' => null,
- 'children' => [],
- ],
- ],
- ],
- ];
-
- $this->templateService
- ->method('getUserGroupIdsFor')
- ->willReturn(['anyone']);
-
- $result = $this->service->filterTreeByUserGroups(
- tree: $tree,
- userId: 'alice'
- );
-
- $this->assertCount(1, $result);
- $this->assertCount(1, $result[0]['children']);
-
- }//end testFilterReturnsFullTreeWhenAllNodesAreUnrestricted()
-
+class OrgNavigationServiceTest extends TestCase {
+
+ /** @var IAppData&MockObject */
+ private $appData;
+
+ /** @var AdminTemplateService&MockObject */
+ private $templateService;
+
+ private OrgNavigationService $service;
+
+ protected function setUp(): void {
+ $this->appData = $this->createMock(IAppData::class);
+ $this->templateService = $this->createMock(AdminTemplateService::class);
+
+ $this->service = new OrgNavigationService(
+ appData: $this->appData,
+ templateService: $this->templateService,
+ );
+
+ }//end setUp()
+
+ /**
+ * Build a deterministic UUID v4 derived from the given seed so
+ * fixtures stay readable.
+ *
+ * @param string $seed The seed.
+ *
+ * @return string A canonical UUID string.
+ */
+ private function uuid(string $seed): string {
+ $hash = md5($seed);
+ return sprintf(
+ '%s-%s-4%s-8%s-%s',
+ substr($hash, 0, 8),
+ substr($hash, 8, 4),
+ substr($hash, 12, 3),
+ substr($hash, 15, 3),
+ substr($hash, 18, 12)
+ );
+
+ }//end uuid()
+
+ public function testValidateAcceptsWellFormedTree(): void {
+ $tree = [
+ [
+ 'id' => $this->uuid('a'),
+ 'label' => 'Section A',
+ 'icon' => 'folder',
+ 'url' => null,
+ 'openInNewTab' => false,
+ 'groupVisibility' => null,
+ 'children' => [
+ [
+ 'id' => $this->uuid('a.1'),
+ 'label' => 'Child',
+ 'url' => '/apps/launchpad/dashboards',
+ 'children' => [],
+ ],
+ ],
+ ],
+ ];
+
+ $this->service->validateTree(tree: $tree);
+ $this->assertTrue(true);
+
+ }//end testValidateAcceptsWellFormedTree()
+
+ public function testValidateRejectsTreeExceedingDepth(): void {
+ $tree = [
+ [
+ 'id' => $this->uuid('l1'),
+ 'label' => 'L1',
+ 'children' => [
+ [
+ 'id' => $this->uuid('l2'),
+ 'label' => 'L2',
+ 'children' => [
+ [
+ 'id' => $this->uuid('l3'),
+ 'label' => 'L3',
+ 'children' => [
+ [
+ 'id' => $this->uuid('l4'),
+ 'label' => 'L4 too deep',
+ 'children' => [],
+ ],
+ ],
+ ],
+ ],
+ ],
+ ],
+ ],
+ ];
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->expectExceptionMessage('Tree depth cannot exceed 3 levels');
+ $this->service->validateTree(tree: $tree);
+
+ }//end testValidateRejectsTreeExceedingDepth()
+
+ public function testValidateRejectsDuplicateIds(): void {
+ $shared = $this->uuid('shared');
+ $tree = [
+ ['id' => $shared, 'label' => 'A'],
+ ['id' => $shared, 'label' => 'B'],
+ ];
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->expectExceptionMessageMatches('/duplicate.*id/i');
+ $this->service->validateTree(tree: $tree);
+
+ }//end testValidateRejectsDuplicateIds()
+
+ public function testValidateRejectsJavascriptUrl(): void {
+ $tree = [
+ ['id' => $this->uuid('x'), 'label' => 'X', 'url' => 'JavaScript:alert(1)'],
+ ];
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->expectExceptionMessage('URL scheme is not allowed');
+ $this->service->validateTree(tree: $tree);
+
+ }//end testValidateRejectsJavascriptUrl()
+
+ public function testValidateRejectsDataUrl(): void {
+ $tree = [
+ ['id' => $this->uuid('x'), 'label' => 'X', 'url' => 'data:text/html,'],
+ ];
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->service->validateTree(tree: $tree);
+
+ }//end testValidateRejectsDataUrl()
+
+ public function testValidateRejectsEmptyLabel(): void {
+ $tree = [
+ ['id' => $this->uuid('x'), 'label' => ' '],
+ ];
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->expectExceptionMessage('label is required');
+ $this->service->validateTree(tree: $tree);
+
+ }//end testValidateRejectsEmptyLabel()
+
+ public function testValidateRejectsNonUuidId(): void {
+ $tree = [
+ ['id' => 'not-a-uuid', 'label' => 'X'],
+ ];
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->expectExceptionMessage('Node id must be a valid UUID');
+ $this->service->validateTree(tree: $tree);
+
+ }//end testValidateRejectsNonUuidId()
+
+ public function testFilterReturnsFullTreeWhenAllNodesAreUnrestricted(): void {
+ $tree = [
+ [
+ 'id' => $this->uuid('a'),
+ 'label' => 'A',
+ 'groupVisibility' => null,
+ 'children' => [
+ [
+ 'id' => $this->uuid('a.1'),
+ 'label' => 'A.1',
+ 'groupVisibility' => null,
+ 'children' => [],
+ ],
+ ],
+ ],
+ ];
+
+ $this->templateService
+ ->method('getUserGroupIdsFor')
+ ->willReturn(['anyone']);
+
+ $result = $this->service->filterTreeByUserGroups(
+ tree: $tree,
+ userId: 'alice'
+ );
+
+ $this->assertCount(1, $result);
+ $this->assertCount(1, $result[0]['children']);
+
+ }//end testFilterReturnsFullTreeWhenAllNodesAreUnrestricted()
+
+ public function testFilterHidesNodeWhenUserNotInGroup(): void {
+ $tree = [
+ [
+ 'id' => $this->uuid('admin'),
+ 'label' => 'Admin only',
+ 'groupVisibility' => ['admin'],
+ 'children' => [],
+ ],
+ [
+ 'id' => $this->uuid('public'),
+ 'label' => 'Public',
+ 'groupVisibility' => null,
+ 'children' => [],
+ ],
+ ];
+
+ $this->templateService
+ ->method('getUserGroupIdsFor')
+ ->willReturn(['users']);
+
+ $result = $this->service->filterTreeByUserGroups(
+ tree: $tree,
+ userId: 'bob'
+ );
+
+ $this->assertCount(1, $result);
+ $this->assertSame('Public', $result[0]['label']);
+
+ }//end testFilterHidesNodeWhenUserNotInGroup()
+
+ public function testFilterShowsNodeWhenUserMatchesAnyListedGroup(): void {
+ $tree = [
+ [
+ 'id' => $this->uuid('mkt'),
+ 'label' => 'Sales/Marketing',
+ 'groupVisibility' => ['marketing', 'sales'],
+ 'children' => [],
+ ],
+ ];
+
+ $this->templateService
+ ->method('getUserGroupIdsFor')
+ ->willReturn(['sales']);
+
+ $result = $this->service->filterTreeByUserGroups(
+ tree: $tree,
+ userId: 'sam'
+ );
+
+ $this->assertCount(1, $result);
+
+ }//end testFilterShowsNodeWhenUserMatchesAnyListedGroup()
+
+ public function testFilterCascadesHiddenParentToChildren(): void {
+ $tree = [
+ [
+ 'id' => $this->uuid('p'),
+ 'label' => 'Parent',
+ 'groupVisibility' => ['secret'],
+ 'children' => [
+ [
+ 'id' => $this->uuid('c'),
+ 'label' => 'Child',
+ 'groupVisibility' => null,
+ 'children' => [],
+ ],
+ ],
+ ],
+ ];
+
+ $this->templateService
+ ->method('getUserGroupIdsFor')
+ ->willReturn(['users']);
+
+ $result = $this->service->filterTreeByUserGroups(
+ tree: $tree,
+ userId: 'eve'
+ );
+
+ $this->assertSame([], $result);
+
+ }//end testFilterCascadesHiddenParentToChildren()
+
+ public function testGetTreeReturnsEmptyWhenFolderMissing(): void {
+ $this->appData
+ ->method('getFolder')
+ ->willThrowException(new NotFoundException());
+
+ $this->assertSame([], $this->service->getTree());
+
+ }//end testGetTreeReturnsEmptyWhenFolderMissing()
+
+ public function testGetTreeReturnsEmptyWhenFileMissing(): void {
+ $folder = $this->createMock(ISimpleFolder::class);
+ $folder->method('getFile')
+ ->willThrowException(new NotFoundException());
+
+ $this->appData
+ ->method('getFolder')
+ ->willReturn($folder);
+
+ $this->assertSame([], $this->service->getTree());
+
+ }//end testGetTreeReturnsEmptyWhenFileMissing()
+
+ public function testGetTreeDecodesPersistedJson(): void {
+ $payload = json_encode([
+ ['id' => $this->uuid('only'), 'label' => 'Only', 'children' => []],
+ ]);
+
+ $file = $this->createMock(ISimpleFile::class);
+ $file->method('getSize')->willReturn(strlen((string)$payload));
+ $file->method('getContent')->willReturn($payload);
+
+ $folder = $this->createMock(ISimpleFolder::class);
+ $folder->method('getFile')->willReturn($file);
+
+ $this->appData
+ ->method('getFolder')
+ ->willReturn($folder);
+
+ $tree = $this->service->getTree(language: 'nl');
+
+ $this->assertCount(1, $tree);
+ $this->assertSame('Only', $tree[0]['label']);
+
+ }//end testGetTreeDecodesPersistedJson()
+
+ public function testSetTreeWritesNewFileWhenAbsent(): void {
+ $folder = $this->createMock(ISimpleFolder::class);
+ $folder->method('getFile')
+ ->willThrowException(new NotFoundException());
+
+ $folder->expects($this->once())
+ ->method('newFile')
+ ->with(
+ $this->equalTo('nl.json'),
+ $this->callback(static function (string $content): bool {
+ $decoded = json_decode($content, true);
+ return is_array($decoded) === true
+ && count($decoded) === 1
+ && $decoded[0]['label'] === 'Item';
+ })
+ );
+
+ $this->appData
+ ->method('getFolder')
+ ->willReturn($folder);
+
+ $this->service->setTree(
+ tree: [
+ ['id' => $this->uuid('one'), 'label' => 'Item', 'children' => []],
+ ],
+ language: 'nl'
+ );
+
+ }//end testSetTreeWritesNewFileWhenAbsent()
+
+ public function testSetTreeOverwritesExistingFile(): void {
+ $file = $this->createMock(ISimpleFile::class);
+ $file->expects($this->once())->method('putContent');
+
+ $folder = $this->createMock(ISimpleFolder::class);
+ $folder->method('getFile')->willReturn($file);
+
+ $this->appData
+ ->method('getFolder')
+ ->willReturn($folder);
- public function testFilterHidesNodeWhenUserNotInGroup(): void
- {
- $tree = [
- [
- 'id' => $this->uuid('admin'),
- 'label' => 'Admin only',
- 'groupVisibility' => ['admin'],
- 'children' => [],
- ],
- [
- 'id' => $this->uuid('public'),
- 'label' => 'Public',
- 'groupVisibility' => null,
- 'children' => [],
- ],
- ];
-
- $this->templateService
- ->method('getUserGroupIdsFor')
- ->willReturn(['users']);
+ $this->service->setTree(
+ tree: [
+ ['id' => $this->uuid('over'), 'label' => 'Over', 'children' => []],
+ ],
+ language: 'en'
+ );
- $result = $this->service->filterTreeByUserGroups(
- tree: $tree,
- userId: 'bob'
- );
+ }//end testSetTreeOverwritesExistingFile()
- $this->assertCount(1, $result);
- $this->assertSame('Public', $result[0]['label']);
-
- }//end testFilterHidesNodeWhenUserNotInGroup()
-
-
- public function testFilterShowsNodeWhenUserMatchesAnyListedGroup(): void
- {
- $tree = [
- [
- 'id' => $this->uuid('mkt'),
- 'label' => 'Sales/Marketing',
- 'groupVisibility' => ['marketing', 'sales'],
- 'children' => [],
- ],
- ];
-
- $this->templateService
- ->method('getUserGroupIdsFor')
- ->willReturn(['sales']);
-
- $result = $this->service->filterTreeByUserGroups(
- tree: $tree,
- userId: 'sam'
- );
-
- $this->assertCount(1, $result);
-
- }//end testFilterShowsNodeWhenUserMatchesAnyListedGroup()
-
-
- public function testFilterCascadesHiddenParentToChildren(): void
- {
- $tree = [
- [
- 'id' => $this->uuid('p'),
- 'label' => 'Parent',
- 'groupVisibility' => ['secret'],
- 'children' => [
- [
- 'id' => $this->uuid('c'),
- 'label' => 'Child',
- 'groupVisibility' => null,
- 'children' => [],
- ],
- ],
- ],
- ];
-
- $this->templateService
- ->method('getUserGroupIdsFor')
- ->willReturn(['users']);
-
- $result = $this->service->filterTreeByUserGroups(
- tree: $tree,
- userId: 'eve'
- );
-
- $this->assertSame([], $result);
-
- }//end testFilterCascadesHiddenParentToChildren()
-
-
- public function testGetTreeReturnsEmptyWhenFolderMissing(): void
- {
- $this->appData
- ->method('getFolder')
- ->willThrowException(new NotFoundException());
-
- $this->assertSame([], $this->service->getTree());
-
- }//end testGetTreeReturnsEmptyWhenFolderMissing()
-
-
- public function testGetTreeReturnsEmptyWhenFileMissing(): void
- {
- $folder = $this->createMock(ISimpleFolder::class);
- $folder->method('getFile')
- ->willThrowException(new NotFoundException());
-
- $this->appData
- ->method('getFolder')
- ->willReturn($folder);
-
- $this->assertSame([], $this->service->getTree());
-
- }//end testGetTreeReturnsEmptyWhenFileMissing()
-
-
- public function testGetTreeDecodesPersistedJson(): void
- {
- $payload = json_encode([
- ['id' => $this->uuid('only'), 'label' => 'Only', 'children' => []],
- ]);
-
- $file = $this->createMock(ISimpleFile::class);
- $file->method('getSize')->willReturn(strlen((string) $payload));
- $file->method('getContent')->willReturn($payload);
-
- $folder = $this->createMock(ISimpleFolder::class);
- $folder->method('getFile')->willReturn($file);
-
- $this->appData
- ->method('getFolder')
- ->willReturn($folder);
-
- $tree = $this->service->getTree(language: 'nl');
-
- $this->assertCount(1, $tree);
- $this->assertSame('Only', $tree[0]['label']);
-
- }//end testGetTreeDecodesPersistedJson()
-
-
- public function testSetTreeWritesNewFileWhenAbsent(): void
- {
- $folder = $this->createMock(ISimpleFolder::class);
- $folder->method('getFile')
- ->willThrowException(new NotFoundException());
-
- $folder->expects($this->once())
- ->method('newFile')
- ->with(
- $this->equalTo('nl.json'),
- $this->callback(static function (string $content): bool {
- $decoded = json_decode($content, true);
- return is_array($decoded) === true
- && count($decoded) === 1
- && $decoded[0]['label'] === 'Item';
- })
- );
-
- $this->appData
- ->method('getFolder')
- ->willReturn($folder);
-
- $this->service->setTree(
- tree: [
- ['id' => $this->uuid('one'), 'label' => 'Item', 'children' => []],
- ],
- language: 'nl'
- );
-
- }//end testSetTreeWritesNewFileWhenAbsent()
-
-
- public function testSetTreeOverwritesExistingFile(): void
- {
- $file = $this->createMock(ISimpleFile::class);
- $file->expects($this->once())->method('putContent');
-
- $folder = $this->createMock(ISimpleFolder::class);
- $folder->method('getFile')->willReturn($file);
-
- $this->appData
- ->method('getFolder')
- ->willReturn($folder);
-
- $this->service->setTree(
- tree: [
- ['id' => $this->uuid('over'), 'label' => 'Over', 'children' => []],
- ],
- language: 'en'
- );
-
- }//end testSetTreeOverwritesExistingFile()
-
-
- public function testSetTreeRejectsInvalidPayload(): void
- {
- $this->appData->expects($this->never())->method('getFolder');
-
- $this->expectException(InvalidArgumentException::class);
- $this->service->setTree(
- tree: [
- ['id' => 'not-uuid', 'label' => 'X'],
- ],
- language: 'nl'
- );
-
- }//end testSetTreeRejectsInvalidPayload()
-
-
- public function testSanitiseUrlAcceptsHttpsAndRelativePaths(): void
- {
- $this->assertSame(
- 'https://example.com/x',
- $this->service->sanitiseUrl(url: 'https://example.com/x')
- );
- $this->assertSame(
- '/apps/launchpad/dashboards',
- $this->service->sanitiseUrl(url: '/apps/launchpad/dashboards')
- );
-
- }//end testSanitiseUrlAcceptsHttpsAndRelativePaths()
-
-
- public function testSanitiseUrlRejectsVbscript(): void
- {
- $this->expectException(InvalidArgumentException::class);
- $this->service->sanitiseUrl(url: 'VBScript:msgbox');
-
- }//end testSanitiseUrlRejectsVbscript()
+ public function testSetTreeRejectsInvalidPayload(): void {
+ $this->appData->expects($this->never())->method('getFolder');
+ $this->expectException(InvalidArgumentException::class);
+ $this->service->setTree(
+ tree: [
+ ['id' => 'not-uuid', 'label' => 'X'],
+ ],
+ language: 'nl'
+ );
+
+ }//end testSetTreeRejectsInvalidPayload()
+
+ public function testSanitiseUrlAcceptsHttpsAndRelativePaths(): void {
+ $this->assertSame(
+ 'https://example.com/x',
+ $this->service->sanitiseUrl(url: 'https://example.com/x')
+ );
+ $this->assertSame(
+ '/apps/launchpad/dashboards',
+ $this->service->sanitiseUrl(url: '/apps/launchpad/dashboards')
+ );
+
+ }//end testSanitiseUrlAcceptsHttpsAndRelativePaths()
+
+ public function testSanitiseUrlRejectsVbscript(): void {
+ $this->expectException(InvalidArgumentException::class);
+ $this->service->sanitiseUrl(url: 'VBScript:msgbox');
+
+ }//end testSanitiseUrlRejectsVbscript()
}//end class
diff --git a/tests/Unit/Service/OrphanedDataCleanupServiceTest.php b/tests/Unit/Service/OrphanedDataCleanupServiceTest.php
index c20b49d7..b7271f85 100644
--- a/tests/Unit/Service/OrphanedDataCleanupServiceTest.php
+++ b/tests/Unit/Service/OrphanedDataCleanupServiceTest.php
@@ -37,285 +37,276 @@
/**
* Unit tests for OrphanedDataCleanupService.
*/
-class OrphanedDataCleanupServiceTest extends TestCase
-{
- /**
- * Registry mock.
- *
- * @var CategoryRegistryService&MockObject
- */
- private $registry;
-
- /**
- * Cache factory mock.
- *
- * @var ICacheFactory&MockObject
- */
- private $cacheFactory;
-
- /**
- * Cache mock returned by the factory.
- *
- * @var ICache&MockObject
- */
- private $cache;
-
- /**
- * DB connection mock (transaction tracking).
- *
- * @var IDBConnection&MockObject
- */
- private $db;
-
- /**
- * Activity manager mock.
- *
- * @var IActivityManager&MockObject
- */
- private $activity;
-
- /**
- * Logger mock.
- *
- * @var LoggerInterface&MockObject
- */
- private $logger;
-
- /**
- * Service under test.
- *
- * @var OrphanedDataCleanupService
- */
- private OrphanedDataCleanupService $service;
-
- /**
- * Build all mocks.
- *
- * @return void
- */
- protected function setUp(): void
- {
- $this->registry = $this->createMock(originalClassName: CategoryRegistryService::class);
- $this->cacheFactory = $this->createMock(originalClassName: ICacheFactory::class);
- $this->cache = $this->createMock(originalClassName: ICache::class);
- $this->db = $this->createMock(originalClassName: IDBConnection::class);
- $this->activity = $this->createMock(originalClassName: IActivityManager::class);
- $this->logger = $this->createMock(originalClassName: LoggerInterface::class);
-
- $this->cacheFactory->method('createDistributed')->willReturn($this->cache);
-
- $this->service = new OrphanedDataCleanupService(
- registry: $this->registry,
- cacheFactory: $this->cacheFactory,
- db: $this->db,
- activityManager: $this->activity,
- logger: $this->logger,
- );
- }
-
- /**
- * Build a category mock returning the supplied count from `scan`
- * and `purge`. `isAvailable()` is `true` by default.
- *
- * @param string $name Category identifier.
- * @param int $count Count to return from scan/purge.
- * @param bool $available Whether the category is available.
- *
- * @return CleanupCategoryInterface&MockObject The category.
- */
- private function makeCategory(
- string $name,
- int $count,
- bool $available=true
- ): CleanupCategoryInterface {
- $category = $this->createMock(originalClassName: CleanupCategoryInterface::class);
- $category->method('getName')->willReturn($name);
- $category->method('isAvailable')->willReturn($available);
- $category->method('scan')->willReturn($count);
- $category->method('purge')->willReturn($count);
-
- return $category;
- }
-
- /**
- * Scan with no filter MUST traverse every registered category in
- * registration order and aggregate counts.
- *
- * @return void
- */
- public function testScanAggregatesCountsAcrossRegistry(): void
- {
- $a = $this->makeCategory(name: 'a', count: 3);
- $b = $this->makeCategory(name: 'b', count: 0);
-
- $this->registry->method('getCategoryNames')->willReturn(['a', 'b']);
- $this->registry->method('getCategoryByName')->willReturnMap(
- [
- ['a', $a],
- ['b', $b],
- ]
- );
-
- // Cache empty so the orchestrator runs a fresh scan.
- $this->cache->method('get')->willReturn(null);
-
- $result = $this->service->scan();
-
- $this->assertSame(expected: 3, actual: $result->getTotalRows());
- $this->assertSame(
- expected: ['a' => 3, 'b' => 0],
- actual: $result->getByCategory()
- );
- }
-
- /**
- * Categories whose `isAvailable()` is `false` MUST end up under
- * `skipped` and contribute no count.
- *
- * @return void
- */
- public function testScanSkipsUnavailableCategories(): void
- {
- $a = $this->makeCategory(name: 'a', count: 3);
- $b = $this->makeCategory(name: 'b', count: 99, available: false);
-
- $this->registry->method('getCategoryNames')->willReturn(['a', 'b']);
- $this->registry->method('getCategoryByName')->willReturnMap(
- [
- ['a', $a],
- ['b', $b],
- ]
- );
- $this->cache->method('get')->willReturn(null);
-
- $result = $this->service->scan();
-
- $this->assertSame(expected: ['a' => 3], actual: $result->getByCategory());
- $this->assertSame(expected: ['b'], actual: $result->getSkipped());
- $this->assertSame(expected: 3, actual: $result->getTotalRows());
- }
-
- /**
- * The cache hit path MUST short-circuit the registry traversal
- * and return a hydrated DTO.
- *
- * @return void
- */
- public function testScanReturnsCachedResultWhenAvailable(): void
- {
- // Registry MUST NOT be touched on a cache hit.
- $this->registry->expects($this->never())->method('getCategoryNames');
-
- $this->cache->method('get')->willReturn(
- [
- 'byCategory' => ['x' => 7],
- 'totalRows' => 7,
- 'durationMs' => 1,
- 'dryRun' => false,
- 'scannedAt' => '2026-05-03T10:00:00Z',
- 'skipped' => [],
- ]
- );
-
- $result = $this->service->scan();
-
- $this->assertSame(expected: 7, actual: $result->getTotalRows());
- $this->assertSame(
- expected: '2026-05-03T10:00:00Z',
- actual: $result->getScannedAt()
- );
- }
-
- /**
- * A successful real purge MUST invalidate the cache.
- *
- * @return void
- */
- public function testRealPurgeInvalidatesCache(): void
- {
- $a = $this->makeCategory(name: 'a', count: 2);
-
- $this->registry->method('getCategoryNames')->willReturn(['a']);
- $this->registry->method('getCategoryByName')->willReturn($a);
-
- $this->cache->expects($this->once())
- ->method('remove')
- ->with(self::equalTo('launchpad.cleanup.scan'));
-
- $this->service->purge();
- }
-
- /**
- * Dry-run purge MUST wrap the work in a transaction rollback and
- * MUST NOT emit an Activity event or invalidate the cache.
- *
- * @return void
- */
- public function testDryRunRollsBackAndDoesNotEmitEvent(): void
- {
- $a = $this->makeCategory(name: 'a', count: 5);
-
- $this->registry->method('getCategoryNames')->willReturn(['a']);
- $this->registry->method('getCategoryByName')->willReturn($a);
-
- $this->db->expects($this->once())->method('beginTransaction');
- $this->db->expects($this->once())->method('rollBack');
- $this->cache->expects($this->never())->method('remove');
- $this->activity->expects($this->never())->method('publish');
-
- $result = $this->service->purge(categoryNames: [], dryRun: true);
-
- $this->assertTrue(condition: $result->isDryRun());
- $this->assertSame(expected: 5, actual: $result->getTotalRows());
- }
-
- /**
- * Real purge with a non-zero total MUST publish exactly one
- * activity event tagged with the source.
- *
- * @return void
- */
- public function testRealPurgeEmitsOneActivityEvent(): void
- {
- $a = $this->makeCategory(name: 'a', count: 4);
-
- $this->registry->method('getCategoryNames')->willReturn(['a']);
- $this->registry->method('getCategoryByName')->willReturn($a);
-
- $event = $this->createMock(originalClassName: IEvent::class);
- $event->method('setApp')->willReturnSelf();
- $event->method('setType')->willReturnSelf();
- $event->method('setAffectedUser')->willReturnSelf();
- $event->method('setAuthor')->willReturnSelf();
- $event->method('setSubject')->willReturnSelf();
- $event->method('setObject')->willReturnSelf();
-
- $this->activity->method('generateEvent')->willReturn($event);
- $this->activity->expects($this->once())->method('publish');
-
- $this->service->purge(
- categoryNames: [],
- dryRun: false,
- userId: 'admin',
- source: 'cli'
- );
- }
-
- /**
- * A real purge that finds zero rows MUST NOT emit an activity
- * event (avoids audit-log spam from idle daily runs).
- *
- * @return void
- */
- public function testRealPurgeWithZeroRowsDoesNotEmitEvent(): void
- {
- $a = $this->makeCategory(name: 'a', count: 0);
-
- $this->registry->method('getCategoryNames')->willReturn(['a']);
- $this->registry->method('getCategoryByName')->willReturn($a);
-
- $this->activity->expects($this->never())->method('publish');
-
- $this->service->purge();
- }
+class OrphanedDataCleanupServiceTest extends TestCase {
+ /**
+ * Registry mock.
+ *
+ * @var CategoryRegistryService&MockObject
+ */
+ private $registry;
+
+ /**
+ * Cache factory mock.
+ *
+ * @var ICacheFactory&MockObject
+ */
+ private $cacheFactory;
+
+ /**
+ * Cache mock returned by the factory.
+ *
+ * @var ICache&MockObject
+ */
+ private $cache;
+
+ /**
+ * DB connection mock (transaction tracking).
+ *
+ * @var IDBConnection&MockObject
+ */
+ private $db;
+
+ /**
+ * Activity manager mock.
+ *
+ * @var IActivityManager&MockObject
+ */
+ private $activity;
+
+ /**
+ * Logger mock.
+ *
+ * @var LoggerInterface&MockObject
+ */
+ private $logger;
+
+ /**
+ * Service under test.
+ *
+ * @var OrphanedDataCleanupService
+ */
+ private OrphanedDataCleanupService $service;
+
+ /**
+ * Build all mocks.
+ *
+ * @return void
+ */
+ protected function setUp(): void {
+ $this->registry = $this->createMock(originalClassName: CategoryRegistryService::class);
+ $this->cacheFactory = $this->createMock(originalClassName: ICacheFactory::class);
+ $this->cache = $this->createMock(originalClassName: ICache::class);
+ $this->db = $this->createMock(originalClassName: IDBConnection::class);
+ $this->activity = $this->createMock(originalClassName: IActivityManager::class);
+ $this->logger = $this->createMock(originalClassName: LoggerInterface::class);
+
+ $this->cacheFactory->method('createDistributed')->willReturn($this->cache);
+
+ $this->service = new OrphanedDataCleanupService(
+ registry: $this->registry,
+ cacheFactory: $this->cacheFactory,
+ db: $this->db,
+ activityManager: $this->activity,
+ logger: $this->logger,
+ );
+ }
+
+ /**
+ * Build a category mock returning the supplied count from `scan`
+ * and `purge`. `isAvailable()` is `true` by default.
+ *
+ * @param string $name Category identifier.
+ * @param int $count Count to return from scan/purge.
+ * @param bool $available Whether the category is available.
+ *
+ * @return CleanupCategoryInterface&MockObject The category.
+ */
+ private function makeCategory(
+ string $name,
+ int $count,
+ bool $available = true,
+ ): CleanupCategoryInterface {
+ $category = $this->createMock(originalClassName: CleanupCategoryInterface::class);
+ $category->method('getName')->willReturn($name);
+ $category->method('isAvailable')->willReturn($available);
+ $category->method('scan')->willReturn($count);
+ $category->method('purge')->willReturn($count);
+
+ return $category;
+ }
+
+ /**
+ * Scan with no filter MUST traverse every registered category in
+ * registration order and aggregate counts.
+ *
+ * @return void
+ */
+ public function testScanAggregatesCountsAcrossRegistry(): void {
+ $a = $this->makeCategory(name: 'a', count: 3);
+ $b = $this->makeCategory(name: 'b', count: 0);
+
+ $this->registry->method('getCategoryNames')->willReturn(['a', 'b']);
+ $this->registry->method('getCategoryByName')->willReturnMap(
+ [
+ ['a', $a],
+ ['b', $b],
+ ]
+ );
+
+ // Cache empty so the orchestrator runs a fresh scan.
+ $this->cache->method('get')->willReturn(null);
+
+ $result = $this->service->scan();
+
+ $this->assertSame(expected: 3, actual: $result->getTotalRows());
+ $this->assertSame(
+ expected: ['a' => 3, 'b' => 0],
+ actual: $result->getByCategory()
+ );
+ }
+
+ /**
+ * Categories whose `isAvailable()` is `false` MUST end up under
+ * `skipped` and contribute no count.
+ *
+ * @return void
+ */
+ public function testScanSkipsUnavailableCategories(): void {
+ $a = $this->makeCategory(name: 'a', count: 3);
+ $b = $this->makeCategory(name: 'b', count: 99, available: false);
+
+ $this->registry->method('getCategoryNames')->willReturn(['a', 'b']);
+ $this->registry->method('getCategoryByName')->willReturnMap(
+ [
+ ['a', $a],
+ ['b', $b],
+ ]
+ );
+ $this->cache->method('get')->willReturn(null);
+
+ $result = $this->service->scan();
+
+ $this->assertSame(expected: ['a' => 3], actual: $result->getByCategory());
+ $this->assertSame(expected: ['b'], actual: $result->getSkipped());
+ $this->assertSame(expected: 3, actual: $result->getTotalRows());
+ }
+
+ /**
+ * The cache hit path MUST short-circuit the registry traversal
+ * and return a hydrated DTO.
+ *
+ * @return void
+ */
+ public function testScanReturnsCachedResultWhenAvailable(): void {
+ // Registry MUST NOT be touched on a cache hit.
+ $this->registry->expects($this->never())->method('getCategoryNames');
+
+ $this->cache->method('get')->willReturn(
+ [
+ 'byCategory' => ['x' => 7],
+ 'totalRows' => 7,
+ 'durationMs' => 1,
+ 'dryRun' => false,
+ 'scannedAt' => '2026-05-03T10:00:00Z',
+ 'skipped' => [],
+ ]
+ );
+
+ $result = $this->service->scan();
+
+ $this->assertSame(expected: 7, actual: $result->getTotalRows());
+ $this->assertSame(
+ expected: '2026-05-03T10:00:00Z',
+ actual: $result->getScannedAt()
+ );
+ }
+
+ /**
+ * A successful real purge MUST invalidate the cache.
+ *
+ * @return void
+ */
+ public function testRealPurgeInvalidatesCache(): void {
+ $a = $this->makeCategory(name: 'a', count: 2);
+
+ $this->registry->method('getCategoryNames')->willReturn(['a']);
+ $this->registry->method('getCategoryByName')->willReturn($a);
+
+ $this->cache->expects($this->once())
+ ->method('remove')
+ ->with(self::equalTo('launchpad.cleanup.scan'));
+
+ $this->service->purge();
+ }
+
+ /**
+ * Dry-run purge MUST wrap the work in a transaction rollback and
+ * MUST NOT emit an Activity event or invalidate the cache.
+ *
+ * @return void
+ */
+ public function testDryRunRollsBackAndDoesNotEmitEvent(): void {
+ $a = $this->makeCategory(name: 'a', count: 5);
+
+ $this->registry->method('getCategoryNames')->willReturn(['a']);
+ $this->registry->method('getCategoryByName')->willReturn($a);
+
+ $this->db->expects($this->once())->method('beginTransaction');
+ $this->db->expects($this->once())->method('rollBack');
+ $this->cache->expects($this->never())->method('remove');
+ $this->activity->expects($this->never())->method('publish');
+
+ $result = $this->service->purge(categoryNames: [], dryRun: true);
+
+ $this->assertTrue(condition: $result->isDryRun());
+ $this->assertSame(expected: 5, actual: $result->getTotalRows());
+ }
+
+ /**
+ * Real purge with a non-zero total MUST publish exactly one
+ * activity event tagged with the source.
+ *
+ * @return void
+ */
+ public function testRealPurgeEmitsOneActivityEvent(): void {
+ $a = $this->makeCategory(name: 'a', count: 4);
+
+ $this->registry->method('getCategoryNames')->willReturn(['a']);
+ $this->registry->method('getCategoryByName')->willReturn($a);
+
+ $event = $this->createMock(originalClassName: IEvent::class);
+ $event->method('setApp')->willReturnSelf();
+ $event->method('setType')->willReturnSelf();
+ $event->method('setAffectedUser')->willReturnSelf();
+ $event->method('setAuthor')->willReturnSelf();
+ $event->method('setSubject')->willReturnSelf();
+ $event->method('setObject')->willReturnSelf();
+
+ $this->activity->method('generateEvent')->willReturn($event);
+ $this->activity->expects($this->once())->method('publish');
+
+ $this->service->purge(
+ categoryNames: [],
+ dryRun: false,
+ userId: 'admin',
+ source: 'cli'
+ );
+ }
+
+ /**
+ * A real purge that finds zero rows MUST NOT emit an activity
+ * event (avoids audit-log spam from idle daily runs).
+ *
+ * @return void
+ */
+ public function testRealPurgeWithZeroRowsDoesNotEmitEvent(): void {
+ $a = $this->makeCategory(name: 'a', count: 0);
+
+ $this->registry->method('getCategoryNames')->willReturn(['a']);
+ $this->registry->method('getCategoryByName')->willReturn($a);
+
+ $this->activity->expects($this->never())->method('publish');
+
+ $this->service->purge();
+ }
}
diff --git a/tests/Unit/Service/PeopleWidgetServiceTest.php b/tests/Unit/Service/PeopleWidgetServiceTest.php
index f71cb889..18b559b8 100644
--- a/tests/Unit/Service/PeopleWidgetServiceTest.php
+++ b/tests/Unit/Service/PeopleWidgetServiceTest.php
@@ -44,531 +44,509 @@
*
* @SuppressWarnings(PHPMD.CouplingBetweenObjects) Mirrors constructor.
*/
-class PeopleWidgetServiceTest extends TestCase
-{
-
- /**
- * @var IUserManager&MockObject
- */
- private $userManager;
-
- /**
- * @var IGroupManager&MockObject
- */
- private $groupManager;
-
- /**
- * @var IAccountManager&MockObject
- */
- private $accountManager;
-
- /**
- * @var IURLGenerator&MockObject
- */
- private $urlGenerator;
-
- /**
- * @var AdminTemplateService&MockObject
- */
- private $adminTemplateService;
-
- private PeopleWidgetService $service;
-
- /**
- * @return void
- */
- protected function setUp(): void
- {
- parent::setUp();
-
- $this->userManager = $this->createMock(originalClassName: IUserManager::class);
- $this->groupManager = $this->createMock(originalClassName: IGroupManager::class);
- $this->accountManager = $this->createMock(originalClassName: IAccountManager::class);
- $this->urlGenerator = $this->createMock(originalClassName: IURLGenerator::class);
- $this->adminTemplateService = $this->createMock(originalClassName: AdminTemplateService::class);
-
- $this->urlGenerator->method('linkToRouteAbsolute')
- ->willReturnCallback(
- callback: static fn(string $route, array $args=[]): string => 'https://example.test/'.$route.'?'.http_build_query(data: $args)
- );
-
- // Default: any user has no groups. Tests can override per-call.
- $this->adminTemplateService->method('getUserGroupIdsFor')->willReturn([]);
-
- $this->service = new PeopleWidgetService(
- userManager: $this->userManager,
- groupManager: $this->groupManager,
- accountManager: $this->accountManager,
- urlGenerator: $this->urlGenerator,
- adminTemplateService: $this->adminTemplateService,
- );
- }//end setUp()
-
- // ---------------------------------------------------------------
- // computeDaysToBirthday — pure helper (REQ-PPL-005)
- // ---------------------------------------------------------------
-
- /**
- * @return void
- */
- public function testComputeDaysToBirthdayReturnsNullForBlankInput(): void
- {
- $this->assertNull(actual: PeopleWidgetService::computeDaysToBirthday(birthdate: null));
- $this->assertNull(actual: PeopleWidgetService::computeDaysToBirthday(birthdate: ''));
- $this->assertNull(actual: PeopleWidgetService::computeDaysToBirthday(birthdate: 'not-a-date'));
- }//end testComputeDaysToBirthdayReturnsNullForBlankInput()
-
- /**
- * @return void
- */
- public function testComputeDaysToBirthdayHandlesIsoInput(): void
- {
- $today = new \DateTimeImmutable(datetime: 'today');
- $iso = $today->modify(modifier: '+5 days')->format(format: '1990-m-d');
-
- $this->assertSame(
- expected: 5,
- actual: PeopleWidgetService::computeDaysToBirthday(birthdate: $iso)
- );
- }//end testComputeDaysToBirthdayHandlesIsoInput()
-
- /**
- * @return void
- */
- public function testComputeDaysToBirthdayHandlesLocaleFormat(): void
- {
- $today = new \DateTimeImmutable(datetime: 'today');
- $locale = $today->modify(modifier: '+10 days')->format(format: 'd-m-1990');
-
- $this->assertSame(
- expected: 10,
- actual: PeopleWidgetService::computeDaysToBirthday(birthdate: $locale)
- );
- }//end testComputeDaysToBirthdayHandlesLocaleFormat()
-
- /**
- * @return void
- */
- public function testComputeDaysToBirthdayWrapsToNextYearWhenPast(): void
- {
- $today = new \DateTimeImmutable(datetime: 'today');
- $past = $today->modify(modifier: '-30 days')->format(format: '1990-m-d');
-
- $days = PeopleWidgetService::computeDaysToBirthday(birthdate: $past);
- $this->assertNotNull(actual: $days);
- $this->assertGreaterThan(300, $days);
- }//end testComputeDaysToBirthdayWrapsToNextYearWhenPast()
-
- /**
- * Feb-29 birthday must NOT throw on non-leap years; the service falls
- * back to Feb-28. We verify by parsing 2027 (not a leap year) as the
- * candidate window.
- *
- * @return void
- */
- public function testComputeDaysToBirthdayHandlesFeb29OnNonLeapYear(): void
- {
- $days = PeopleWidgetService::computeDaysToBirthday(birthdate: '2000-02-29');
- $this->assertNotNull(
- actual: $days,
- message: 'Feb-29 input must not throw or return null on any year'
- );
- }//end testComputeDaysToBirthdayHandlesFeb29OnNonLeapYear()
-
- // ---------------------------------------------------------------
- // listUsers — argument validation (REQ-PPL-003)
- // ---------------------------------------------------------------
-
- /**
- * @return void
- */
- public function testListUsersRejectsLimitOverMax(): void
- {
- $this->expectException(exception: InvalidArgumentException::class);
- $this->service->listUsers(limit: PeopleWidgetService::MAX_LIMIT + 1);
- }//end testListUsersRejectsLimitOverMax()
-
- /**
- * @return void
- */
- public function testListUsersRejectsZeroLimit(): void
- {
- $this->expectException(exception: InvalidArgumentException::class);
- $this->service->listUsers(limit: 0);
- }//end testListUsersRejectsZeroLimit()
-
- /**
- * @return void
- */
- public function testListUsersRejectsNegativeOffset(): void
- {
- $this->expectException(exception: InvalidArgumentException::class);
- $this->service->listUsers(offset: -1);
- }//end testListUsersRejectsNegativeOffset()
-
- /**
- * @return void
- */
- public function testListUsersRejectsRecentActivitySort(): void
- {
- $this->expectException(exception: InvalidArgumentException::class);
- $this->service->listUsers(sortBy: 'recent-activity');
- }//end testListUsersRejectsRecentActivitySort()
-
- // ---------------------------------------------------------------
- // listUsers — pagination + projection (REQ-PPL-003, REQ-PPL-004)
- // ---------------------------------------------------------------
-
- /**
- * @return void
- */
- public function testListUsersReturnsPaginationShape(): void
- {
- $users = [];
- $users[] = $this->makeUser(uid: 'alice', display: 'Alice', email: 'alice@example.test');
- $users[] = $this->makeUser(uid: 'bob', display: 'Bob', email: '');
- $users[] = $this->makeUser(uid: 'carol', display: 'Carol', email: 'carol@example.test');
-
- $this->wireDirectory(orderedUsers: $users);
- $this->groupManager->method('getUserGroupIds')->willReturn([]);
-
- // Empty account so the optional fields are omitted.
- $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
-
- $result = $this->service->listUsers(limit: 2, offset: 0);
-
- $this->assertSame(expected: 3, actual: $result['total']);
- $this->assertTrue(condition: $result['hasMore']);
- $this->assertCount(expectedCount: 2, haystack: $result['users']);
-
- // Default sort = displayName ASC.
- $this->assertSame(expected: 'alice', actual: $result['users'][0]['uid']);
- $this->assertSame(expected: 'bob', actual: $result['users'][1]['uid']);
-
- // Empty email is OMITTED, not nulled (REQ-PPL-004).
- $this->assertArrayNotHasKey(key: 'email', array: $result['users'][1]);
- $this->assertArrayHasKey(key: 'email', array: $result['users'][0]);
- $this->assertSame(
- expected: 'alice@example.test',
- actual: $result['users'][0]['email']
- );
-
- // Avatar URL points to the configured route.
- $this->assertStringContainsString(
- needle: 'core.avatar.getAvatar',
- haystack: $result['users'][0]['avatarUrl']
- );
- }//end testListUsersReturnsPaginationShape()
-
- /**
- * @return void
- */
- public function testListUsersLastPageHasMoreFalse(): void
- {
- $users = [];
- $users[] = $this->makeUser(uid: 'alice', display: 'Alice');
- $users[] = $this->makeUser(uid: 'bob', display: 'Bob');
-
- $this->wireDirectory(orderedUsers: $users);
- $this->groupManager->method('getUserGroupIds')->willReturn([]);
- $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
-
- $result = $this->service->listUsers(limit: 50, offset: 0);
-
- $this->assertFalse(condition: $result['hasMore']);
- $this->assertSame(expected: 2, actual: $result['total']);
- $this->assertCount(expectedCount: 2, haystack: $result['users']);
- }//end testListUsersLastPageHasMoreFalse()
-
- /**
- * @return void
- */
- public function testListUsersExcludesDisabledByDefault(): void
- {
- $alice = $this->makeUser(uid: 'alice', display: 'Alice', enabled: true);
- $eve = $this->makeUser(uid: 'eve', display: 'Eve', enabled: false);
-
- // The backend returns both (display-name order); the bounded page
- // path skips the disabled user inside the window, and the exact
- // total comes from countUsersTotal() minus countDisabledUsers().
- $this->wireDirectory(orderedUsers: [$alice, $eve], disabledCount: 1);
- $this->groupManager->method('getUserGroupIds')->willReturn([]);
- $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
-
- $result = $this->service->listUsers();
-
- $this->assertSame(expected: 1, actual: $result['total']);
- $this->assertSame(expected: 'alice', actual: $result['users'][0]['uid']);
- }//end testListUsersExcludesDisabledByDefault()
-
- // ---------------------------------------------------------------
- // listUsers — group filter (REQ-PPL-006)
- // ---------------------------------------------------------------
-
- /**
- * @return void
- */
- public function testGroupFilterUnionDeduplicates(): void
- {
- $alice = $this->makeUser(uid: 'alice', display: 'Alice');
- $bob = $this->makeUser(uid: 'bob', display: 'Bob');
- $carol = $this->makeUser(uid: 'carol', display: 'Carol');
-
- $mgmt = $this->createMock(originalClassName: IGroup::class);
- $mgmt->method('getUsers')->willReturn([$alice, $bob]);
-
- $prod = $this->createMock(originalClassName: IGroup::class);
- $prod->method('getUsers')->willReturn([$bob, $carol]);
-
- $this->groupManager->method('get')
- ->willReturnCallback(
- callback: static function (string $gid) use ($mgmt, $prod) {
- if ($gid === 'management') {
- return $mgmt;
- }
-
- if ($gid === 'product') {
- return $prod;
- }
-
- return null;
- }
- );
-
- // Group sort path consults getUserGroupIds; default sort doesn't.
- $this->groupManager->method('getUserGroupIds')->willReturn([]);
- $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
-
- $result = $this->service->listUsers(
- filters: [
- [
- 'fieldName' => 'group',
- 'operator' => 'in',
- 'values' => ['management', 'product'],
- ],
- ],
- );
-
- // Bob appears once across both groups (dedup).
- $uids = array_map(
- callback: static fn(array $u): string => $u['uid'],
- array: $result['users']
- );
- $this->assertSame(expected: ['alice', 'bob', 'carol'], actual: $uids);
- $this->assertSame(expected: 3, actual: $result['total']);
- }//end testGroupFilterUnionDeduplicates()
-
- /**
- * @return void
- */
- public function testUnknownGroupYieldsZeroUsersWithoutError(): void
- {
- $this->groupManager->method('get')->willReturn(null);
- $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
-
- $result = $this->service->listUsers(
- filters: [
- [
- 'fieldName' => 'group',
- 'operator' => 'in',
- 'values' => ['nonexistent'],
- ],
- ],
- );
-
- $this->assertSame(expected: 0, actual: $result['total']);
- $this->assertSame(expected: [], actual: $result['users']);
- $this->assertFalse(condition: $result['hasMore']);
- }//end testUnknownGroupYieldsZeroUsersWithoutError()
-
- // ---------------------------------------------------------------
- // listUsers — account-field projection (REQ-PPL-005)
- // ---------------------------------------------------------------
-
- /**
- * @return void
- */
- public function testBirthdateIsNormalisedToIso(): void
- {
- $alice = $this->makeUser(uid: 'alice', display: 'Alice');
- $this->wireDirectory(orderedUsers: [$alice]);
- $this->groupManager->method('getUserGroupIds')->willReturn([]);
-
- $account = $this->makeAccount(
- properties: [
- IAccountManager::PROPERTY_BIRTHDATE => '10-06-1990',
- IAccountManager::PROPERTY_ROLE => 'PM',
- ]
- );
- $this->accountManager->method('getAccount')->willReturn($account);
-
- $result = $this->service->listUsers();
-
- $this->assertSame(
- expected: '1990-06-10',
- actual: $result['users'][0]['birthdate']
- );
- $this->assertSame(expected: 'PM', actual: $result['users'][0]['role']);
- }//end testBirthdateIsNormalisedToIso()
-
- /**
- * @return void
- */
- public function testShowBirthdaysFalseStripsBirthdate(): void
- {
- $alice = $this->makeUser(uid: 'alice', display: 'Alice');
- $this->wireDirectory(orderedUsers: [$alice]);
- $this->groupManager->method('getUserGroupIds')->willReturn([]);
-
- $account = $this->makeAccount(
- properties: [IAccountManager::PROPERTY_BIRTHDATE => '1990-06-10']
- );
- $this->accountManager->method('getAccount')->willReturn($account);
-
- $result = $this->service->listUsers(showBirthdays: false);
-
- $this->assertArrayNotHasKey(
- key: 'birthdate',
- array: $result['users'][0]
- );
- }//end testShowBirthdaysFalseStripsBirthdate()
-
- // ---------------------------------------------------------------
- // listUsers — bounded directory scan (fix-people-widget-unbounded-user-scan)
- // ---------------------------------------------------------------
-
- /**
- * With no `group` filter and the default `displayName` sort, the
- * service MUST page directly from the backend via a bounded
- * `searchDisplayName($pattern, $limit, $offset)` call and MUST NOT
- * fall back to the unbounded `search('')` full-directory scan.
- *
- * @return void
- */
- public function testDisplayNameSortUsesBoundedSearchNotFullScan(): void
- {
- $alice = $this->makeUser(uid: 'alice', display: 'Alice');
- $bob = $this->makeUser(uid: 'bob', display: 'Bob');
-
- // The unbounded scan MUST NOT be used for this path.
- $this->userManager->expects($this->never())->method('search');
-
- $captured = [];
- $this->userManager->expects($this->atLeastOnce())
- ->method('searchDisplayName')
- ->willReturnCallback(
- function (string $pattern, ?int $limit=null, ?int $offset=null) use (&$captured, $alice, $bob): array {
- $captured[] = ['pattern' => $pattern, 'limit' => $limit, 'offset' => $offset];
- return array_slice([$alice, $bob], (int) $offset, ($limit ?? 2));
- }
- );
- $this->userManager->method('countUsersTotal')->willReturn(2);
- $this->userManager->method('countDisabledUsers')->willReturn(0);
- $this->groupManager->method('getUserGroupIds')->willReturn([]);
- $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
-
- $result = $this->service->listUsers(limit: 10, offset: 0);
-
- // The backend was asked for a bounded, non-null limit.
- $this->assertNotEmpty($captured);
- $this->assertNotNull($captured[0]['limit']);
- $this->assertGreaterThanOrEqual(10, $captured[0]['limit']);
- $this->assertSame(0, $captured[0]['offset']);
- $this->assertSame('', $captured[0]['pattern']);
-
- // Envelope semantics unchanged from the caller's point of view.
- $this->assertSame(2, $result['total']);
- $this->assertFalse($result['hasMore']);
- $this->assertSame(['alice', 'bob'], array_column($result['users'], 'uid'));
- }//end testDisplayNameSortUsesBoundedSearchNotFullScan()
-
- // ---------------------------------------------------------------
- // Helpers
- // ---------------------------------------------------------------
-
- /**
- * Wire the user-directory backend for a no-group-filter,
- * display-name-sorted listing: a bounded `searchDisplayName` that
- * honours the streamed `limit`/`offset` window plus the
- * `countUsersTotal`/`countDisabledUsers` counters the bounded path
- * uses to size `total` without a full scan.
- *
- * @param IUser[] $orderedUsers Users in display-name order (enabled
- * and disabled). `countUsersTotal`
- * reports the full length.
- * @param int $disabledCount Number of disabled users in the set.
- *
- * @return void
- */
- private function wireDirectory(array $orderedUsers, int $disabledCount=0): void
- {
- $this->userManager->method('searchDisplayName')
- ->willReturnCallback(
- static function (string $pattern, ?int $limit=null, ?int $offset=null) use ($orderedUsers): array {
- return array_slice(
- $orderedUsers,
- (int) $offset,
- ($limit ?? count($orderedUsers))
- );
- }
- );
- $this->userManager->method('countUsersTotal')->willReturn(count($orderedUsers));
- $this->userManager->method('countDisabledUsers')->willReturn($disabledCount);
- }//end wireDirectory()
-
- /**
- * @param string $uid The user id.
- * @param string $display Display name.
- * @param string $email Email or empty string.
- * @param bool $enabled Whether the user is enabled.
- *
- * @return IUser&MockObject
- */
- private function makeUser(
- string $uid,
- string $display,
- string $email='',
- bool $enabled=true
- ): IUser {
- $user = $this->createMock(originalClassName: IUser::class);
- $user->method('getUID')->willReturn($uid);
- $user->method('getDisplayName')->willReturn($display);
- $user->method('getEMailAddress')->willReturn($email === '' ? null : $email);
- $user->method('isEnabled')->willReturn($enabled);
- return $user;
- }//end makeUser()
-
- /**
- * Build an account whose every property returns the empty string —
- * matches the "no profile fields set" baseline.
- *
- * @return IAccount&MockObject
- */
- private function emptyAccount(): IAccount
- {
- return $this->makeAccount(properties: []);
- }//end emptyAccount()
-
- /**
- * @param array $properties Map of property name → value.
- * Properties absent from the map
- * resolve to the empty string.
- *
- * @return IAccount&MockObject
- */
- private function makeAccount(array $properties): IAccount
- {
- $account = $this->createMock(originalClassName: IAccount::class);
- $account->method('getProperty')
- ->willReturnCallback(
- callback: function (string $name) use ($properties): IAccountProperty {
- $prop = $this->createMock(originalClassName: IAccountProperty::class);
- $prop->method('getValue')->willReturn($properties[$name] ?? '');
- $prop->method('getName')->willReturn($name);
- return $prop;
- }
- );
-
- return $account;
- }//end makeAccount()
+class PeopleWidgetServiceTest extends TestCase {
+
+ /**
+ * @var IUserManager&MockObject
+ */
+ private $userManager;
+
+ /**
+ * @var IGroupManager&MockObject
+ */
+ private $groupManager;
+
+ /**
+ * @var IAccountManager&MockObject
+ */
+ private $accountManager;
+
+ /**
+ * @var IURLGenerator&MockObject
+ */
+ private $urlGenerator;
+
+ /**
+ * @var AdminTemplateService&MockObject
+ */
+ private $adminTemplateService;
+
+ private PeopleWidgetService $service;
+
+ /**
+ * @return void
+ */
+ protected function setUp(): void {
+ parent::setUp();
+
+ $this->userManager = $this->createMock(originalClassName: IUserManager::class);
+ $this->groupManager = $this->createMock(originalClassName: IGroupManager::class);
+ $this->accountManager = $this->createMock(originalClassName: IAccountManager::class);
+ $this->urlGenerator = $this->createMock(originalClassName: IURLGenerator::class);
+ $this->adminTemplateService = $this->createMock(originalClassName: AdminTemplateService::class);
+
+ $this->urlGenerator->method('linkToRouteAbsolute')
+ ->willReturnCallback(
+ callback: static fn (string $route, array $args = []): string => 'https://example.test/' . $route . '?' . http_build_query(data: $args)
+ );
+
+ // Default: any user has no groups. Tests can override per-call.
+ $this->adminTemplateService->method('getUserGroupIdsFor')->willReturn([]);
+
+ $this->service = new PeopleWidgetService(
+ userManager: $this->userManager,
+ groupManager: $this->groupManager,
+ accountManager: $this->accountManager,
+ urlGenerator: $this->urlGenerator,
+ adminTemplateService: $this->adminTemplateService,
+ );
+ }//end setUp()
+
+ // ---------------------------------------------------------------
+ // computeDaysToBirthday — pure helper (REQ-PPL-005)
+ // ---------------------------------------------------------------
+
+ /**
+ * @return void
+ */
+ public function testComputeDaysToBirthdayReturnsNullForBlankInput(): void {
+ $this->assertNull(actual: PeopleWidgetService::computeDaysToBirthday(birthdate: null));
+ $this->assertNull(actual: PeopleWidgetService::computeDaysToBirthday(birthdate: ''));
+ $this->assertNull(actual: PeopleWidgetService::computeDaysToBirthday(birthdate: 'not-a-date'));
+ }//end testComputeDaysToBirthdayReturnsNullForBlankInput()
+
+ /**
+ * @return void
+ */
+ public function testComputeDaysToBirthdayHandlesIsoInput(): void {
+ $today = new \DateTimeImmutable(datetime: 'today');
+ $iso = $today->modify(modifier: '+5 days')->format(format: '1990-m-d');
+
+ $this->assertSame(
+ expected: 5,
+ actual: PeopleWidgetService::computeDaysToBirthday(birthdate: $iso)
+ );
+ }//end testComputeDaysToBirthdayHandlesIsoInput()
+
+ /**
+ * @return void
+ */
+ public function testComputeDaysToBirthdayHandlesLocaleFormat(): void {
+ $today = new \DateTimeImmutable(datetime: 'today');
+ $locale = $today->modify(modifier: '+10 days')->format(format: 'd-m-1990');
+
+ $this->assertSame(
+ expected: 10,
+ actual: PeopleWidgetService::computeDaysToBirthday(birthdate: $locale)
+ );
+ }//end testComputeDaysToBirthdayHandlesLocaleFormat()
+
+ /**
+ * @return void
+ */
+ public function testComputeDaysToBirthdayWrapsToNextYearWhenPast(): void {
+ $today = new \DateTimeImmutable(datetime: 'today');
+ $past = $today->modify(modifier: '-30 days')->format(format: '1990-m-d');
+
+ $days = PeopleWidgetService::computeDaysToBirthday(birthdate: $past);
+ $this->assertNotNull(actual: $days);
+ $this->assertGreaterThan(300, $days);
+ }//end testComputeDaysToBirthdayWrapsToNextYearWhenPast()
+
+ /**
+ * Feb-29 birthday must NOT throw on non-leap years; the service falls
+ * back to Feb-28. We verify by parsing 2027 (not a leap year) as the
+ * candidate window.
+ *
+ * @return void
+ */
+ public function testComputeDaysToBirthdayHandlesFeb29OnNonLeapYear(): void {
+ $days = PeopleWidgetService::computeDaysToBirthday(birthdate: '2000-02-29');
+ $this->assertNotNull(
+ actual: $days,
+ message: 'Feb-29 input must not throw or return null on any year'
+ );
+ }//end testComputeDaysToBirthdayHandlesFeb29OnNonLeapYear()
+
+ // ---------------------------------------------------------------
+ // listUsers — argument validation (REQ-PPL-003)
+ // ---------------------------------------------------------------
+
+ /**
+ * @return void
+ */
+ public function testListUsersRejectsLimitOverMax(): void {
+ $this->expectException(exception: InvalidArgumentException::class);
+ $this->service->listUsers(limit: PeopleWidgetService::MAX_LIMIT + 1);
+ }//end testListUsersRejectsLimitOverMax()
+
+ /**
+ * @return void
+ */
+ public function testListUsersRejectsZeroLimit(): void {
+ $this->expectException(exception: InvalidArgumentException::class);
+ $this->service->listUsers(limit: 0);
+ }//end testListUsersRejectsZeroLimit()
+
+ /**
+ * @return void
+ */
+ public function testListUsersRejectsNegativeOffset(): void {
+ $this->expectException(exception: InvalidArgumentException::class);
+ $this->service->listUsers(offset: -1);
+ }//end testListUsersRejectsNegativeOffset()
+
+ /**
+ * @return void
+ */
+ public function testListUsersRejectsRecentActivitySort(): void {
+ $this->expectException(exception: InvalidArgumentException::class);
+ $this->service->listUsers(sortBy: 'recent-activity');
+ }//end testListUsersRejectsRecentActivitySort()
+
+ // ---------------------------------------------------------------
+ // listUsers — pagination + projection (REQ-PPL-003, REQ-PPL-004)
+ // ---------------------------------------------------------------
+
+ /**
+ * @return void
+ */
+ public function testListUsersReturnsPaginationShape(): void {
+ $users = [];
+ $users[] = $this->makeUser(uid: 'alice', display: 'Alice', email: 'alice@example.test');
+ $users[] = $this->makeUser(uid: 'bob', display: 'Bob', email: '');
+ $users[] = $this->makeUser(uid: 'carol', display: 'Carol', email: 'carol@example.test');
+
+ $this->wireDirectory(orderedUsers: $users);
+ $this->groupManager->method('getUserGroupIds')->willReturn([]);
+
+ // Empty account so the optional fields are omitted.
+ $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
+
+ $result = $this->service->listUsers(limit: 2, offset: 0);
+
+ $this->assertSame(expected: 3, actual: $result['total']);
+ $this->assertTrue(condition: $result['hasMore']);
+ $this->assertCount(expectedCount: 2, haystack: $result['users']);
+
+ // Default sort = displayName ASC.
+ $this->assertSame(expected: 'alice', actual: $result['users'][0]['uid']);
+ $this->assertSame(expected: 'bob', actual: $result['users'][1]['uid']);
+
+ // Empty email is OMITTED, not nulled (REQ-PPL-004).
+ $this->assertArrayNotHasKey(key: 'email', array: $result['users'][1]);
+ $this->assertArrayHasKey(key: 'email', array: $result['users'][0]);
+ $this->assertSame(
+ expected: 'alice@example.test',
+ actual: $result['users'][0]['email']
+ );
+
+ // Avatar URL points to the configured route.
+ $this->assertStringContainsString(
+ needle: 'core.avatar.getAvatar',
+ haystack: $result['users'][0]['avatarUrl']
+ );
+ }//end testListUsersReturnsPaginationShape()
+
+ /**
+ * @return void
+ */
+ public function testListUsersLastPageHasMoreFalse(): void {
+ $users = [];
+ $users[] = $this->makeUser(uid: 'alice', display: 'Alice');
+ $users[] = $this->makeUser(uid: 'bob', display: 'Bob');
+
+ $this->wireDirectory(orderedUsers: $users);
+ $this->groupManager->method('getUserGroupIds')->willReturn([]);
+ $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
+
+ $result = $this->service->listUsers(limit: 50, offset: 0);
+
+ $this->assertFalse(condition: $result['hasMore']);
+ $this->assertSame(expected: 2, actual: $result['total']);
+ $this->assertCount(expectedCount: 2, haystack: $result['users']);
+ }//end testListUsersLastPageHasMoreFalse()
+
+ /**
+ * @return void
+ */
+ public function testListUsersExcludesDisabledByDefault(): void {
+ $alice = $this->makeUser(uid: 'alice', display: 'Alice', enabled: true);
+ $eve = $this->makeUser(uid: 'eve', display: 'Eve', enabled: false);
+
+ // The backend returns both (display-name order); the bounded page
+ // path skips the disabled user inside the window, and the exact
+ // total comes from countUsersTotal() minus countDisabledUsers().
+ $this->wireDirectory(orderedUsers: [$alice, $eve], disabledCount: 1);
+ $this->groupManager->method('getUserGroupIds')->willReturn([]);
+ $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
+
+ $result = $this->service->listUsers();
+
+ $this->assertSame(expected: 1, actual: $result['total']);
+ $this->assertSame(expected: 'alice', actual: $result['users'][0]['uid']);
+ }//end testListUsersExcludesDisabledByDefault()
+
+ // ---------------------------------------------------------------
+ // listUsers — group filter (REQ-PPL-006)
+ // ---------------------------------------------------------------
+
+ /**
+ * @return void
+ */
+ public function testGroupFilterUnionDeduplicates(): void {
+ $alice = $this->makeUser(uid: 'alice', display: 'Alice');
+ $bob = $this->makeUser(uid: 'bob', display: 'Bob');
+ $carol = $this->makeUser(uid: 'carol', display: 'Carol');
+
+ $mgmt = $this->createMock(originalClassName: IGroup::class);
+ $mgmt->method('getUsers')->willReturn([$alice, $bob]);
+
+ $prod = $this->createMock(originalClassName: IGroup::class);
+ $prod->method('getUsers')->willReturn([$bob, $carol]);
+
+ $this->groupManager->method('get')
+ ->willReturnCallback(
+ callback: static function (string $gid) use ($mgmt, $prod) {
+ if ($gid === 'management') {
+ return $mgmt;
+ }
+
+ if ($gid === 'product') {
+ return $prod;
+ }
+
+ return null;
+ }
+ );
+
+ // Group sort path consults getUserGroupIds; default sort doesn't.
+ $this->groupManager->method('getUserGroupIds')->willReturn([]);
+ $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
+
+ $result = $this->service->listUsers(
+ filters: [
+ [
+ 'fieldName' => 'group',
+ 'operator' => 'in',
+ 'values' => ['management', 'product'],
+ ],
+ ],
+ );
+
+ // Bob appears once across both groups (dedup).
+ $uids = array_map(
+ callback: static fn (array $u): string => $u['uid'],
+ array: $result['users']
+ );
+ $this->assertSame(expected: ['alice', 'bob', 'carol'], actual: $uids);
+ $this->assertSame(expected: 3, actual: $result['total']);
+ }//end testGroupFilterUnionDeduplicates()
+
+ /**
+ * @return void
+ */
+ public function testUnknownGroupYieldsZeroUsersWithoutError(): void {
+ $this->groupManager->method('get')->willReturn(null);
+ $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
+
+ $result = $this->service->listUsers(
+ filters: [
+ [
+ 'fieldName' => 'group',
+ 'operator' => 'in',
+ 'values' => ['nonexistent'],
+ ],
+ ],
+ );
+
+ $this->assertSame(expected: 0, actual: $result['total']);
+ $this->assertSame(expected: [], actual: $result['users']);
+ $this->assertFalse(condition: $result['hasMore']);
+ }//end testUnknownGroupYieldsZeroUsersWithoutError()
+
+ // ---------------------------------------------------------------
+ // listUsers — account-field projection (REQ-PPL-005)
+ // ---------------------------------------------------------------
+
+ /**
+ * @return void
+ */
+ public function testBirthdateIsNormalisedToIso(): void {
+ $alice = $this->makeUser(uid: 'alice', display: 'Alice');
+ $this->wireDirectory(orderedUsers: [$alice]);
+ $this->groupManager->method('getUserGroupIds')->willReturn([]);
+
+ $account = $this->makeAccount(
+ properties: [
+ IAccountManager::PROPERTY_BIRTHDATE => '10-06-1990',
+ IAccountManager::PROPERTY_ROLE => 'PM',
+ ]
+ );
+ $this->accountManager->method('getAccount')->willReturn($account);
+
+ $result = $this->service->listUsers();
+
+ $this->assertSame(
+ expected: '1990-06-10',
+ actual: $result['users'][0]['birthdate']
+ );
+ $this->assertSame(expected: 'PM', actual: $result['users'][0]['role']);
+ }//end testBirthdateIsNormalisedToIso()
+
+ /**
+ * @return void
+ */
+ public function testShowBirthdaysFalseStripsBirthdate(): void {
+ $alice = $this->makeUser(uid: 'alice', display: 'Alice');
+ $this->wireDirectory(orderedUsers: [$alice]);
+ $this->groupManager->method('getUserGroupIds')->willReturn([]);
+
+ $account = $this->makeAccount(
+ properties: [IAccountManager::PROPERTY_BIRTHDATE => '1990-06-10']
+ );
+ $this->accountManager->method('getAccount')->willReturn($account);
+
+ $result = $this->service->listUsers(showBirthdays: false);
+
+ $this->assertArrayNotHasKey(
+ key: 'birthdate',
+ array: $result['users'][0]
+ );
+ }//end testShowBirthdaysFalseStripsBirthdate()
+
+ // ---------------------------------------------------------------
+ // listUsers — bounded directory scan (fix-people-widget-unbounded-user-scan)
+ // ---------------------------------------------------------------
+
+ /**
+ * With no `group` filter and the default `displayName` sort, the
+ * service MUST page directly from the backend via a bounded
+ * `searchDisplayName($pattern, $limit, $offset)` call and MUST NOT
+ * fall back to the unbounded `search('')` full-directory scan.
+ *
+ * @return void
+ */
+ public function testDisplayNameSortUsesBoundedSearchNotFullScan(): void {
+ $alice = $this->makeUser(uid: 'alice', display: 'Alice');
+ $bob = $this->makeUser(uid: 'bob', display: 'Bob');
+
+ // The unbounded scan MUST NOT be used for this path.
+ $this->userManager->expects($this->never())->method('search');
+
+ $captured = [];
+ $this->userManager->expects($this->atLeastOnce())
+ ->method('searchDisplayName')
+ ->willReturnCallback(
+ function (string $pattern, ?int $limit = null, ?int $offset = null) use (&$captured, $alice, $bob): array {
+ $captured[] = ['pattern' => $pattern, 'limit' => $limit, 'offset' => $offset];
+ return array_slice([$alice, $bob], (int)$offset, ($limit ?? 2));
+ }
+ );
+ $this->userManager->method('countUsersTotal')->willReturn(2);
+ $this->userManager->method('countDisabledUsers')->willReturn(0);
+ $this->groupManager->method('getUserGroupIds')->willReturn([]);
+ $this->accountManager->method('getAccount')->willReturn($this->emptyAccount());
+
+ $result = $this->service->listUsers(limit: 10, offset: 0);
+
+ // The backend was asked for a bounded, non-null limit.
+ $this->assertNotEmpty($captured);
+ $this->assertNotNull($captured[0]['limit']);
+ $this->assertGreaterThanOrEqual(10, $captured[0]['limit']);
+ $this->assertSame(0, $captured[0]['offset']);
+ $this->assertSame('', $captured[0]['pattern']);
+
+ // Envelope semantics unchanged from the caller's point of view.
+ $this->assertSame(2, $result['total']);
+ $this->assertFalse($result['hasMore']);
+ $this->assertSame(['alice', 'bob'], array_column($result['users'], 'uid'));
+ }//end testDisplayNameSortUsesBoundedSearchNotFullScan()
+
+ // ---------------------------------------------------------------
+ // Helpers
+ // ---------------------------------------------------------------
+
+ /**
+ * Wire the user-directory backend for a no-group-filter,
+ * display-name-sorted listing: a bounded `searchDisplayName` that
+ * honours the streamed `limit`/`offset` window plus the
+ * `countUsersTotal`/`countDisabledUsers` counters the bounded path
+ * uses to size `total` without a full scan.
+ *
+ * @param IUser[] $orderedUsers Users in display-name order (enabled
+ * and disabled). `countUsersTotal`
+ * reports the full length.
+ * @param int $disabledCount Number of disabled users in the set.
+ *
+ * @return void
+ */
+ private function wireDirectory(array $orderedUsers, int $disabledCount = 0): void {
+ $this->userManager->method('searchDisplayName')
+ ->willReturnCallback(
+ static function (string $pattern, ?int $limit = null, ?int $offset = null) use ($orderedUsers): array {
+ return array_slice(
+ $orderedUsers,
+ (int)$offset,
+ ($limit ?? count($orderedUsers))
+ );
+ }
+ );
+ $this->userManager->method('countUsersTotal')->willReturn(count($orderedUsers));
+ $this->userManager->method('countDisabledUsers')->willReturn($disabledCount);
+ }//end wireDirectory()
+
+ /**
+ * @param string $uid The user id.
+ * @param string $display Display name.
+ * @param string $email Email or empty string.
+ * @param bool $enabled Whether the user is enabled.
+ *
+ * @return IUser&MockObject
+ */
+ private function makeUser(
+ string $uid,
+ string $display,
+ string $email = '',
+ bool $enabled = true,
+ ): IUser {
+ $user = $this->createMock(originalClassName: IUser::class);
+ $user->method('getUID')->willReturn($uid);
+ $user->method('getDisplayName')->willReturn($display);
+ $user->method('getEMailAddress')->willReturn($email === '' ? null : $email);
+ $user->method('isEnabled')->willReturn($enabled);
+ return $user;
+ }//end makeUser()
+
+ /**
+ * Build an account whose every property returns the empty string —
+ * matches the "no profile fields set" baseline.
+ *
+ * @return IAccount&MockObject
+ */
+ private function emptyAccount(): IAccount {
+ return $this->makeAccount(properties: []);
+ }//end emptyAccount()
+
+ /**
+ * @param array $properties Map of property name → value.
+ * Properties absent from the map
+ * resolve to the empty string.
+ *
+ * @return IAccount&MockObject
+ */
+ private function makeAccount(array $properties): IAccount {
+ $account = $this->createMock(originalClassName: IAccount::class);
+ $account->method('getProperty')
+ ->willReturnCallback(
+ callback: function (string $name) use ($properties): IAccountProperty {
+ $prop = $this->createMock(originalClassName: IAccountProperty::class);
+ $prop->method('getValue')->willReturn($properties[$name] ?? '');
+ $prop->method('getName')->willReturn($name);
+ return $prop;
+ }
+ );
+
+ return $account;
+ }//end makeAccount()
}//end class
diff --git a/tests/Unit/Service/PlacementServiceQuotaWiringTest.php b/tests/Unit/Service/PlacementServiceQuotaWiringTest.php
index a8d6bcb0..51ae0aaf 100644
--- a/tests/Unit/Service/PlacementServiceQuotaWiringTest.php
+++ b/tests/Unit/Service/PlacementServiceQuotaWiringTest.php
@@ -34,89 +34,83 @@
use PHPUnit\Framework\MockObject\MockObject;
use PHPUnit\Framework\TestCase;
-class PlacementServiceQuotaWiringTest extends TestCase
-{
-
- /** @var WidgetPlacementMapper&MockObject */
- private $placementMapper;
-
- /** @var AdminSettingMapper&MockObject */
- private $settingMapper;
-
- private PlacementService $service;
-
- protected function setUp(): void
- {
- parent::setUp();
-
- $this->placementMapper = $this->createMock(WidgetPlacementMapper::class);
- $this->settingMapper = $this->createMock(AdminSettingMapper::class);
- /** @var DashboardMapper&MockObject $dashboardMapper */
- $dashboardMapper = $this->createMock(DashboardMapper::class);
-
- $quotaService = new QuotaService(
- settingMapper: $this->settingMapper,
- dashboardMapper: $dashboardMapper,
- placementMapper: $this->placementMapper,
- );
-
- $this->service = new PlacementService(
- placementMapper: $this->placementMapper,
- tileUpdater: $this->createMock(TileUpdater::class),
- placementUpdater: $this->createMock(PlacementUpdater::class),
- publicShareContext: null,
- quotaService: $quotaService,
- );
- }//end setUp()
-
- /**
- * Wire the widget quota to `$limit`.
- *
- * @param int $limit The per-dashboard widget quota.
- *
- * @return void
- */
- private function withWidgetLimit(int $limit): void
- {
- $this->settingMapper->method('getValue')->willReturnCallback(
- function (string $k, $default=null) use ($limit) {
- if ($k === AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD) {
- return $limit;
- }
-
- return $default;
- }
- );
- }//end withWidgetLimit()
-
- public function testAddWidgetThrowsAtQuota(): void
- {
- $this->withWidgetLimit(40);
- $this->placementMapper->method('countByDashboardId')->willReturn(40);
- $this->placementMapper->expects($this->never())->method('insert');
-
- $this->expectException(QuotaExceededException::class);
- $this->service->addWidget(dashboardId: 7, widgetId: 'clock');
- }//end testAddWidgetThrowsAtQuota()
-
- public function testAddTileThrowsAtQuota(): void
- {
- $this->withWidgetLimit(40);
- $this->placementMapper->method('countByDashboardId')->willReturn(40);
- $this->placementMapper->expects($this->never())->method('insert');
-
- $this->expectException(QuotaExceededException::class);
- $this->service->addTileFromArray(dashboardId: 7, tileData: ['title' => 'X']);
- }//end testAddTileThrowsAtQuota()
-
- public function testAddWidgetAllowedBelowQuota(): void
- {
- $this->withWidgetLimit(40);
- $this->placementMapper->method('countByDashboardId')->willReturn(39);
- $this->placementMapper->expects($this->once())
- ->method('insert')
- ->willReturnArgument(0);
-
- $this->service->addWidget(dashboardId: 7, widgetId: 'clock');
- }//end testAddWidgetAllowedBelowQuota()
+class PlacementServiceQuotaWiringTest extends TestCase {
+
+ /** @var WidgetPlacementMapper&MockObject */
+ private $placementMapper;
+
+ /** @var AdminSettingMapper&MockObject */
+ private $settingMapper;
+
+ private PlacementService $service;
+
+ protected function setUp(): void {
+ parent::setUp();
+
+ $this->placementMapper = $this->createMock(WidgetPlacementMapper::class);
+ $this->settingMapper = $this->createMock(AdminSettingMapper::class);
+ /** @var DashboardMapper&MockObject $dashboardMapper */
+ $dashboardMapper = $this->createMock(DashboardMapper::class);
+
+ $quotaService = new QuotaService(
+ settingMapper: $this->settingMapper,
+ dashboardMapper: $dashboardMapper,
+ placementMapper: $this->placementMapper,
+ );
+
+ $this->service = new PlacementService(
+ placementMapper: $this->placementMapper,
+ tileUpdater: $this->createMock(TileUpdater::class),
+ placementUpdater: $this->createMock(PlacementUpdater::class),
+ publicShareContext: null,
+ quotaService: $quotaService,
+ );
+ }//end setUp()
+
+ /**
+ * Wire the widget quota to `$limit`.
+ *
+ * @param int $limit The per-dashboard widget quota.
+ *
+ * @return void
+ */
+ private function withWidgetLimit(int $limit): void {
+ $this->settingMapper->method('getValue')->willReturnCallback(
+ function (string $k, $default = null) use ($limit) {
+ if ($k === AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD) {
+ return $limit;
+ }
+
+ return $default;
+ }
+ );
+ }//end withWidgetLimit()
+
+ public function testAddWidgetThrowsAtQuota(): void {
+ $this->withWidgetLimit(40);
+ $this->placementMapper->method('countByDashboardId')->willReturn(40);
+ $this->placementMapper->expects($this->never())->method('insert');
+
+ $this->expectException(QuotaExceededException::class);
+ $this->service->addWidget(dashboardId: 7, widgetId: 'clock');
+ }//end testAddWidgetThrowsAtQuota()
+
+ public function testAddTileThrowsAtQuota(): void {
+ $this->withWidgetLimit(40);
+ $this->placementMapper->method('countByDashboardId')->willReturn(40);
+ $this->placementMapper->expects($this->never())->method('insert');
+
+ $this->expectException(QuotaExceededException::class);
+ $this->service->addTileFromArray(dashboardId: 7, tileData: ['title' => 'X']);
+ }//end testAddTileThrowsAtQuota()
+
+ public function testAddWidgetAllowedBelowQuota(): void {
+ $this->withWidgetLimit(40);
+ $this->placementMapper->method('countByDashboardId')->willReturn(39);
+ $this->placementMapper->expects($this->once())
+ ->method('insert')
+ ->willReturnArgument(0);
+
+ $this->service->addWidget(dashboardId: 7, widgetId: 'clock');
+ }//end testAddWidgetAllowedBelowQuota()
}//end class
diff --git a/tests/Unit/Service/PublicShareContextTest.php b/tests/Unit/Service/PublicShareContextTest.php
index c34e61a4..59bbfeb0 100644
--- a/tests/Unit/Service/PublicShareContextTest.php
+++ b/tests/Unit/Service/PublicShareContextTest.php
@@ -27,41 +27,32 @@
use OCA\LaunchPad\Service\PublicShareContext;
use PHPUnit\Framework\TestCase;
-class PublicShareContextTest extends TestCase
-{
-
-
- public function testDefaultsToNonBearer(): void
- {
- $ctx = new PublicShareContext();
- $this->assertFalse($ctx->isBearer());
- $this->assertNull($ctx->getToken());
- }//end testDefaultsToNonBearer()
-
-
- public function testRequireMutablePassesByDefault(): void
- {
- $ctx = new PublicShareContext();
- $ctx->requireMutable();
- // No exception — control reaches here.
- $this->assertTrue(true);
- }//end testRequireMutablePassesByDefault()
-
-
- public function testMarkBearerFlipsFlagAndStoresToken(): void
- {
- $ctx = new PublicShareContext();
- $ctx->markBearer(token: 'tok_abc123');
- $this->assertTrue($ctx->isBearer());
- $this->assertSame('tok_abc123', $ctx->getToken());
- }//end testMarkBearerFlipsFlagAndStoresToken()
-
-
- public function testRequireMutableThrowsAfterMarkBearer(): void
- {
- $ctx = new PublicShareContext();
- $ctx->markBearer(token: 'tok_xyz');
- $this->expectException(ShareReadOnlyException::class);
- $ctx->requireMutable();
- }//end testRequireMutableThrowsAfterMarkBearer()
+class PublicShareContextTest extends TestCase {
+
+ public function testDefaultsToNonBearer(): void {
+ $ctx = new PublicShareContext();
+ $this->assertFalse($ctx->isBearer());
+ $this->assertNull($ctx->getToken());
+ }//end testDefaultsToNonBearer()
+
+ public function testRequireMutablePassesByDefault(): void {
+ $ctx = new PublicShareContext();
+ $ctx->requireMutable();
+ // No exception — control reaches here.
+ $this->assertTrue(true);
+ }//end testRequireMutablePassesByDefault()
+
+ public function testMarkBearerFlipsFlagAndStoresToken(): void {
+ $ctx = new PublicShareContext();
+ $ctx->markBearer(token: 'tok_abc123');
+ $this->assertTrue($ctx->isBearer());
+ $this->assertSame('tok_abc123', $ctx->getToken());
+ }//end testMarkBearerFlipsFlagAndStoresToken()
+
+ public function testRequireMutableThrowsAfterMarkBearer(): void {
+ $ctx = new PublicShareContext();
+ $ctx->markBearer(token: 'tok_xyz');
+ $this->expectException(ShareReadOnlyException::class);
+ $ctx->requireMutable();
+ }//end testRequireMutableThrowsAfterMarkBearer()
}//end class
diff --git a/tests/Unit/Service/PublicShareServiceTest.php b/tests/Unit/Service/PublicShareServiceTest.php
index ea8f2180..7a535bda 100644
--- a/tests/Unit/Service/PublicShareServiceTest.php
+++ b/tests/Unit/Service/PublicShareServiceTest.php
@@ -40,275 +40,262 @@
use PHPUnit\Framework\TestCase;
use Psr\Log\LoggerInterface;
-class PublicShareServiceTest extends TestCase
-{
-
- /** @var PublicShareMapper&MockObject */
- private $shareMapper;
-
- /** @var DashboardMapper&MockObject */
- private $dashMapper;
-
- /** @var IGroupManager&MockObject */
- private $groupManager;
-
- /** @var IHasher&MockObject */
- private $hasher;
-
- /** @var ISecureRandom&MockObject */
- private $secureRandom;
-
- /** @var IThrottler&MockObject */
- private $throttler;
-
- /** @var LoggerInterface&MockObject */
- private $logger;
-
- /** @var WidgetPlacementMapper&MockObject */
- private $placementMapper;
-
- private PublicShareService $service;
-
- protected function setUp(): void
- {
- $this->shareMapper = $this->createMock(PublicShareMapper::class);
- $this->dashMapper = $this->createMock(DashboardMapper::class);
- $this->groupManager = $this->createMock(IGroupManager::class);
- $this->hasher = $this->createMock(IHasher::class);
- $this->secureRandom = $this->createMock(ISecureRandom::class);
- $this->throttler = $this->createMock(IThrottler::class);
- $this->logger = $this->createMock(LoggerInterface::class);
- $this->placementMapper = $this->createMock(WidgetPlacementMapper::class);
-
- $this->service = new PublicShareService(
- shareMapper: $this->shareMapper,
- dashMapper: $this->dashMapper,
- groupManager: $this->groupManager,
- hasher: $this->hasher,
- secureRandom: $this->secureRandom,
- throttler: $this->throttler,
- logger: $this->logger,
- placementMapper: $this->placementMapper,
- );
- }
-
- // -------------------------------------------------------------------------
- // createPublicShare
- // -------------------------------------------------------------------------
-
- public function testCreateShareOwnerCanCreate(): void
- {
- $dashboard = new Dashboard();
- $dashboard->setUserId('alice');
-
- $this->dashMapper->method('findByUuid')->willReturn($dashboard);
- $this->groupManager->method('isAdmin')->willReturn(false);
- $this->secureRandom->method('generate')->willReturn(str_repeat('a', 64));
-
- $saved = new PublicShare();
- $saved->setToken(str_repeat('a', 64));
- $this->shareMapper->method('insert')->willReturn($saved);
-
- $result = $this->service->createPublicShare(
- dashboardUuid: 'some-uuid',
- callerId: 'alice'
- );
-
- $this->assertInstanceOf(PublicShare::class, $result);
- }
-
- public function testCreateShareNonOwnerThrowsForbidden(): void
- {
- $dashboard = new Dashboard();
- $dashboard->setUserId('alice');
-
- $this->dashMapper->method('findByUuid')->willReturn($dashboard);
- $this->groupManager->method('isAdmin')->willReturn(false);
-
- $this->expectException(OCSForbiddenException::class);
-
- $this->service->createPublicShare(
- dashboardUuid: 'some-uuid',
- callerId: 'bob'
- );
- }
-
- public function testCreateShareAdminCanCreate(): void
- {
- $dashboard = new Dashboard();
- $dashboard->setUserId('alice');
-
- $this->dashMapper->method('findByUuid')->willReturn($dashboard);
- $this->groupManager->method('isAdmin')->willReturn(true);
- $this->secureRandom->method('generate')->willReturn(str_repeat('x', 64));
-
- $saved = new PublicShare();
- $saved->setToken(str_repeat('x', 64));
- $this->shareMapper->method('insert')->willReturn($saved);
-
- $result = $this->service->createPublicShare(
- dashboardUuid: 'some-uuid',
- callerId: 'admin'
- );
-
- $this->assertInstanceOf(PublicShare::class, $result);
- }
-
- public function testCreateShareHashesPassword(): void
- {
- $dashboard = new Dashboard();
- $dashboard->setUserId('alice');
-
- $this->dashMapper->method('findByUuid')->willReturn($dashboard);
- $this->groupManager->method('isAdmin')->willReturn(false);
- $this->secureRandom->method('generate')->willReturn(str_repeat('t', 64));
-
- $this->hasher
- ->expects($this->once())
- ->method('hash')
- ->with('SecurePass123!')
- ->willReturn('$2y$hashed');
-
- $saved = new PublicShare();
- $saved->setPasswordHash('$2y$hashed');
- $this->shareMapper->method('insert')->willReturn($saved);
-
- $this->service->createPublicShare(
- dashboardUuid: 'some-uuid',
- callerId: 'alice',
- password: 'SecurePass123!'
- );
- }
-
- // -------------------------------------------------------------------------
- // renderShareContent
- // -------------------------------------------------------------------------
-
- public function testRenderInvalidTokenThrowsNotFound(): void
- {
- $this->shareMapper
- ->method('findByToken')
- ->willThrowException(new DoesNotExistException('not found'));
-
- $this->expectException(ShareNotFoundException::class);
-
- $this->service->renderShareContent(token: 'invalid', ipAddress: '127.0.0.1');
- }
-
- public function testRenderRevokedShareThrowsNotFound(): void
- {
- $share = new PublicShare();
- $share->setToken('tok');
- $share->setRevokedAt('2026-01-01 00:00:00');
-
- $this->shareMapper->method('findByToken')->willReturn($share);
-
- $this->expectException(ShareNotFoundException::class);
-
- $this->service->renderShareContent(token: 'tok', ipAddress: '127.0.0.1');
- }
-
- public function testRenderExpiredShareThrowsNotFound(): void
- {
- $share = new PublicShare();
- $share->setToken('tok');
- $share->setRevokedAt(null);
- // Past date.
- $share->setExpiresAt('2020-01-01 00:00:00');
-
- $this->shareMapper->method('findByToken')->willReturn($share);
-
- $this->expectException(ShareNotFoundException::class);
-
- $this->service->renderShareContent(token: 'tok', ipAddress: '127.0.0.1');
- }
-
- public function testRenderPasswordProtectedWithoutPasswordThrowsRequired(): void
- {
- $share = new PublicShare();
- $share->setToken('tok');
- $share->setRevokedAt(null);
- $share->setExpiresAt(null);
- $share->setPasswordHash('$2y$hash');
- $share->setDashboardUuid('some-uuid');
-
- $this->shareMapper->method('findByToken')->willReturn($share);
-
- $this->expectException(SharePasswordRequiredException::class);
-
- $this->service->renderShareContent(token: 'tok', ipAddress: '127.0.0.1');
- }
-
- public function testRenderValidTokenWithoutPasswordSucceeds(): void
- {
- $share = new PublicShare();
- $share->setToken('tok');
- $share->setRevokedAt(null);
- $share->setExpiresAt(null);
- $share->setPasswordHash(null);
- $share->setDashboardUuid('some-uuid');
-
- $this->shareMapper->method('findByToken')->willReturn($share);
- $this->shareMapper->method('incrementViewCount');
-
- $dashboard = new Dashboard();
- $dashboard->setUserId('alice');
- $this->dashMapper->method('findByUuid')->willReturn($dashboard);
- $this->placementMapper->method('findByDashboardId')->willReturn([]);
-
- $result = $this->service->renderShareContent(token: 'tok', ipAddress: '127.0.0.1');
-
- $this->assertArrayHasKey('share', $result);
- $this->assertArrayHasKey('dashboard', $result);
- $this->assertArrayHasKey('placements', $result);
- }
-
- // -------------------------------------------------------------------------
- // unlockShare
- // -------------------------------------------------------------------------
-
- public function testUnlockCorrectPasswordReturnsTrue(): void
- {
- $share = new PublicShare();
- $share->setToken('tok');
- $share->setRevokedAt(null);
- $share->setExpiresAt(null);
- $share->setPasswordHash('$2y$hash');
-
- $this->shareMapper->method('findByToken')->willReturn($share);
- $this->hasher->method('verify')->willReturn(true);
-
- $result = $this->service->unlockShare(
- token: 'tok',
- password: 'SecurePass123!',
- ipAddress: '127.0.0.1'
- );
-
- $this->assertTrue($result);
- }
-
- public function testUnlockWrongPasswordReturnsFalseAndRegistersAttempt(): void
- {
- $share = new PublicShare();
- $share->setToken('tok');
- $share->setRevokedAt(null);
- $share->setExpiresAt(null);
- $share->setPasswordHash('$2y$hash');
-
- $this->shareMapper->method('findByToken')->willReturn($share);
- $this->hasher->method('verify')->willReturn(false);
-
- $this->throttler
- ->expects($this->once())
- ->method('registerAttempt')
- ->with(PublicShareService::ACTION_SHARE_PASSWORD, '127.0.0.1');
-
- $result = $this->service->unlockShare(
- token: 'tok',
- password: 'WrongPassword',
- ipAddress: '127.0.0.1'
- );
-
- $this->assertFalse($result);
- }
+class PublicShareServiceTest extends TestCase {
+
+ /** @var PublicShareMapper&MockObject */
+ private $shareMapper;
+
+ /** @var DashboardMapper&MockObject */
+ private $dashMapper;
+
+ /** @var IGroupManager&MockObject */
+ private $groupManager;
+
+ /** @var IHasher&MockObject */
+ private $hasher;
+
+ /** @var ISecureRandom&MockObject */
+ private $secureRandom;
+
+ /** @var IThrottler&MockObject */
+ private $throttler;
+
+ /** @var LoggerInterface&MockObject */
+ private $logger;
+
+ /** @var WidgetPlacementMapper&MockObject */
+ private $placementMapper;
+
+ private PublicShareService $service;
+
+ protected function setUp(): void {
+ $this->shareMapper = $this->createMock(PublicShareMapper::class);
+ $this->dashMapper = $this->createMock(DashboardMapper::class);
+ $this->groupManager = $this->createMock(IGroupManager::class);
+ $this->hasher = $this->createMock(IHasher::class);
+ $this->secureRandom = $this->createMock(ISecureRandom::class);
+ $this->throttler = $this->createMock(IThrottler::class);
+ $this->logger = $this->createMock(LoggerInterface::class);
+ $this->placementMapper = $this->createMock(WidgetPlacementMapper::class);
+
+ $this->service = new PublicShareService(
+ shareMapper: $this->shareMapper,
+ dashMapper: $this->dashMapper,
+ groupManager: $this->groupManager,
+ hasher: $this->hasher,
+ secureRandom: $this->secureRandom,
+ throttler: $this->throttler,
+ logger: $this->logger,
+ placementMapper: $this->placementMapper,
+ );
+ }
+
+ // -------------------------------------------------------------------------
+ // createPublicShare
+ // -------------------------------------------------------------------------
+
+ public function testCreateShareOwnerCanCreate(): void {
+ $dashboard = new Dashboard();
+ $dashboard->setUserId('alice');
+
+ $this->dashMapper->method('findByUuid')->willReturn($dashboard);
+ $this->groupManager->method('isAdmin')->willReturn(false);
+ $this->secureRandom->method('generate')->willReturn(str_repeat('a', 64));
+
+ $saved = new PublicShare();
+ $saved->setToken(str_repeat('a', 64));
+ $this->shareMapper->method('insert')->willReturn($saved);
+
+ $result = $this->service->createPublicShare(
+ dashboardUuid: 'some-uuid',
+ callerId: 'alice'
+ );
+
+ $this->assertInstanceOf(PublicShare::class, $result);
+ }
+
+ public function testCreateShareNonOwnerThrowsForbidden(): void {
+ $dashboard = new Dashboard();
+ $dashboard->setUserId('alice');
+
+ $this->dashMapper->method('findByUuid')->willReturn($dashboard);
+ $this->groupManager->method('isAdmin')->willReturn(false);
+
+ $this->expectException(OCSForbiddenException::class);
+
+ $this->service->createPublicShare(
+ dashboardUuid: 'some-uuid',
+ callerId: 'bob'
+ );
+ }
+
+ public function testCreateShareAdminCanCreate(): void {
+ $dashboard = new Dashboard();
+ $dashboard->setUserId('alice');
+
+ $this->dashMapper->method('findByUuid')->willReturn($dashboard);
+ $this->groupManager->method('isAdmin')->willReturn(true);
+ $this->secureRandom->method('generate')->willReturn(str_repeat('x', 64));
+
+ $saved = new PublicShare();
+ $saved->setToken(str_repeat('x', 64));
+ $this->shareMapper->method('insert')->willReturn($saved);
+
+ $result = $this->service->createPublicShare(
+ dashboardUuid: 'some-uuid',
+ callerId: 'admin'
+ );
+
+ $this->assertInstanceOf(PublicShare::class, $result);
+ }
+
+ public function testCreateShareHashesPassword(): void {
+ $dashboard = new Dashboard();
+ $dashboard->setUserId('alice');
+
+ $this->dashMapper->method('findByUuid')->willReturn($dashboard);
+ $this->groupManager->method('isAdmin')->willReturn(false);
+ $this->secureRandom->method('generate')->willReturn(str_repeat('t', 64));
+
+ $this->hasher
+ ->expects($this->once())
+ ->method('hash')
+ ->with('SecurePass123!')
+ ->willReturn('$2y$hashed');
+
+ $saved = new PublicShare();
+ $saved->setPasswordHash('$2y$hashed');
+ $this->shareMapper->method('insert')->willReturn($saved);
+
+ $this->service->createPublicShare(
+ dashboardUuid: 'some-uuid',
+ callerId: 'alice',
+ password: 'SecurePass123!'
+ );
+ }
+
+ // -------------------------------------------------------------------------
+ // renderShareContent
+ // -------------------------------------------------------------------------
+
+ public function testRenderInvalidTokenThrowsNotFound(): void {
+ $this->shareMapper
+ ->method('findByToken')
+ ->willThrowException(new DoesNotExistException('not found'));
+
+ $this->expectException(ShareNotFoundException::class);
+
+ $this->service->renderShareContent(token: 'invalid', ipAddress: '127.0.0.1');
+ }
+
+ public function testRenderRevokedShareThrowsNotFound(): void {
+ $share = new PublicShare();
+ $share->setToken('tok');
+ $share->setRevokedAt('2026-01-01 00:00:00');
+
+ $this->shareMapper->method('findByToken')->willReturn($share);
+
+ $this->expectException(ShareNotFoundException::class);
+
+ $this->service->renderShareContent(token: 'tok', ipAddress: '127.0.0.1');
+ }
+
+ public function testRenderExpiredShareThrowsNotFound(): void {
+ $share = new PublicShare();
+ $share->setToken('tok');
+ $share->setRevokedAt(null);
+ // Past date.
+ $share->setExpiresAt('2020-01-01 00:00:00');
+
+ $this->shareMapper->method('findByToken')->willReturn($share);
+
+ $this->expectException(ShareNotFoundException::class);
+
+ $this->service->renderShareContent(token: 'tok', ipAddress: '127.0.0.1');
+ }
+
+ public function testRenderPasswordProtectedWithoutPasswordThrowsRequired(): void {
+ $share = new PublicShare();
+ $share->setToken('tok');
+ $share->setRevokedAt(null);
+ $share->setExpiresAt(null);
+ $share->setPasswordHash('$2y$hash');
+ $share->setDashboardUuid('some-uuid');
+
+ $this->shareMapper->method('findByToken')->willReturn($share);
+
+ $this->expectException(SharePasswordRequiredException::class);
+
+ $this->service->renderShareContent(token: 'tok', ipAddress: '127.0.0.1');
+ }
+
+ public function testRenderValidTokenWithoutPasswordSucceeds(): void {
+ $share = new PublicShare();
+ $share->setToken('tok');
+ $share->setRevokedAt(null);
+ $share->setExpiresAt(null);
+ $share->setPasswordHash(null);
+ $share->setDashboardUuid('some-uuid');
+
+ $this->shareMapper->method('findByToken')->willReturn($share);
+ $this->shareMapper->method('incrementViewCount');
+
+ $dashboard = new Dashboard();
+ $dashboard->setUserId('alice');
+ $this->dashMapper->method('findByUuid')->willReturn($dashboard);
+ $this->placementMapper->method('findByDashboardId')->willReturn([]);
+
+ $result = $this->service->renderShareContent(token: 'tok', ipAddress: '127.0.0.1');
+
+ $this->assertArrayHasKey('share', $result);
+ $this->assertArrayHasKey('dashboard', $result);
+ $this->assertArrayHasKey('placements', $result);
+ }
+
+ // -------------------------------------------------------------------------
+ // unlockShare
+ // -------------------------------------------------------------------------
+
+ public function testUnlockCorrectPasswordReturnsTrue(): void {
+ $share = new PublicShare();
+ $share->setToken('tok');
+ $share->setRevokedAt(null);
+ $share->setExpiresAt(null);
+ $share->setPasswordHash('$2y$hash');
+
+ $this->shareMapper->method('findByToken')->willReturn($share);
+ $this->hasher->method('verify')->willReturn(true);
+
+ $result = $this->service->unlockShare(
+ token: 'tok',
+ password: 'SecurePass123!',
+ ipAddress: '127.0.0.1'
+ );
+
+ $this->assertTrue($result);
+ }
+
+ public function testUnlockWrongPasswordReturnsFalseAndRegistersAttempt(): void {
+ $share = new PublicShare();
+ $share->setToken('tok');
+ $share->setRevokedAt(null);
+ $share->setExpiresAt(null);
+ $share->setPasswordHash('$2y$hash');
+
+ $this->shareMapper->method('findByToken')->willReturn($share);
+ $this->hasher->method('verify')->willReturn(false);
+
+ $this->throttler
+ ->expects($this->once())
+ ->method('registerAttempt')
+ ->with(PublicShareService::ACTION_SHARE_PASSWORD, '127.0.0.1');
+
+ $result = $this->service->unlockShare(
+ token: 'tok',
+ password: 'WrongPassword',
+ ipAddress: '127.0.0.1'
+ );
+
+ $this->assertFalse($result);
+ }
}//end class
diff --git a/tests/Unit/Service/QuotaServiceTest.php b/tests/Unit/Service/QuotaServiceTest.php
index 8fbef0f1..12a4f93e 100644
--- a/tests/Unit/Service/QuotaServiceTest.php
+++ b/tests/Unit/Service/QuotaServiceTest.php
@@ -27,314 +27,295 @@
use OCA\LaunchPad\Service\QuotaService;
use PHPUnit\Framework\TestCase;
-class QuotaServiceTest extends TestCase
-{
-
- private QuotaService $service;
-
- private AdminSettingMapper $settingMapper;
-
- private DashboardMapper $dashboardMapper;
-
- private WidgetPlacementMapper $placementMapper;
-
- protected function setUp(): void
- {
- $this->settingMapper = $this->createMock(AdminSettingMapper::class);
- $this->dashboardMapper = $this->createMock(DashboardMapper::class);
- $this->placementMapper = $this->createMock(WidgetPlacementMapper::class);
- $this->service = new QuotaService(
- settingMapper: $this->settingMapper,
- dashboardMapper: $this->dashboardMapper,
- placementMapper: $this->placementMapper,
- );
- }//end setUp()
-
- /**
- * Wire the setting mapper's getValue() for a given numeric quota +
- * allow-multiple flag.
- *
- * @param string $key The numeric quota key.
- * @param int $value The numeric quota value.
- * @param bool $allowMultiple The allow_multiple_dashboards flag.
- *
- * @return void
- */
- private function withSettings(string $key, int $value, bool $allowMultiple=true): void
- {
- $this->settingMapper->method('getValue')->willReturnCallback(
- function (string $k, $default=null) use ($key, $value, $allowMultiple) {
- if ($k === $key) {
- return $value;
- }
-
- if ($k === AdminSetting::KEY_ALLOW_MULTIPLE_DASHBOARDS) {
- return $allowMultiple;
- }
-
- return $default;
- }
- );
- }//end withSettings()
-
- // ----- REQ-QUOTA-002: dashboard count enforcement -----
-
- public function testDashboardCreateAllowedBelowLimit(): void
- {
- $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
- $this->dashboardMapper->method('countPersonalByUserId')->willReturn(4);
-
- // No exception => allowed.
- $this->service->assertCanCreateDashboard(userId: 'alice');
- $this->addToAssertionCount(1);
- }//end testDashboardCreateAllowedBelowLimit()
-
- public function testDashboardCreateBlockedAtLimit(): void
- {
- $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
- $this->dashboardMapper->method('countPersonalByUserId')->willReturn(5);
-
- try {
- $this->service->assertCanCreateDashboard(userId: 'alice');
- $this->fail('Expected QuotaExceededException');
- } catch (QuotaExceededException $e) {
- $this->assertSame(QuotaExceededException::QUOTA_DASHBOARDS, $e->getQuota());
- $this->assertSame(5, $e->getLimit());
- $this->assertSame(5, $e->getCurrent());
- $this->assertSame(409, $e->getHttpStatus());
- $this->assertSame(
- [
- 'error' => 'quota_exceeded',
- 'quota' => 'dashboards',
- 'limit' => 5,
- 'current' => 5,
- ],
- $e->toResponseBody()
- );
- }//end try
- }//end testDashboardCreateBlockedAtLimit()
-
- public function testDashboardCreateUnlimitedWhenZero(): void
- {
- // REQ-QUOTA-001 — 0 means unlimited; count never queried.
- $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 0);
- $this->dashboardMapper->expects($this->never())
- ->method('countPersonalByUserId');
-
- $this->service->assertCanCreateDashboard(userId: 'alice');
- $this->addToAssertionCount(1);
- }//end testDashboardCreateUnlimitedWhenZero()
-
- public function testDashboardCreateLiveRecountAfterDelete(): void
- {
- // REQ-QUOTA-002 — count is computed live, so dropping below the
- // limit immediately permits a new create.
- $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
- $this->dashboardMapper->method('countPersonalByUserId')->willReturn(4);
-
- $this->service->assertCanCreateDashboard(userId: 'alice');
- $this->addToAssertionCount(1);
- }//end testDashboardCreateLiveRecountAfterDelete()
-
- public function testGrandfatheringBlocksWhenOverLoweredLimit(): void
- {
- // REQ-QUOTA-005 — usage (8) exceeds a lowered limit (5): new
- // creation blocked, exception carries the real over-quota count.
- $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
- $this->dashboardMapper->method('countPersonalByUserId')->willReturn(8);
-
- try {
- $this->service->assertCanCreateDashboard(userId: 'alice');
- $this->fail('Expected QuotaExceededException');
- } catch (QuotaExceededException $e) {
- $this->assertSame(5, $e->getLimit());
- $this->assertSame(8, $e->getCurrent());
- }
- }//end testGrandfatheringBlocksWhenOverLoweredLimit()
-
- // ----- REQ-QUOTA-002 / D6: most-restrictive-wins -----
-
- public function testAllowMultipleFalseGivesEffectiveLimitOne(): void
- {
- // REQ-QUOTA-002 — allow_multiple_dashboards = false ⇒ effective
- // limit 1 regardless of the numeric setting (5).
- $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5, allowMultiple: false);
- $this->dashboardMapper->method('countPersonalByUserId')->willReturn(1);
-
- try {
- $this->service->assertCanCreateDashboard(userId: 'alice');
- $this->fail('Expected QuotaExceededException');
- } catch (QuotaExceededException $e) {
- $this->assertSame(1, $e->getLimit());
- $this->assertSame(1, $e->getCurrent());
- }
- }//end testAllowMultipleFalseGivesEffectiveLimitOne()
-
- public function testNumericQuotaDoesNotLoosenBooleanRestriction(): void
- {
- // REQ-QUOTA-002 — even with a generous numeric quota, the boolean
- // off-switch keeps the effective limit at 1, so a user with 1
- // dashboard is blocked from a second.
- $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 100, allowMultiple: false);
- $this->dashboardMapper->method('countPersonalByUserId')->willReturn(1);
-
- $this->expectException(QuotaExceededException::class);
- $this->service->assertCanCreateDashboard(userId: 'alice');
- }//end testNumericQuotaDoesNotLoosenBooleanRestriction()
-
- // ----- REQ-QUOTA-003: widget count enforcement -----
-
- public function testWidgetAddAllowedBelowLimit(): void
- {
- $this->withSettings(AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD, 40);
- $this->placementMapper->method('countByDashboardId')->willReturn(39);
-
- $this->service->assertCanAddPlacement(dashboardId: 7);
- $this->addToAssertionCount(1);
- }//end testWidgetAddAllowedBelowLimit()
-
- public function testWidgetAddBlockedAtLimit(): void
- {
- $this->withSettings(AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD, 40);
- $this->placementMapper->method('countByDashboardId')->willReturn(40);
-
- try {
- $this->service->assertCanAddPlacement(dashboardId: 7);
- $this->fail('Expected QuotaExceededException');
- } catch (QuotaExceededException $e) {
- $this->assertSame(QuotaExceededException::QUOTA_WIDGETS, $e->getQuota());
- $this->assertSame(40, $e->getLimit());
- $this->assertSame(40, $e->getCurrent());
- $this->assertSame('widgets', $e->toResponseBody()['quota']);
- }//end try
- }//end testWidgetAddBlockedAtLimit()
-
- public function testWidgetAddUnlimitedWhenZero(): void
- {
- $this->withSettings(AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD, 0);
- $this->placementMapper->expects($this->never())
- ->method('countByDashboardId');
-
- $this->service->assertCanAddPlacement(dashboardId: 7);
- $this->addToAssertionCount(1);
- }//end testWidgetAddUnlimitedWhenZero()
-
- // ----- REQ-QUOTA-004: provisioning bypass -----
-
- public function testProvisioningBypassesDashboardQuota(): void
- {
- // REQ-QUOTA-004 — inside runProvisioning(), an over-quota user's
- // creation is NOT blocked (template rollout). Count never queried.
- $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
- $this->dashboardMapper->expects($this->never())
- ->method('countPersonalByUserId');
-
- $ran = $this->service->runProvisioning(
- function () {
- $this->service->assertCanCreateDashboard(userId: 'alice');
- return 'rolled-out';
- }
- );
-
- $this->assertSame('rolled-out', $ran);
- }//end testProvisioningBypassesDashboardQuota()
-
- public function testProvisioningBypassesWidgetQuota(): void
- {
- // REQ-QUOTA-004 — compulsory-widget push bypasses the widget quota.
- $this->withSettings(AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD, 40);
- $this->placementMapper->expects($this->never())
- ->method('countByDashboardId');
-
- $this->service->runProvisioning(
- function () {
- $this->service->assertCanAddPlacement(dashboardId: 7);
- }
- );
- $this->addToAssertionCount(1);
- }//end testProvisioningBypassesWidgetQuota()
-
- public function testProvisioningFlagResetsAfterCallEvenOnThrow(): void
- {
- // REQ-QUOTA-004 — a throwing provisioning call must NOT leave the
- // service permanently bypassed: the next user-initiated assert is
- // enforced again.
- $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
- $this->dashboardMapper->method('countPersonalByUserId')->willReturn(5);
-
- try {
- $this->service->runProvisioning(
- function () {
- throw new \RuntimeException('boom');
- }
- );
- } catch (\RuntimeException) {
- // expected
- }
-
- $this->assertFalse($this->service->isProvisioning());
- $this->expectException(QuotaExceededException::class);
- $this->service->assertCanCreateDashboard(userId: 'alice');
- }//end testProvisioningFlagResetsAfterCallEvenOnThrow()
-
- public function testAdminBoundByQuotaOutsideProvisioning(): void
- {
- // REQ-QUOTA-004 — an admin creating their own personal dashboard
- // through the normal flow (no provisioning wrapper) is still bound.
- $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
- $this->dashboardMapper->method('countPersonalByUserId')->willReturn(5);
-
- $this->expectException(QuotaExceededException::class);
- $this->service->assertCanCreateDashboard(userId: 'carol');
- }//end testAdminBoundByQuotaOutsideProvisioning()
-
- // ----- REQ-QUOTA-006: quota status envelope -----
-
- public function testGetQuotaStatusEnvelopeShape(): void
- {
- $this->settingMapper->method('getValue')->willReturnCallback(
- function (string $k, $default=null) {
- return match ($k) {
- AdminSetting::KEY_MAX_DASHBOARDS_PER_USER => 5,
- AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD => 40,
- AdminSetting::KEY_ALLOW_MULTIPLE_DASHBOARDS => true,
- default => $default,
- };
- }
- );
- $this->dashboardMapper->method('countPersonalByUserId')->willReturn(3);
-
- $status = $this->service->getQuotaStatus(userId: 'alice');
-
- $this->assertSame(
- [
- 'maxDashboards' => 5,
- 'dashboardsUsed' => 3,
- 'maxWidgetsPerDashboard' => 40,
- ],
- $status
- );
- }//end testGetQuotaStatusEnvelopeShape()
-
- public function testGetQuotaStatusReflectsEffectiveLimit(): void
- {
- // REQ-QUOTA-006 / D6 — the envelope surfaces the EFFECTIVE limit, so
- // allow_multiple_dashboards = false shows maxDashboards = 1.
- $this->settingMapper->method('getValue')->willReturnCallback(
- function (string $k, $default=null) {
- return match ($k) {
- AdminSetting::KEY_MAX_DASHBOARDS_PER_USER => 5,
- AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD => 0,
- AdminSetting::KEY_ALLOW_MULTIPLE_DASHBOARDS => false,
- default => $default,
- };
- }
- );
- $this->dashboardMapper->method('countPersonalByUserId')->willReturn(1);
-
- $status = $this->service->getQuotaStatus(userId: 'alice');
-
- $this->assertSame(1, $status['maxDashboards']);
- $this->assertSame(0, $status['maxWidgetsPerDashboard']);
- }//end testGetQuotaStatusReflectsEffectiveLimit()
+class QuotaServiceTest extends TestCase {
+
+ private QuotaService $service;
+
+ private AdminSettingMapper $settingMapper;
+
+ private DashboardMapper $dashboardMapper;
+
+ private WidgetPlacementMapper $placementMapper;
+
+ protected function setUp(): void {
+ $this->settingMapper = $this->createMock(AdminSettingMapper::class);
+ $this->dashboardMapper = $this->createMock(DashboardMapper::class);
+ $this->placementMapper = $this->createMock(WidgetPlacementMapper::class);
+ $this->service = new QuotaService(
+ settingMapper: $this->settingMapper,
+ dashboardMapper: $this->dashboardMapper,
+ placementMapper: $this->placementMapper,
+ );
+ }//end setUp()
+
+ /**
+ * Wire the setting mapper's getValue() for a given numeric quota +
+ * allow-multiple flag.
+ *
+ * @param string $key The numeric quota key.
+ * @param int $value The numeric quota value.
+ * @param bool $allowMultiple The allow_multiple_dashboards flag.
+ *
+ * @return void
+ */
+ private function withSettings(string $key, int $value, bool $allowMultiple = true): void {
+ $this->settingMapper->method('getValue')->willReturnCallback(
+ function (string $k, $default = null) use ($key, $value, $allowMultiple) {
+ if ($k === $key) {
+ return $value;
+ }
+
+ if ($k === AdminSetting::KEY_ALLOW_MULTIPLE_DASHBOARDS) {
+ return $allowMultiple;
+ }
+
+ return $default;
+ }
+ );
+ }//end withSettings()
+
+ // ----- REQ-QUOTA-002: dashboard count enforcement -----
+
+ public function testDashboardCreateAllowedBelowLimit(): void {
+ $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
+ $this->dashboardMapper->method('countPersonalByUserId')->willReturn(4);
+
+ // No exception => allowed.
+ $this->service->assertCanCreateDashboard(userId: 'alice');
+ $this->addToAssertionCount(1);
+ }//end testDashboardCreateAllowedBelowLimit()
+
+ public function testDashboardCreateBlockedAtLimit(): void {
+ $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
+ $this->dashboardMapper->method('countPersonalByUserId')->willReturn(5);
+
+ try {
+ $this->service->assertCanCreateDashboard(userId: 'alice');
+ $this->fail('Expected QuotaExceededException');
+ } catch (QuotaExceededException $e) {
+ $this->assertSame(QuotaExceededException::QUOTA_DASHBOARDS, $e->getQuota());
+ $this->assertSame(5, $e->getLimit());
+ $this->assertSame(5, $e->getCurrent());
+ $this->assertSame(409, $e->getHttpStatus());
+ $this->assertSame(
+ [
+ 'error' => 'quota_exceeded',
+ 'quota' => 'dashboards',
+ 'limit' => 5,
+ 'current' => 5,
+ ],
+ $e->toResponseBody()
+ );
+ }//end try
+ }//end testDashboardCreateBlockedAtLimit()
+
+ public function testDashboardCreateUnlimitedWhenZero(): void {
+ // REQ-QUOTA-001 — 0 means unlimited; count never queried.
+ $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 0);
+ $this->dashboardMapper->expects($this->never())
+ ->method('countPersonalByUserId');
+
+ $this->service->assertCanCreateDashboard(userId: 'alice');
+ $this->addToAssertionCount(1);
+ }//end testDashboardCreateUnlimitedWhenZero()
+
+ public function testDashboardCreateLiveRecountAfterDelete(): void {
+ // REQ-QUOTA-002 — count is computed live, so dropping below the
+ // limit immediately permits a new create.
+ $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
+ $this->dashboardMapper->method('countPersonalByUserId')->willReturn(4);
+
+ $this->service->assertCanCreateDashboard(userId: 'alice');
+ $this->addToAssertionCount(1);
+ }//end testDashboardCreateLiveRecountAfterDelete()
+
+ public function testGrandfatheringBlocksWhenOverLoweredLimit(): void {
+ // REQ-QUOTA-005 — usage (8) exceeds a lowered limit (5): new
+ // creation blocked, exception carries the real over-quota count.
+ $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
+ $this->dashboardMapper->method('countPersonalByUserId')->willReturn(8);
+
+ try {
+ $this->service->assertCanCreateDashboard(userId: 'alice');
+ $this->fail('Expected QuotaExceededException');
+ } catch (QuotaExceededException $e) {
+ $this->assertSame(5, $e->getLimit());
+ $this->assertSame(8, $e->getCurrent());
+ }
+ }//end testGrandfatheringBlocksWhenOverLoweredLimit()
+
+ // ----- REQ-QUOTA-002 / D6: most-restrictive-wins -----
+
+ public function testAllowMultipleFalseGivesEffectiveLimitOne(): void {
+ // REQ-QUOTA-002 — allow_multiple_dashboards = false ⇒ effective
+ // limit 1 regardless of the numeric setting (5).
+ $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5, allowMultiple: false);
+ $this->dashboardMapper->method('countPersonalByUserId')->willReturn(1);
+
+ try {
+ $this->service->assertCanCreateDashboard(userId: 'alice');
+ $this->fail('Expected QuotaExceededException');
+ } catch (QuotaExceededException $e) {
+ $this->assertSame(1, $e->getLimit());
+ $this->assertSame(1, $e->getCurrent());
+ }
+ }//end testAllowMultipleFalseGivesEffectiveLimitOne()
+
+ public function testNumericQuotaDoesNotLoosenBooleanRestriction(): void {
+ // REQ-QUOTA-002 — even with a generous numeric quota, the boolean
+ // off-switch keeps the effective limit at 1, so a user with 1
+ // dashboard is blocked from a second.
+ $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 100, allowMultiple: false);
+ $this->dashboardMapper->method('countPersonalByUserId')->willReturn(1);
+
+ $this->expectException(QuotaExceededException::class);
+ $this->service->assertCanCreateDashboard(userId: 'alice');
+ }//end testNumericQuotaDoesNotLoosenBooleanRestriction()
+
+ // ----- REQ-QUOTA-003: widget count enforcement -----
+
+ public function testWidgetAddAllowedBelowLimit(): void {
+ $this->withSettings(AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD, 40);
+ $this->placementMapper->method('countByDashboardId')->willReturn(39);
+
+ $this->service->assertCanAddPlacement(dashboardId: 7);
+ $this->addToAssertionCount(1);
+ }//end testWidgetAddAllowedBelowLimit()
+
+ public function testWidgetAddBlockedAtLimit(): void {
+ $this->withSettings(AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD, 40);
+ $this->placementMapper->method('countByDashboardId')->willReturn(40);
+
+ try {
+ $this->service->assertCanAddPlacement(dashboardId: 7);
+ $this->fail('Expected QuotaExceededException');
+ } catch (QuotaExceededException $e) {
+ $this->assertSame(QuotaExceededException::QUOTA_WIDGETS, $e->getQuota());
+ $this->assertSame(40, $e->getLimit());
+ $this->assertSame(40, $e->getCurrent());
+ $this->assertSame('widgets', $e->toResponseBody()['quota']);
+ }//end try
+ }//end testWidgetAddBlockedAtLimit()
+
+ public function testWidgetAddUnlimitedWhenZero(): void {
+ $this->withSettings(AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD, 0);
+ $this->placementMapper->expects($this->never())
+ ->method('countByDashboardId');
+
+ $this->service->assertCanAddPlacement(dashboardId: 7);
+ $this->addToAssertionCount(1);
+ }//end testWidgetAddUnlimitedWhenZero()
+
+ // ----- REQ-QUOTA-004: provisioning bypass -----
+
+ public function testProvisioningBypassesDashboardQuota(): void {
+ // REQ-QUOTA-004 — inside runProvisioning(), an over-quota user's
+ // creation is NOT blocked (template rollout). Count never queried.
+ $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
+ $this->dashboardMapper->expects($this->never())
+ ->method('countPersonalByUserId');
+
+ $ran = $this->service->runProvisioning(
+ function () {
+ $this->service->assertCanCreateDashboard(userId: 'alice');
+ return 'rolled-out';
+ }
+ );
+
+ $this->assertSame('rolled-out', $ran);
+ }//end testProvisioningBypassesDashboardQuota()
+
+ public function testProvisioningBypassesWidgetQuota(): void {
+ // REQ-QUOTA-004 — compulsory-widget push bypasses the widget quota.
+ $this->withSettings(AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD, 40);
+ $this->placementMapper->expects($this->never())
+ ->method('countByDashboardId');
+
+ $this->service->runProvisioning(
+ function () {
+ $this->service->assertCanAddPlacement(dashboardId: 7);
+ }
+ );
+ $this->addToAssertionCount(1);
+ }//end testProvisioningBypassesWidgetQuota()
+
+ public function testProvisioningFlagResetsAfterCallEvenOnThrow(): void {
+ // REQ-QUOTA-004 — a throwing provisioning call must NOT leave the
+ // service permanently bypassed: the next user-initiated assert is
+ // enforced again.
+ $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
+ $this->dashboardMapper->method('countPersonalByUserId')->willReturn(5);
+
+ try {
+ $this->service->runProvisioning(
+ function () {
+ throw new \RuntimeException('boom');
+ }
+ );
+ } catch (\RuntimeException) {
+ // expected
+ }
+
+ $this->assertFalse($this->service->isProvisioning());
+ $this->expectException(QuotaExceededException::class);
+ $this->service->assertCanCreateDashboard(userId: 'alice');
+ }//end testProvisioningFlagResetsAfterCallEvenOnThrow()
+
+ public function testAdminBoundByQuotaOutsideProvisioning(): void {
+ // REQ-QUOTA-004 — an admin creating their own personal dashboard
+ // through the normal flow (no provisioning wrapper) is still bound.
+ $this->withSettings(AdminSetting::KEY_MAX_DASHBOARDS_PER_USER, 5);
+ $this->dashboardMapper->method('countPersonalByUserId')->willReturn(5);
+
+ $this->expectException(QuotaExceededException::class);
+ $this->service->assertCanCreateDashboard(userId: 'carol');
+ }//end testAdminBoundByQuotaOutsideProvisioning()
+
+ // ----- REQ-QUOTA-006: quota status envelope -----
+
+ public function testGetQuotaStatusEnvelopeShape(): void {
+ $this->settingMapper->method('getValue')->willReturnCallback(
+ function (string $k, $default = null) {
+ return match ($k) {
+ AdminSetting::KEY_MAX_DASHBOARDS_PER_USER => 5,
+ AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD => 40,
+ AdminSetting::KEY_ALLOW_MULTIPLE_DASHBOARDS => true,
+ default => $default,
+ };
+ }
+ );
+ $this->dashboardMapper->method('countPersonalByUserId')->willReturn(3);
+
+ $status = $this->service->getQuotaStatus(userId: 'alice');
+
+ $this->assertSame(
+ [
+ 'maxDashboards' => 5,
+ 'dashboardsUsed' => 3,
+ 'maxWidgetsPerDashboard' => 40,
+ ],
+ $status
+ );
+ }//end testGetQuotaStatusEnvelopeShape()
+
+ public function testGetQuotaStatusReflectsEffectiveLimit(): void {
+ // REQ-QUOTA-006 / D6 — the envelope surfaces the EFFECTIVE limit, so
+ // allow_multiple_dashboards = false shows maxDashboards = 1.
+ $this->settingMapper->method('getValue')->willReturnCallback(
+ function (string $k, $default = null) {
+ return match ($k) {
+ AdminSetting::KEY_MAX_DASHBOARDS_PER_USER => 5,
+ AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD => 0,
+ AdminSetting::KEY_ALLOW_MULTIPLE_DASHBOARDS => false,
+ default => $default,
+ };
+ }
+ );
+ $this->dashboardMapper->method('countPersonalByUserId')->willReturn(1);
+
+ $status = $this->service->getQuotaStatus(userId: 'alice');
+
+ $this->assertSame(1, $status['maxDashboards']);
+ $this->assertSame(0, $status['maxWidgetsPerDashboard']);
+ }//end testGetQuotaStatusReflectsEffectiveLimit()
}//end class
diff --git a/tests/Unit/Service/ReactionServiceTest.php b/tests/Unit/Service/ReactionServiceTest.php
index 8cae8e1c..53b95bbf 100644
--- a/tests/Unit/Service/ReactionServiceTest.php
+++ b/tests/Unit/Service/ReactionServiceTest.php
@@ -28,9 +28,8 @@
use OCA\LaunchPad\Db\DashboardReactionMapper;
use OCA\LaunchPad\Service\PermissionDeniedException;
use OCA\LaunchPad\Service\PermissionService;
-use OCA\LaunchPad\Service\ReactionService;
use OCA\LaunchPad\Service\ReactionsDisabledException;
-use OCP\AppFramework\Db\DoesNotExistException;
+use OCA\LaunchPad\Service\ReactionService;
use OCP\DB\Exception as DbException;
use OCP\IAppConfig;
use OCP\IUser;
@@ -41,348 +40,329 @@
/**
* Tests for ReactionService.
*/
-class ReactionServiceTest extends TestCase
-{
- private DashboardReactionMapper&MockObject $reactionMapper;
- private DashboardMapper&MockObject $dashboardMapper;
- private PermissionService&MockObject $permissionService;
- private IAppConfig&MockObject $appConfig;
- private IUserManager&MockObject $userManager;
- private ReactionService $service;
-
- protected function setUp(): void
- {
- $this->reactionMapper = $this->createMock(originalClassName: DashboardReactionMapper::class);
- $this->dashboardMapper = $this->createMock(originalClassName: DashboardMapper::class);
- $this->permissionService = $this->createMock(originalClassName: PermissionService::class);
- $this->appConfig = $this->createMock(originalClassName: IAppConfig::class);
- $this->userManager = $this->createMock(originalClassName: IUserManager::class);
-
- $this->service = new ReactionService(
- reactionMapper: $this->reactionMapper,
- dashboardMapper: $this->dashboardMapper,
- permissionService: $this->permissionService,
- appConfig: $this->appConfig,
- userManager: $this->userManager,
- );
- }
-
- private function makeDashboard(?int $perDashFlag, int $id=1, string $uuid='dash-123'): Dashboard
- {
- $dashboard = new Dashboard();
- // phpcs:disable CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- // Entity __call uses $args[0] — named args break the magic forwarding.
- $dashboard->setId($id);
- $dashboard->setUuid($uuid);
- $dashboard->setReactionsEnabled($perDashFlag);
- // phpcs:enable CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- return $dashboard;
- }
-
- /**
- * REQ-RXN-006 — null/1/0 tri-state resolution.
- */
- public function testIsReactionsEnabledTriState(): void
- {
- $this->appConfig->method('getValueBool')->willReturn(true);
-
- $this->assertTrue($this->service->isReactionsEnabled(dashboard: $this->makeDashboard(perDashFlag: 1)));
- $this->assertFalse($this->service->isReactionsEnabled(dashboard: $this->makeDashboard(perDashFlag: 0)));
- $this->assertTrue($this->service->isReactionsEnabled(dashboard: $this->makeDashboard(perDashFlag: null)));
- }
-
- /**
- * REQ-RXN-007 scenario "Admin updates the allowed emoji list".
- */
- public function testValidateEmojiRejectsNonWhitelisted(): void
- {
- $this->appConfig->method('getValueString')->willReturn('["👍","❤️"]');
-
- $this->expectException(InvalidArgumentException::class);
- $this->service->validateEmoji(emoji: '🚀');
- }
-
- public function testValidateEmojiAcceptsWhitelisted(): void
- {
- $this->appConfig->method('getValueString')->willReturn('["👍","❤️"]');
-
- $this->service->validateEmoji(emoji: '❤️');
- $this->expectNotToPerformAssertions();
- }
-
- public function testValidateEmojiRejectsEmpty(): void
- {
- $this->appConfig->method('getValueString')->willReturn('["👍"]');
- $this->expectException(InvalidArgumentException::class);
- $this->service->validateEmoji(emoji: '');
- }
-
- /**
- * REQ-RXN-007 scenario "Default allowed emoji list".
- */
- public function testGetAllowedEmojisDefaults(): void
- {
- $this->appConfig->method('getValueString')->willReturn('');
- $this->assertSame(
- ReactionService::DEFAULT_ALLOWED_EMOJIS,
- $this->service->getAllowedEmojis()
- );
- }
-
- public function testGetAllowedEmojisFallsBackOnCorruptJson(): void
- {
- $this->appConfig->method('getValueString')->willReturn('not-json');
- $this->assertSame(
- ReactionService::DEFAULT_ALLOWED_EMOJIS,
- $this->service->getAllowedEmojis()
- );
- }
-
- /**
- * REQ-RXN-007 scenario "Empty emoji in whitelist" — admin-set
- * empty list returned as-is so validateEmoji rejects everything.
- */
- public function testGetAllowedEmojisEmptyAdminListSurfacesAsEmpty(): void
- {
- $this->appConfig->method('getValueString')->willReturn('[]');
- $this->assertSame([], $this->service->getAllowedEmojis());
- }
-
- /**
- * REQ-RXN-008 — non-VIEW user rejected with PermissionDeniedException.
- */
- public function testAddReactionPermissionDenied(): void
- {
- $dash = $this->makeDashboard(perDashFlag: 1);
- $this->dashboardMapper->method('findByUuid')->willReturn($dash);
- $this->permissionService->method('canViewDashboard')->willReturn(false);
-
- $this->expectException(PermissionDeniedException::class);
- $this->service->addReaction(
- dashboardUuid: 'dash-123',
- userId: 'bob',
- emoji: '👍'
- );
- }
-
- /**
- * REQ-RXN-005 — global off + per-dashboard null returns
- * ReactionsDisabledException on POST.
- */
- public function testAddReactionDisabledThrows(): void
- {
- $dash = $this->makeDashboard(perDashFlag: null);
- $this->dashboardMapper->method('findByUuid')->willReturn($dash);
- $this->permissionService->method('canViewDashboard')->willReturn(true);
- $this->appConfig->method('getValueBool')->willReturn(false);
-
- $this->expectException(ReactionsDisabledException::class);
- $this->service->addReaction(
- dashboardUuid: 'dash-123',
- userId: 'alice',
- emoji: '👍'
- );
- }
-
- /**
- * REQ-RXN-001 scenario "User re-posts the same emoji" — duplicate
- * insert (unique constraint) is swallowed; summary returned as if
- * the row already existed.
- */
- public function testAddReactionIdempotentOnUniqueConstraint(): void
- {
- $dash = $this->makeDashboard(perDashFlag: 1);
- $this->dashboardMapper->method('findByUuid')->willReturn($dash);
- $this->permissionService->method('canViewDashboard')->willReturn(true);
- $this->appConfig->method('getValueString')->willReturn('["👍"]');
- $this->appConfig->method('getValueBool')->willReturn(true);
-
- $duplicate = $this->createMock(originalClassName: DbException::class);
- $duplicate->method('getReason')->willReturn(DbException::REASON_UNIQUE_CONSTRAINT_VIOLATION);
- $this->reactionMapper->method('addReaction')->willThrowException($duplicate);
-
- $this->reactionMapper->method('countByEmoji')->willReturn(['👍' => 1]);
- $existing = new DashboardReaction();
- $existing->setEmoji('👍');
- $this->reactionMapper->method('findByUser')->willReturn([$existing]);
-
- $summary = $this->service->addReaction(
- dashboardUuid: 'dash-123',
- userId: 'alice',
- emoji: '👍'
- );
-
- $this->assertTrue($summary['enabled']);
- $this->assertSame(['👍'], $summary['mine']);
- $this->assertSame(['👍' => 1], (array) $summary['counts']);
- }
-
- /**
- * REQ-RXN-003 scenario "Reactions disabled on dashboard" — GET
- * returns the empty-shape summary regardless of stored rows.
- */
- public function testGetReactionsSummaryDisabledShape(): void
- {
- $dash = $this->makeDashboard(perDashFlag: 0);
- $this->dashboardMapper->method('findByUuid')->willReturn($dash);
- $this->permissionService->method('canViewDashboard')->willReturn(true);
- $this->appConfig->method('getValueBool')->willReturn(true);
-
- $this->reactionMapper->expects($this->never())->method('countByEmoji');
-
- $summary = $this->service->getReactionsSummary(
- dashboardUuid: 'dash-123',
- userId: 'alice'
- );
-
- $this->assertFalse($summary['enabled']);
- $this->assertSame([], (array) $summary['counts']);
- $this->assertSame([], $summary['mine']);
- }
-
- /**
- * REQ-RXN-003 scenario "User retrieves reactions on a dashboard
- * they can view" — counts + mine populated from mapper.
- */
- public function testGetReactionsSummaryEnabledShape(): void
- {
- $dash = $this->makeDashboard(perDashFlag: 1);
- $this->dashboardMapper->method('findByUuid')->willReturn($dash);
- $this->permissionService->method('canViewDashboard')->willReturn(true);
- $this->appConfig->method('getValueBool')->willReturn(true);
-
- $this->reactionMapper->method('countByEmoji')->willReturn([
- '👍' => 3,
- '❤️' => 1,
- '🎉' => 2,
- ]);
-
- $a = new DashboardReaction();
- $a->setEmoji('👍');
- $b = new DashboardReaction();
- $b->setEmoji('🎉');
- $this->reactionMapper->method('findByUser')->willReturn([$a, $b]);
-
- $summary = $this->service->getReactionsSummary(
- dashboardUuid: 'dash-123',
- userId: 'alice'
- );
-
- $this->assertTrue($summary['enabled']);
- $this->assertSame(
- ['👍' => 3, '❤️' => 1, '🎉' => 2],
- (array) $summary['counts']
- );
- $this->assertSame(['👍', '🎉'], $summary['mine']);
- }
-
- /**
- * REQ-RXN-002 — DELETE delegates to mapper; idempotent return
- * value bubbles up.
- */
- public function testRemoveReactionDelegatesToMapper(): void
- {
- $dash = $this->makeDashboard(perDashFlag: 1);
- $this->dashboardMapper->method('findByUuid')->willReturn($dash);
- $this->permissionService->method('canViewDashboard')->willReturn(true);
-
- $this->reactionMapper->expects($this->once())
- ->method('removeReaction')
- ->with(
- $this->equalTo('dash-123'),
- $this->equalTo('alice'),
- $this->equalTo('👍'),
- )
- ->willReturn(true);
-
- $result = $this->service->removeReaction(
- dashboardUuid: 'dash-123',
- userId: 'alice',
- emoji: '👍'
- );
-
- $this->assertTrue($result);
- }
-
- /**
- * REQ-RXN-009 — cascade delete delegates to mapper.
- */
- public function testDeleteReactionsByDashboardDelegates(): void
- {
- $this->reactionMapper->expects($this->once())
- ->method('deleteByDashboardUuid')
- ->with($this->equalTo('dash-123'))
- ->willReturn(7);
-
- $this->assertSame(
- 7,
- $this->service->deleteReactionsByDashboard(dashboardUuid: 'dash-123')
- );
- }
-
- /**
- * REQ-RXN-004 — pagination cap + cursor advance.
- */
- public function testGetReactorsByEmojiPagination(): void
- {
- $dash = $this->makeDashboard(perDashFlag: 1);
- $this->dashboardMapper->method('findByUuid')->willReturn($dash);
- $this->permissionService->method('canViewDashboard')->willReturn(true);
-
- $rows = [];
- for ($i = 0; $i < ReactionService::REACTORS_PAGE_SIZE; $i++) {
- $r = new DashboardReaction();
- $r->setUserId(sprintf('user%d', $i));
- $r->setEmoji('🎉');
- $rows[] = $r;
- }
-
- $this->reactionMapper->method('findByEmoji')->willReturn($rows);
- $this->reactionMapper->method('countReactorsByEmoji')->willReturn(150);
-
- $user = $this->createMock(originalClassName: IUser::class);
- $user->method('getDisplayName')->willReturn('User');
- $this->userManager->method('get')->willReturn($user);
-
- $page = $this->service->getReactorsByEmoji(
- dashboardUuid: 'dash-123',
- emoji: '🎉',
- userId: 'alice',
- cursor: null
- );
-
- $this->assertCount(ReactionService::REACTORS_PAGE_SIZE, $page['items']);
- $this->assertSame('100', $page['nextCursor']);
- $this->assertSame(150, $page['total']);
- }
-
- /**
- * Last page exposes nextCursor === null.
- */
- public function testGetReactorsByEmojiLastPageNoCursor(): void
- {
- $dash = $this->makeDashboard(perDashFlag: 1);
- $this->dashboardMapper->method('findByUuid')->willReturn($dash);
- $this->permissionService->method('canViewDashboard')->willReturn(true);
-
- $r = new DashboardReaction();
- $r->setUserId('alice');
- $r->setEmoji('🎉');
- $this->reactionMapper->method('findByEmoji')->willReturn([$r]);
- $this->reactionMapper->method('countReactorsByEmoji')->willReturn(1);
-
- $user = $this->createMock(originalClassName: IUser::class);
- $user->method('getDisplayName')->willReturn('Alice');
- $this->userManager->method('get')->willReturn($user);
-
- $page = $this->service->getReactorsByEmoji(
- dashboardUuid: 'dash-123',
- emoji: '🎉',
- userId: 'alice',
- cursor: null
- );
-
- $this->assertNull($page['nextCursor']);
- $this->assertSame(1, $page['total']);
- }
+class ReactionServiceTest extends TestCase {
+ private DashboardReactionMapper&MockObject $reactionMapper;
+ private DashboardMapper&MockObject $dashboardMapper;
+ private PermissionService&MockObject $permissionService;
+ private IAppConfig&MockObject $appConfig;
+ private IUserManager&MockObject $userManager;
+ private ReactionService $service;
+
+ protected function setUp(): void {
+ $this->reactionMapper = $this->createMock(originalClassName: DashboardReactionMapper::class);
+ $this->dashboardMapper = $this->createMock(originalClassName: DashboardMapper::class);
+ $this->permissionService = $this->createMock(originalClassName: PermissionService::class);
+ $this->appConfig = $this->createMock(originalClassName: IAppConfig::class);
+ $this->userManager = $this->createMock(originalClassName: IUserManager::class);
+
+ $this->service = new ReactionService(
+ reactionMapper: $this->reactionMapper,
+ dashboardMapper: $this->dashboardMapper,
+ permissionService: $this->permissionService,
+ appConfig: $this->appConfig,
+ userManager: $this->userManager,
+ );
+ }
+
+ private function makeDashboard(?int $perDashFlag, int $id = 1, string $uuid = 'dash-123'): Dashboard {
+ $dashboard = new Dashboard();
+ // phpcs:disable CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ // Entity __call uses $args[0] — named args break the magic forwarding.
+ $dashboard->setId($id);
+ $dashboard->setUuid($uuid);
+ $dashboard->setReactionsEnabled($perDashFlag);
+ // phpcs:enable CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ return $dashboard;
+ }
+
+ /**
+ * REQ-RXN-006 — null/1/0 tri-state resolution.
+ */
+ public function testIsReactionsEnabledTriState(): void {
+ $this->appConfig->method('getValueBool')->willReturn(true);
+
+ $this->assertTrue($this->service->isReactionsEnabled(dashboard: $this->makeDashboard(perDashFlag: 1)));
+ $this->assertFalse($this->service->isReactionsEnabled(dashboard: $this->makeDashboard(perDashFlag: 0)));
+ $this->assertTrue($this->service->isReactionsEnabled(dashboard: $this->makeDashboard(perDashFlag: null)));
+ }
+
+ /**
+ * REQ-RXN-007 scenario "Admin updates the allowed emoji list".
+ */
+ public function testValidateEmojiRejectsNonWhitelisted(): void {
+ $this->appConfig->method('getValueString')->willReturn('["👍","❤️"]');
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->service->validateEmoji(emoji: '🚀');
+ }
+
+ public function testValidateEmojiAcceptsWhitelisted(): void {
+ $this->appConfig->method('getValueString')->willReturn('["👍","❤️"]');
+
+ $this->service->validateEmoji(emoji: '❤️');
+ $this->expectNotToPerformAssertions();
+ }
+
+ public function testValidateEmojiRejectsEmpty(): void {
+ $this->appConfig->method('getValueString')->willReturn('["👍"]');
+ $this->expectException(InvalidArgumentException::class);
+ $this->service->validateEmoji(emoji: '');
+ }
+
+ /**
+ * REQ-RXN-007 scenario "Default allowed emoji list".
+ */
+ public function testGetAllowedEmojisDefaults(): void {
+ $this->appConfig->method('getValueString')->willReturn('');
+ $this->assertSame(
+ ReactionService::DEFAULT_ALLOWED_EMOJIS,
+ $this->service->getAllowedEmojis()
+ );
+ }
+
+ public function testGetAllowedEmojisFallsBackOnCorruptJson(): void {
+ $this->appConfig->method('getValueString')->willReturn('not-json');
+ $this->assertSame(
+ ReactionService::DEFAULT_ALLOWED_EMOJIS,
+ $this->service->getAllowedEmojis()
+ );
+ }
+
+ /**
+ * REQ-RXN-007 scenario "Empty emoji in whitelist" — admin-set
+ * empty list returned as-is so validateEmoji rejects everything.
+ */
+ public function testGetAllowedEmojisEmptyAdminListSurfacesAsEmpty(): void {
+ $this->appConfig->method('getValueString')->willReturn('[]');
+ $this->assertSame([], $this->service->getAllowedEmojis());
+ }
+
+ /**
+ * REQ-RXN-008 — non-VIEW user rejected with PermissionDeniedException.
+ */
+ public function testAddReactionPermissionDenied(): void {
+ $dash = $this->makeDashboard(perDashFlag: 1);
+ $this->dashboardMapper->method('findByUuid')->willReturn($dash);
+ $this->permissionService->method('canViewDashboard')->willReturn(false);
+
+ $this->expectException(PermissionDeniedException::class);
+ $this->service->addReaction(
+ dashboardUuid: 'dash-123',
+ userId: 'bob',
+ emoji: '👍'
+ );
+ }
+
+ /**
+ * REQ-RXN-005 — global off + per-dashboard null returns
+ * ReactionsDisabledException on POST.
+ */
+ public function testAddReactionDisabledThrows(): void {
+ $dash = $this->makeDashboard(perDashFlag: null);
+ $this->dashboardMapper->method('findByUuid')->willReturn($dash);
+ $this->permissionService->method('canViewDashboard')->willReturn(true);
+ $this->appConfig->method('getValueBool')->willReturn(false);
+
+ $this->expectException(ReactionsDisabledException::class);
+ $this->service->addReaction(
+ dashboardUuid: 'dash-123',
+ userId: 'alice',
+ emoji: '👍'
+ );
+ }
+
+ /**
+ * REQ-RXN-001 scenario "User re-posts the same emoji" — duplicate
+ * insert (unique constraint) is swallowed; summary returned as if
+ * the row already existed.
+ */
+ public function testAddReactionIdempotentOnUniqueConstraint(): void {
+ $dash = $this->makeDashboard(perDashFlag: 1);
+ $this->dashboardMapper->method('findByUuid')->willReturn($dash);
+ $this->permissionService->method('canViewDashboard')->willReturn(true);
+ $this->appConfig->method('getValueString')->willReturn('["👍"]');
+ $this->appConfig->method('getValueBool')->willReturn(true);
+
+ $duplicate = $this->createMock(originalClassName: DbException::class);
+ $duplicate->method('getReason')->willReturn(DbException::REASON_UNIQUE_CONSTRAINT_VIOLATION);
+ $this->reactionMapper->method('addReaction')->willThrowException($duplicate);
+
+ $this->reactionMapper->method('countByEmoji')->willReturn(['👍' => 1]);
+ $existing = new DashboardReaction();
+ $existing->setEmoji('👍');
+ $this->reactionMapper->method('findByUser')->willReturn([$existing]);
+
+ $summary = $this->service->addReaction(
+ dashboardUuid: 'dash-123',
+ userId: 'alice',
+ emoji: '👍'
+ );
+
+ $this->assertTrue($summary['enabled']);
+ $this->assertSame(['👍'], $summary['mine']);
+ $this->assertSame(['👍' => 1], (array)$summary['counts']);
+ }
+
+ /**
+ * REQ-RXN-003 scenario "Reactions disabled on dashboard" — GET
+ * returns the empty-shape summary regardless of stored rows.
+ */
+ public function testGetReactionsSummaryDisabledShape(): void {
+ $dash = $this->makeDashboard(perDashFlag: 0);
+ $this->dashboardMapper->method('findByUuid')->willReturn($dash);
+ $this->permissionService->method('canViewDashboard')->willReturn(true);
+ $this->appConfig->method('getValueBool')->willReturn(true);
+
+ $this->reactionMapper->expects($this->never())->method('countByEmoji');
+
+ $summary = $this->service->getReactionsSummary(
+ dashboardUuid: 'dash-123',
+ userId: 'alice'
+ );
+
+ $this->assertFalse($summary['enabled']);
+ $this->assertSame([], (array)$summary['counts']);
+ $this->assertSame([], $summary['mine']);
+ }
+
+ /**
+ * REQ-RXN-003 scenario "User retrieves reactions on a dashboard
+ * they can view" — counts + mine populated from mapper.
+ */
+ public function testGetReactionsSummaryEnabledShape(): void {
+ $dash = $this->makeDashboard(perDashFlag: 1);
+ $this->dashboardMapper->method('findByUuid')->willReturn($dash);
+ $this->permissionService->method('canViewDashboard')->willReturn(true);
+ $this->appConfig->method('getValueBool')->willReturn(true);
+
+ $this->reactionMapper->method('countByEmoji')->willReturn([
+ '👍' => 3,
+ '❤️' => 1,
+ '🎉' => 2,
+ ]);
+
+ $a = new DashboardReaction();
+ $a->setEmoji('👍');
+ $b = new DashboardReaction();
+ $b->setEmoji('🎉');
+ $this->reactionMapper->method('findByUser')->willReturn([$a, $b]);
+
+ $summary = $this->service->getReactionsSummary(
+ dashboardUuid: 'dash-123',
+ userId: 'alice'
+ );
+
+ $this->assertTrue($summary['enabled']);
+ $this->assertSame(
+ ['👍' => 3, '❤️' => 1, '🎉' => 2],
+ (array)$summary['counts']
+ );
+ $this->assertSame(['👍', '🎉'], $summary['mine']);
+ }
+
+ /**
+ * REQ-RXN-002 — DELETE delegates to mapper; idempotent return
+ * value bubbles up.
+ */
+ public function testRemoveReactionDelegatesToMapper(): void {
+ $dash = $this->makeDashboard(perDashFlag: 1);
+ $this->dashboardMapper->method('findByUuid')->willReturn($dash);
+ $this->permissionService->method('canViewDashboard')->willReturn(true);
+
+ $this->reactionMapper->expects($this->once())
+ ->method('removeReaction')
+ ->with(
+ $this->equalTo('dash-123'),
+ $this->equalTo('alice'),
+ $this->equalTo('👍'),
+ )
+ ->willReturn(true);
+
+ $result = $this->service->removeReaction(
+ dashboardUuid: 'dash-123',
+ userId: 'alice',
+ emoji: '👍'
+ );
+
+ $this->assertTrue($result);
+ }
+
+ /**
+ * REQ-RXN-009 — cascade delete delegates to mapper.
+ */
+ public function testDeleteReactionsByDashboardDelegates(): void {
+ $this->reactionMapper->expects($this->once())
+ ->method('deleteByDashboardUuid')
+ ->with($this->equalTo('dash-123'))
+ ->willReturn(7);
+
+ $this->assertSame(
+ 7,
+ $this->service->deleteReactionsByDashboard(dashboardUuid: 'dash-123')
+ );
+ }
+
+ /**
+ * REQ-RXN-004 — pagination cap + cursor advance.
+ */
+ public function testGetReactorsByEmojiPagination(): void {
+ $dash = $this->makeDashboard(perDashFlag: 1);
+ $this->dashboardMapper->method('findByUuid')->willReturn($dash);
+ $this->permissionService->method('canViewDashboard')->willReturn(true);
+
+ $rows = [];
+ for ($i = 0; $i < ReactionService::REACTORS_PAGE_SIZE; $i++) {
+ $r = new DashboardReaction();
+ $r->setUserId(sprintf('user%d', $i));
+ $r->setEmoji('🎉');
+ $rows[] = $r;
+ }
+
+ $this->reactionMapper->method('findByEmoji')->willReturn($rows);
+ $this->reactionMapper->method('countReactorsByEmoji')->willReturn(150);
+
+ $user = $this->createMock(originalClassName: IUser::class);
+ $user->method('getDisplayName')->willReturn('User');
+ $this->userManager->method('get')->willReturn($user);
+
+ $page = $this->service->getReactorsByEmoji(
+ dashboardUuid: 'dash-123',
+ emoji: '🎉',
+ userId: 'alice',
+ cursor: null
+ );
+
+ $this->assertCount(ReactionService::REACTORS_PAGE_SIZE, $page['items']);
+ $this->assertSame('100', $page['nextCursor']);
+ $this->assertSame(150, $page['total']);
+ }
+
+ /**
+ * Last page exposes nextCursor === null.
+ */
+ public function testGetReactorsByEmojiLastPageNoCursor(): void {
+ $dash = $this->makeDashboard(perDashFlag: 1);
+ $this->dashboardMapper->method('findByUuid')->willReturn($dash);
+ $this->permissionService->method('canViewDashboard')->willReturn(true);
+
+ $r = new DashboardReaction();
+ $r->setUserId('alice');
+ $r->setEmoji('🎉');
+ $this->reactionMapper->method('findByEmoji')->willReturn([$r]);
+ $this->reactionMapper->method('countReactorsByEmoji')->willReturn(1);
+
+ $user = $this->createMock(originalClassName: IUser::class);
+ $user->method('getDisplayName')->willReturn('Alice');
+ $this->userManager->method('get')->willReturn($user);
+
+ $page = $this->service->getReactorsByEmoji(
+ dashboardUuid: 'dash-123',
+ emoji: '🎉',
+ userId: 'alice',
+ cursor: null
+ );
+
+ $this->assertNull($page['nextCursor']);
+ $this->assertSame(1, $page['total']);
+ }
}
diff --git a/tests/Unit/Service/ResourceServeServiceTest.php b/tests/Unit/Service/ResourceServeServiceTest.php
index 99e0d26b..791859a2 100644
--- a/tests/Unit/Service/ResourceServeServiceTest.php
+++ b/tests/Unit/Service/ResourceServeServiceTest.php
@@ -30,143 +30,129 @@
use PHPUnit\Framework\TestCase;
use Psr\Log\LoggerInterface;
-class ResourceServeServiceTest extends TestCase
-{
- private ResourceServeService $service;
-
- /** @var IAppData&MockObject */
- private $appData;
-
- /** @var LoggerInterface&MockObject */
- private $logger;
-
- /** @var ISimpleFolder&MockObject */
- private $folder;
-
- protected function setUp(): void
- {
- $this->appData = $this->createMock(IAppData::class);
- $this->logger = $this->createMock(LoggerInterface::class);
- $this->folder = $this->createMock(ISimpleFolder::class);
-
- $this->service = new ResourceServeService(
- appData: $this->appData,
- logger: $this->logger,
- );
- }
-
- public function testFindFileReturnsFileWhenPresent(): void
- {
- $file = $this->createMock(ISimpleFile::class);
- $this->appData->method('getFolder')
- ->with(ResourceService::FOLDER)->willReturn($this->folder);
- $this->folder->method('getFile')->with('resource_abc.png')->willReturn($file);
-
- $this->assertSame($file, $this->service->findFile(filename: 'resource_abc.png'));
- }
-
- public function testFindFileReturnsNullWhenFolderMissing(): void
- {
- $this->appData->method('getFolder')
- ->willThrowException(new NotFoundException());
-
- $this->assertNull($this->service->findFile(filename: 'whatever.png'));
- }
-
- public function testFindFileReturnsNullWhenFileMissing(): void
- {
- $this->appData->method('getFolder')->willReturn($this->folder);
- $this->folder->method('getFile')
- ->willThrowException(new NotFoundException());
-
- $this->assertNull($this->service->findFile(filename: 'gone.png'));
- }
-
- public function testFindFileReturnsNullOnUnexpectedException(): void
- {
- $this->appData->method('getFolder')
- ->willThrowException(new \RuntimeException('boom'));
- $this->logger->expects($this->once())->method('warning');
-
- $this->assertNull($this->service->findFile(filename: 'whatever.png'));
- }
-
- public function testListFilesReturnsAllSimpleFiles(): void
- {
- $a = $this->createMock(ISimpleFile::class);
- $b = $this->createMock(ISimpleFile::class);
- $this->appData->method('getFolder')->willReturn($this->folder);
- $this->folder->method('getDirectoryListing')->willReturn([$a, $b]);
-
- $this->assertSame([$a, $b], $this->service->listFiles());
- }
-
- public function testListFilesReturnsEmptyArrayWhenFolderMissing(): void
- {
- $this->appData->method('getFolder')
- ->willThrowException(new NotFoundException());
-
- $this->assertSame([], $this->service->listFiles());
- }
-
- public function testListFilesReturnsEmptyArrayOnUnexpectedException(): void
- {
- $this->appData->method('getFolder')
- ->willThrowException(new \RuntimeException('disk failure'));
- $this->logger->expects($this->once())->method('warning');
-
- $this->assertSame([], $this->service->listFiles());
- }
-
- public function testListFilesSkipsNonFileEntries(): void
- {
- $a = $this->createMock(ISimpleFile::class);
- $bogus = new \stdClass();
- $this->appData->method('getFolder')->willReturn($this->folder);
- $this->folder->method('getDirectoryListing')->willReturn([$a, $bogus]);
-
- $this->assertSame([$a], $this->service->listFiles());
- }
-
- /**
- * @dataProvider contentTypeProvider
- */
- public function testContentTypeForFilename(string $filename, string $expected): void
- {
- $this->assertSame($expected, $this->service->contentTypeForFilename(filename: $filename));
- }
-
- /**
- * @return array>
- */
- public static function contentTypeProvider(): array
- {
- return [
- 'png lowercase' => ['resource_a.png', 'image/png'],
- 'jpg lowercase' => ['resource_a.jpg', 'image/jpeg'],
- 'jpeg lowercase' => ['resource_a.jpeg', 'image/jpeg'],
- 'gif lowercase' => ['resource_a.gif', 'image/gif'],
- 'svg lowercase' => ['resource_a.svg', 'image/svg+xml'],
- 'webp lowercase' => ['resource_a.webp', 'image/webp'],
- 'png uppercase' => ['resource_a.PNG', 'image/png'],
- 'svg uppercase' => ['resource_a.SVG', 'image/svg+xml'],
- 'unknown ext' => ['resource_a.bin', 'application/octet-stream'],
- 'no extension' => ['noext', 'application/octet-stream'],
- 'empty extension' => ['weird.', 'application/octet-stream'],
- 'dotfile' => ['.hidden', 'application/octet-stream'],
- ];
- }
-
- public function testFormatTimestampReturnsIso8601Utc(): void
- {
- // 2023-11-14T22:13:20+00:00
- $iso = $this->service->formatTimestamp(epoch: 1700000000);
- $this->assertSame('2023-11-14T22:13:20+00:00', $iso);
- }
-
- public function testFormatTimestampUsesUtcRegardlessOfPhpDefault(): void
- {
- $iso = $this->service->formatTimestamp(epoch: 0);
- $this->assertSame('1970-01-01T00:00:00+00:00', $iso);
- }
+class ResourceServeServiceTest extends TestCase {
+ private ResourceServeService $service;
+
+ /** @var IAppData&MockObject */
+ private $appData;
+
+ /** @var LoggerInterface&MockObject */
+ private $logger;
+
+ /** @var ISimpleFolder&MockObject */
+ private $folder;
+
+ protected function setUp(): void {
+ $this->appData = $this->createMock(IAppData::class);
+ $this->logger = $this->createMock(LoggerInterface::class);
+ $this->folder = $this->createMock(ISimpleFolder::class);
+
+ $this->service = new ResourceServeService(
+ appData: $this->appData,
+ logger: $this->logger,
+ );
+ }
+
+ public function testFindFileReturnsFileWhenPresent(): void {
+ $file = $this->createMock(ISimpleFile::class);
+ $this->appData->method('getFolder')
+ ->with(ResourceService::FOLDER)->willReturn($this->folder);
+ $this->folder->method('getFile')->with('resource_abc.png')->willReturn($file);
+
+ $this->assertSame($file, $this->service->findFile(filename: 'resource_abc.png'));
+ }
+
+ public function testFindFileReturnsNullWhenFolderMissing(): void {
+ $this->appData->method('getFolder')
+ ->willThrowException(new NotFoundException());
+
+ $this->assertNull($this->service->findFile(filename: 'whatever.png'));
+ }
+
+ public function testFindFileReturnsNullWhenFileMissing(): void {
+ $this->appData->method('getFolder')->willReturn($this->folder);
+ $this->folder->method('getFile')
+ ->willThrowException(new NotFoundException());
+
+ $this->assertNull($this->service->findFile(filename: 'gone.png'));
+ }
+
+ public function testFindFileReturnsNullOnUnexpectedException(): void {
+ $this->appData->method('getFolder')
+ ->willThrowException(new \RuntimeException('boom'));
+ $this->logger->expects($this->once())->method('warning');
+
+ $this->assertNull($this->service->findFile(filename: 'whatever.png'));
+ }
+
+ public function testListFilesReturnsAllSimpleFiles(): void {
+ $a = $this->createMock(ISimpleFile::class);
+ $b = $this->createMock(ISimpleFile::class);
+ $this->appData->method('getFolder')->willReturn($this->folder);
+ $this->folder->method('getDirectoryListing')->willReturn([$a, $b]);
+
+ $this->assertSame([$a, $b], $this->service->listFiles());
+ }
+
+ public function testListFilesReturnsEmptyArrayWhenFolderMissing(): void {
+ $this->appData->method('getFolder')
+ ->willThrowException(new NotFoundException());
+
+ $this->assertSame([], $this->service->listFiles());
+ }
+
+ public function testListFilesReturnsEmptyArrayOnUnexpectedException(): void {
+ $this->appData->method('getFolder')
+ ->willThrowException(new \RuntimeException('disk failure'));
+ $this->logger->expects($this->once())->method('warning');
+
+ $this->assertSame([], $this->service->listFiles());
+ }
+
+ public function testListFilesSkipsNonFileEntries(): void {
+ $a = $this->createMock(ISimpleFile::class);
+ $bogus = new \stdClass();
+ $this->appData->method('getFolder')->willReturn($this->folder);
+ $this->folder->method('getDirectoryListing')->willReturn([$a, $bogus]);
+
+ $this->assertSame([$a], $this->service->listFiles());
+ }
+
+ /**
+ * @dataProvider contentTypeProvider
+ */
+ public function testContentTypeForFilename(string $filename, string $expected): void {
+ $this->assertSame($expected, $this->service->contentTypeForFilename(filename: $filename));
+ }
+
+ /**
+ * @return array>
+ */
+ public static function contentTypeProvider(): array {
+ return [
+ 'png lowercase' => ['resource_a.png', 'image/png'],
+ 'jpg lowercase' => ['resource_a.jpg', 'image/jpeg'],
+ 'jpeg lowercase' => ['resource_a.jpeg', 'image/jpeg'],
+ 'gif lowercase' => ['resource_a.gif', 'image/gif'],
+ 'svg lowercase' => ['resource_a.svg', 'image/svg+xml'],
+ 'webp lowercase' => ['resource_a.webp', 'image/webp'],
+ 'png uppercase' => ['resource_a.PNG', 'image/png'],
+ 'svg uppercase' => ['resource_a.SVG', 'image/svg+xml'],
+ 'unknown ext' => ['resource_a.bin', 'application/octet-stream'],
+ 'no extension' => ['noext', 'application/octet-stream'],
+ 'empty extension' => ['weird.', 'application/octet-stream'],
+ 'dotfile' => ['.hidden', 'application/octet-stream'],
+ ];
+ }
+
+ public function testFormatTimestampReturnsIso8601Utc(): void {
+ // 2023-11-14T22:13:20+00:00
+ $iso = $this->service->formatTimestamp(epoch: 1700000000);
+ $this->assertSame('2023-11-14T22:13:20+00:00', $iso);
+ }
+
+ public function testFormatTimestampUsesUtcRegardlessOfPhpDefault(): void {
+ $iso = $this->service->formatTimestamp(epoch: 0);
+ $this->assertSame('1970-01-01T00:00:00+00:00', $iso);
+ }
}
diff --git a/tests/Unit/Service/ResourceServiceSvgIntegrationTest.php b/tests/Unit/Service/ResourceServiceSvgIntegrationTest.php
index ab67f732..1a74dec6 100644
--- a/tests/Unit/Service/ResourceServiceSvgIntegrationTest.php
+++ b/tests/Unit/Service/ResourceServiceSvgIntegrationTest.php
@@ -38,148 +38,139 @@
use PHPUnit\Framework\MockObject\MockObject;
use PHPUnit\Framework\TestCase;
-class ResourceServiceSvgIntegrationTest extends TestCase
-{
- private ResourceService $service;
-
- /** @var IAppData&MockObject */
- private $appData;
-
- /** @var ISimpleFolder&MockObject */
- private $folder;
-
- /** Captures whatever bytes the service writes to disk. */
- private string $persistedBytes = '';
-
- protected function setUp(): void
- {
- $this->appData = $this->createMock(IAppData::class);
- $this->folder = $this->createMock(ISimpleFolder::class);
- $this->appData->method('getFolder')->willReturn($this->folder);
-
- $this->folder->method('newFile')->willReturnCallback(
- function (string $name, $content): ISimpleFile {
- $this->persistedBytes = (string) $content;
- return $this->createMock(ISimpleFile::class);
- }
- );
-
- $this->service = new ResourceService(
- appData: $this->appData,
- mimeValidator: new ImageMimeValidator(),
- svgSanitiser: new SvgSanitiser(),
- );
- }
-
- private function dataUrl(string $bytes): string
- {
- return 'data:image/svg+xml;base64,' . base64_encode($bytes);
- }
-
- public function testMaliciousSvgUploadStripsScriptAndPersists(): void
- {
- $svg = '';
-
- $result = $this->service->upload(
- base64DataUrl: $this->dataUrl($svg)
- );
-
- $this->assertStringStartsWith('/apps/launchpad/resource/resource_', $result['url']);
- $this->assertStringNotContainsString('persistedBytes);
- $this->assertStringNotContainsString('alert', $this->persistedBytes);
- $this->assertStringContainsString('persistedBytes);
- }
-
- public function testGarbagePayloadThrowsInvalidSvg(): void
- {
- $this->folder->expects($this->never())->method('newFile');
-
- $this->expectException(InvalidSvgException::class);
- $this->service->upload(
- base64DataUrl: $this->dataUrl('service->upload(
- base64DataUrl: $this->dataUrl('fail('Expected InvalidSvgException');
- } catch (InvalidSvgException $exception) {
- $this->assertSame('invalid_svg', $exception->getErrorCode());
- $this->assertSame(400, $exception->getHttpStatus());
- }
- }
-
- public function testOversizeSvgBelowCapAfterSanitisationIsAccepted(): void
- {
- // Build an SVG whose original bytes exceed 5 MB but whose
- // sanitised form (script stripped) drops below the cap. Pad
- // a stripped-out '
- . 'persistedBytes);
- }
-
- public function testNearCapCleanSvgIsAccepted(): void
- {
- // A clean 4.9 MB-ish SVG whose sanitised output is roughly the
- // same size — must succeed, well under the 5 MB cap.
- $padding = str_repeat(' ', (int) (4.8 * 1024 * 1024));
- $svg = '';
-
- $result = $this->service->upload(
- base64DataUrl: $this->dataUrl($svg)
- );
-
- $this->assertLessThan(ResourceService::MAX_BYTES, $result['size']);
- $this->assertStringContainsString('persistedBytes);
- }
-
- public function testPersistedBytesAreSanitisedNotOriginal(): void
- {
- $svg = '';
-
- $this->service->upload(
- base64DataUrl: $this->dataUrl($svg)
- );
-
- // Persisted bytes MUST NOT be byte-equal to the original.
- $this->assertNotSame($svg, $this->persistedBytes);
- $this->assertStringNotContainsString('EVIL_MARKER_42', $this->persistedBytes);
- $this->assertStringContainsString('persistedBytes);
- }
+class ResourceServiceSvgIntegrationTest extends TestCase {
+ private ResourceService $service;
+
+ /** @var IAppData&MockObject */
+ private $appData;
+
+ /** @var ISimpleFolder&MockObject */
+ private $folder;
+
+ /** Captures whatever bytes the service writes to disk. */
+ private string $persistedBytes = '';
+
+ protected function setUp(): void {
+ $this->appData = $this->createMock(IAppData::class);
+ $this->folder = $this->createMock(ISimpleFolder::class);
+ $this->appData->method('getFolder')->willReturn($this->folder);
+
+ $this->folder->method('newFile')->willReturnCallback(
+ function (string $name, $content): ISimpleFile {
+ $this->persistedBytes = (string)$content;
+ return $this->createMock(ISimpleFile::class);
+ }
+ );
+
+ $this->service = new ResourceService(
+ appData: $this->appData,
+ mimeValidator: new ImageMimeValidator(),
+ svgSanitiser: new SvgSanitiser(),
+ );
+ }
+
+ private function dataUrl(string $bytes): string {
+ return 'data:image/svg+xml;base64,' . base64_encode($bytes);
+ }
+
+ public function testMaliciousSvgUploadStripsScriptAndPersists(): void {
+ $svg = '';
+
+ $result = $this->service->upload(
+ base64DataUrl: $this->dataUrl($svg)
+ );
+
+ $this->assertStringStartsWith('/apps/launchpad/resource/resource_', $result['url']);
+ $this->assertStringNotContainsString('persistedBytes);
+ $this->assertStringNotContainsString('alert', $this->persistedBytes);
+ $this->assertStringContainsString('persistedBytes);
+ }
+
+ public function testGarbagePayloadThrowsInvalidSvg(): void {
+ $this->folder->expects($this->never())->method('newFile');
+
+ $this->expectException(InvalidSvgException::class);
+ $this->service->upload(
+ base64DataUrl: $this->dataUrl('service->upload(
+ base64DataUrl: $this->dataUrl('fail('Expected InvalidSvgException');
+ } catch (InvalidSvgException $exception) {
+ $this->assertSame('invalid_svg', $exception->getErrorCode());
+ $this->assertSame(400, $exception->getHttpStatus());
+ }
+ }
+
+ public function testOversizeSvgBelowCapAfterSanitisationIsAccepted(): void {
+ // Build an SVG whose original bytes exceed 5 MB but whose
+ // sanitised form (script stripped) drops below the cap. Pad
+ // a stripped-out '
+ . 'persistedBytes);
+ }
+
+ public function testNearCapCleanSvgIsAccepted(): void {
+ // A clean 4.9 MB-ish SVG whose sanitised output is roughly the
+ // same size — must succeed, well under the 5 MB cap.
+ $padding = str_repeat(' ', (int)(4.8 * 1024 * 1024));
+ $svg = '';
+
+ $result = $this->service->upload(
+ base64DataUrl: $this->dataUrl($svg)
+ );
+
+ $this->assertLessThan(ResourceService::MAX_BYTES, $result['size']);
+ $this->assertStringContainsString('persistedBytes);
+ }
+
+ public function testPersistedBytesAreSanitisedNotOriginal(): void {
+ $svg = '';
+
+ $this->service->upload(
+ base64DataUrl: $this->dataUrl($svg)
+ );
+
+ // Persisted bytes MUST NOT be byte-equal to the original.
+ $this->assertNotSame($svg, $this->persistedBytes);
+ $this->assertStringNotContainsString('EVIL_MARKER_42', $this->persistedBytes);
+ $this->assertStringContainsString('persistedBytes);
+ }
}
diff --git a/tests/Unit/Service/ResourceServiceTest.php b/tests/Unit/Service/ResourceServiceTest.php
index 7ea0dbb0..2b24e431 100644
--- a/tests/Unit/Service/ResourceServiceTest.php
+++ b/tests/Unit/Service/ResourceServiceTest.php
@@ -33,311 +33,289 @@
use PHPUnit\Framework\MockObject\MockObject;
use PHPUnit\Framework\TestCase;
-class ResourceServiceTest extends TestCase
-{
- private ResourceService $service;
-
- /**
- * @var IAppData&MockObject
- */
- private $appData;
-
- /**
- * @var ImageMimeValidator&MockObject
- */
- private $mimeValidator;
-
- /**
- * @var ISimpleFolder&MockObject
- */
- private $folder;
-
- protected function setUp(): void
- {
- $this->appData = $this->createMock(IAppData::class);
- $this->mimeValidator = $this->createMock(ImageMimeValidator::class);
- $this->folder = $this->createMock(ISimpleFolder::class);
-
- $this->service = new ResourceService(
- appData: $this->appData,
- mimeValidator: $this->mimeValidator,
- svgSanitiser: new SvgSanitiser(),
- );
- }
-
- /**
- * Tiny 1x1 PNG bytes (red pixel).
- */
- private function tinyPng(): string
- {
- return base64_decode(
- 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==',
- true
- );
- }
-
- /**
- * Build a base64 data URL from raw bytes and a declared type.
- */
- private function dataUrl(string $type, string $bytes): string
- {
- return 'data:image/' . $type . ';base64,' . base64_encode($bytes);
- }
-
- public function testMissingDataUrlPrefixIsRejected(): void
- {
- $this->expectException(InvalidDataUrlException::class);
- $this->service->upload(base64DataUrl: 'iVBORw0KGgo');
- }
-
- public function testEmptyInputIsRejected(): void
- {
- $this->expectException(InvalidDataUrlException::class);
- $this->service->upload(base64DataUrl: '');
- }
-
- public function testDisallowedTypeIsRejected(): void
- {
- $this->expectException(InvalidImageFormatException::class);
- $this->service->upload(
- base64DataUrl: $this->dataUrl(type: 'bmp', bytes: 'whatever')
- );
- }
-
- public function testMixedCaseDeclaredTypeIsAcceptedAndLowercased(): void
- {
- $this->mimeValidator->expects($this->once())->method('validate')
- ->with('png', $this->tinyPng());
-
- $this->folder->expects($this->once())->method('newFile')
- ->willReturnCallback(function (string $name, $content): ISimpleFile {
- $this->assertStringEndsWith('.png', $name);
- $this->assertStringStartsWith('resource_', $name);
-
- return $this->createMock(ISimpleFile::class);
- });
-
- $this->appData->expects($this->once())->method('getFolder')
- ->with(ResourceService::FOLDER)->willReturn($this->folder);
-
- $result = $this->service->upload(
- base64DataUrl: 'data:image/PNG;base64,' . base64_encode($this->tinyPng())
- );
-
- $this->assertSame('success', 'success'); // sanity
- $this->assertStringStartsWith('/apps/launchpad/resource/resource_', $result['url']);
- $this->assertStringEndsWith('.png', $result['url']);
- $this->assertSame(strlen($this->tinyPng()), $result['size']);
- }
-
- public function testSvgPlusXmlNormalisesToSvg(): void
- {
- $svg = '';
- $this->mimeValidator->expects($this->once())->method('validate')
- ->with('svg', $svg);
-
- $this->folder->method('newFile')
- ->willReturnCallback(function (string $name): ISimpleFile {
- $this->assertStringEndsWith('.svg', $name);
- return $this->createMock(ISimpleFile::class);
- });
-
- $this->appData->method('getFolder')->willReturn($this->folder);
-
- $result = $this->service->upload(
- base64DataUrl: $this->dataUrl(type: 'svg+xml', bytes: $svg)
- );
-
- $this->assertStringEndsWith('.svg', $result['name']);
- }
-
- public function testOversizePayloadIsRejectedBeforeValidator(): void
- {
- // 6 MB blob.
- $oversize = str_repeat('A', (6 * 1024 * 1024));
- $this->mimeValidator->expects($this->never())->method('validate');
- $this->appData->expects($this->never())->method('getFolder');
-
- $this->expectException(FileTooLargeException::class);
- $this->service->upload(
- base64DataUrl: $this->dataUrl(type: 'png', bytes: $oversize)
- );
- }
-
- public function testSizeAtCapIsAccepted(): void
- {
- // Exactly 5 MB → allowed (cap is "exceeds", not "equals").
- $atCap = str_repeat('A', (5 * 1024 * 1024));
- $this->mimeValidator->expects($this->once())->method('validate');
- $this->folder->method('newFile')
- ->willReturn($this->createMock(ISimpleFile::class));
- $this->appData->method('getFolder')->willReturn($this->folder);
-
- $result = $this->service->upload(
- base64DataUrl: $this->dataUrl(type: 'png', bytes: $atCap)
- );
-
- $this->assertSame((5 * 1024 * 1024), $result['size']);
- }
-
- public function testMimeMismatchBubblesUp(): void
- {
- $this->mimeValidator->method('validate')
- ->willThrowException(new MimeMismatchException());
-
- $this->expectException(MimeMismatchException::class);
- $this->service->upload(
- base64DataUrl: $this->dataUrl(type: 'png', bytes: 'whatever')
- );
- }
-
- public function testFolderAutoCreatedWhenMissing(): void
- {
- $this->mimeValidator->method('validate');
- $this->appData->expects($this->once())->method('getFolder')
- ->with(ResourceService::FOLDER)
- ->willThrowException(new NotFoundException());
- $this->appData->expects($this->once())->method('newFolder')
- ->with(ResourceService::FOLDER)->willReturn($this->folder);
- $this->folder->expects($this->once())->method('newFile')
- ->willReturn($this->createMock(ISimpleFile::class));
-
- $result = $this->service->upload(
- base64DataUrl: $this->dataUrl(type: 'png', bytes: $this->tinyPng())
- );
-
- $this->assertStringStartsWith('resource_', $result['name']);
- }
-
- public function testStorageFailureIsWrapped(): void
- {
- $this->mimeValidator->method('validate');
- $this->appData->method('getFolder')->willReturn($this->folder);
- $this->folder->method('newFile')
- ->willThrowException(new NotPermittedException('disk full'));
-
- $this->expectException(StorageFailureException::class);
- $this->service->upload(
- base64DataUrl: $this->dataUrl(type: 'png', bytes: $this->tinyPng())
- );
- }
-
- public function testFilenameMatchesSpecPattern(): void
- {
- $this->mimeValidator->method('validate');
- $this->appData->method('getFolder')->willReturn($this->folder);
- $this->folder->method('newFile')
- ->willReturn($this->createMock(ISimpleFile::class));
-
- $result = $this->service->upload(
- base64DataUrl: $this->dataUrl(type: 'png', bytes: $this->tinyPng())
- );
-
- // resource_.png — uniqid with
- // more_entropy=true returns hex + dot + decimal.
- $this->assertMatchesRegularExpression(
- '#^resource_[a-f0-9.]+\.(jpeg|jpg|png|gif|svg|webp)$#',
- $result['name']
- );
- }
-
- // ---------------------------------------------------------------
- // uploadRaw() — raw multipart path (REQ-RES-014).
- // ---------------------------------------------------------------
-
- public function testUploadRawStoresBytesAndReturnsEnvelope(): void
- {
- $this->mimeValidator->expects($this->once())->method('validate')
- ->with('png', $this->tinyPng());
- $this->appData->method('getFolder')->willReturn($this->folder);
- $this->folder->expects($this->once())->method('newFile')
- ->willReturnCallback(function (string $name): ISimpleFile {
- $this->assertStringStartsWith('resource_', $name);
- $this->assertStringEndsWith('.png', $name);
- return $this->createMock(ISimpleFile::class);
- });
-
- $result = $this->service->uploadRaw(bytes: $this->tinyPng(), declaredType: 'png');
-
- $this->assertStringStartsWith('/apps/launchpad/resource/resource_', $result['url']);
- $this->assertStringEndsWith('.png', $result['url']);
- $this->assertSame(strlen($this->tinyPng()), $result['size']);
- }
-
- public function testUploadRawNormalisesUppercaseAndSvgXmlType(): void
- {
- $svg = '';
- $this->mimeValidator->method('validate');
- $this->appData->method('getFolder')->willReturn($this->folder);
- $this->folder->method('newFile')
- ->willReturnCallback(function (string $name): ISimpleFile {
- $this->assertStringEndsWith('.svg', $name);
- return $this->createMock(ISimpleFile::class);
- });
-
- // 'SVG+XML' (uppercase, +xml suffix) must normalise to 'svg'.
- $result = $this->service->uploadRaw(bytes: $svg, declaredType: 'SVG+XML');
-
- $this->assertStringEndsWith('.svg', $result['name']);
- }
-
- public function testUploadRawEmptyBytesRejected(): void
- {
- $this->expectException(InvalidDataUrlException::class);
- $this->appData->expects($this->never())->method('getFolder');
- $this->service->uploadRaw(bytes: '', declaredType: 'png');
- }
-
- public function testUploadRawDisallowedTypeRejected(): void
- {
- $this->expectException(InvalidImageFormatException::class);
- $this->appData->expects($this->never())->method('getFolder');
- $this->service->uploadRaw(bytes: 'whatever', declaredType: 'bmp');
- }
-
- public function testUploadRawOversizeRejectedBeforeValidator(): void
- {
- $oversize = str_repeat('A', (6 * 1024 * 1024));
- $this->mimeValidator->expects($this->never())->method('validate');
- $this->appData->expects($this->never())->method('getFolder');
-
- $this->expectException(FileTooLargeException::class);
- $this->service->uploadRaw(bytes: $oversize, declaredType: 'png');
- }
-
- public function testUploadRawSanitisesSvgScriptBeforePersisting(): void
- {
- // Uses the real SvgSanitiser (wired in setUp): a assertStringContainsString('mimeValidator->method('validate')
- ->willThrowException(new MimeMismatchException());
- $this->appData->expects($this->never())->method('getFolder');
-
- $this->expectException(MimeMismatchException::class);
- $this->service->uploadRaw(bytes: $this->tinyPng(), declaredType: 'webp');
- }
+class ResourceServiceTest extends TestCase {
+ private ResourceService $service;
+
+ /**
+ * @var IAppData&MockObject
+ */
+ private $appData;
+
+ /**
+ * @var ImageMimeValidator&MockObject
+ */
+ private $mimeValidator;
+
+ /**
+ * @var ISimpleFolder&MockObject
+ */
+ private $folder;
+
+ protected function setUp(): void {
+ $this->appData = $this->createMock(IAppData::class);
+ $this->mimeValidator = $this->createMock(ImageMimeValidator::class);
+ $this->folder = $this->createMock(ISimpleFolder::class);
+
+ $this->service = new ResourceService(
+ appData: $this->appData,
+ mimeValidator: $this->mimeValidator,
+ svgSanitiser: new SvgSanitiser(),
+ );
+ }
+
+ /**
+ * Tiny 1x1 PNG bytes (red pixel).
+ */
+ private function tinyPng(): string {
+ return base64_decode(
+ 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==',
+ true
+ );
+ }
+
+ /**
+ * Build a base64 data URL from raw bytes and a declared type.
+ */
+ private function dataUrl(string $type, string $bytes): string {
+ return 'data:image/' . $type . ';base64,' . base64_encode($bytes);
+ }
+
+ public function testMissingDataUrlPrefixIsRejected(): void {
+ $this->expectException(InvalidDataUrlException::class);
+ $this->service->upload(base64DataUrl: 'iVBORw0KGgo');
+ }
+
+ public function testEmptyInputIsRejected(): void {
+ $this->expectException(InvalidDataUrlException::class);
+ $this->service->upload(base64DataUrl: '');
+ }
+
+ public function testDisallowedTypeIsRejected(): void {
+ $this->expectException(InvalidImageFormatException::class);
+ $this->service->upload(
+ base64DataUrl: $this->dataUrl(type: 'bmp', bytes: 'whatever')
+ );
+ }
+
+ public function testMixedCaseDeclaredTypeIsAcceptedAndLowercased(): void {
+ $this->mimeValidator->expects($this->once())->method('validate')
+ ->with('png', $this->tinyPng());
+
+ $this->folder->expects($this->once())->method('newFile')
+ ->willReturnCallback(function (string $name, $content): ISimpleFile {
+ $this->assertStringEndsWith('.png', $name);
+ $this->assertStringStartsWith('resource_', $name);
+
+ return $this->createMock(ISimpleFile::class);
+ });
+
+ $this->appData->expects($this->once())->method('getFolder')
+ ->with(ResourceService::FOLDER)->willReturn($this->folder);
+
+ $result = $this->service->upload(
+ base64DataUrl: 'data:image/PNG;base64,' . base64_encode($this->tinyPng())
+ );
+
+ $this->assertSame('success', 'success'); // sanity
+ $this->assertStringStartsWith('/apps/launchpad/resource/resource_', $result['url']);
+ $this->assertStringEndsWith('.png', $result['url']);
+ $this->assertSame(strlen($this->tinyPng()), $result['size']);
+ }
+
+ public function testSvgPlusXmlNormalisesToSvg(): void {
+ $svg = '';
+ $this->mimeValidator->expects($this->once())->method('validate')
+ ->with('svg', $svg);
+
+ $this->folder->method('newFile')
+ ->willReturnCallback(function (string $name): ISimpleFile {
+ $this->assertStringEndsWith('.svg', $name);
+ return $this->createMock(ISimpleFile::class);
+ });
+
+ $this->appData->method('getFolder')->willReturn($this->folder);
+
+ $result = $this->service->upload(
+ base64DataUrl: $this->dataUrl(type: 'svg+xml', bytes: $svg)
+ );
+
+ $this->assertStringEndsWith('.svg', $result['name']);
+ }
+
+ public function testOversizePayloadIsRejectedBeforeValidator(): void {
+ // 6 MB blob.
+ $oversize = str_repeat('A', (6 * 1024 * 1024));
+ $this->mimeValidator->expects($this->never())->method('validate');
+ $this->appData->expects($this->never())->method('getFolder');
+
+ $this->expectException(FileTooLargeException::class);
+ $this->service->upload(
+ base64DataUrl: $this->dataUrl(type: 'png', bytes: $oversize)
+ );
+ }
+
+ public function testSizeAtCapIsAccepted(): void {
+ // Exactly 5 MB → allowed (cap is "exceeds", not "equals").
+ $atCap = str_repeat('A', (5 * 1024 * 1024));
+ $this->mimeValidator->expects($this->once())->method('validate');
+ $this->folder->method('newFile')
+ ->willReturn($this->createMock(ISimpleFile::class));
+ $this->appData->method('getFolder')->willReturn($this->folder);
+
+ $result = $this->service->upload(
+ base64DataUrl: $this->dataUrl(type: 'png', bytes: $atCap)
+ );
+
+ $this->assertSame((5 * 1024 * 1024), $result['size']);
+ }
+
+ public function testMimeMismatchBubblesUp(): void {
+ $this->mimeValidator->method('validate')
+ ->willThrowException(new MimeMismatchException());
+
+ $this->expectException(MimeMismatchException::class);
+ $this->service->upload(
+ base64DataUrl: $this->dataUrl(type: 'png', bytes: 'whatever')
+ );
+ }
+
+ public function testFolderAutoCreatedWhenMissing(): void {
+ $this->mimeValidator->method('validate');
+ $this->appData->expects($this->once())->method('getFolder')
+ ->with(ResourceService::FOLDER)
+ ->willThrowException(new NotFoundException());
+ $this->appData->expects($this->once())->method('newFolder')
+ ->with(ResourceService::FOLDER)->willReturn($this->folder);
+ $this->folder->expects($this->once())->method('newFile')
+ ->willReturn($this->createMock(ISimpleFile::class));
+
+ $result = $this->service->upload(
+ base64DataUrl: $this->dataUrl(type: 'png', bytes: $this->tinyPng())
+ );
+
+ $this->assertStringStartsWith('resource_', $result['name']);
+ }
+
+ public function testStorageFailureIsWrapped(): void {
+ $this->mimeValidator->method('validate');
+ $this->appData->method('getFolder')->willReturn($this->folder);
+ $this->folder->method('newFile')
+ ->willThrowException(new NotPermittedException('disk full'));
+
+ $this->expectException(StorageFailureException::class);
+ $this->service->upload(
+ base64DataUrl: $this->dataUrl(type: 'png', bytes: $this->tinyPng())
+ );
+ }
+
+ public function testFilenameMatchesSpecPattern(): void {
+ $this->mimeValidator->method('validate');
+ $this->appData->method('getFolder')->willReturn($this->folder);
+ $this->folder->method('newFile')
+ ->willReturn($this->createMock(ISimpleFile::class));
+
+ $result = $this->service->upload(
+ base64DataUrl: $this->dataUrl(type: 'png', bytes: $this->tinyPng())
+ );
+
+ // resource_.png — uniqid with
+ // more_entropy=true returns hex + dot + decimal.
+ $this->assertMatchesRegularExpression(
+ '#^resource_[a-f0-9.]+\.(jpeg|jpg|png|gif|svg|webp)$#',
+ $result['name']
+ );
+ }
+
+ // ---------------------------------------------------------------
+ // uploadRaw() — raw multipart path (REQ-RES-014).
+ // ---------------------------------------------------------------
+
+ public function testUploadRawStoresBytesAndReturnsEnvelope(): void {
+ $this->mimeValidator->expects($this->once())->method('validate')
+ ->with('png', $this->tinyPng());
+ $this->appData->method('getFolder')->willReturn($this->folder);
+ $this->folder->expects($this->once())->method('newFile')
+ ->willReturnCallback(function (string $name): ISimpleFile {
+ $this->assertStringStartsWith('resource_', $name);
+ $this->assertStringEndsWith('.png', $name);
+ return $this->createMock(ISimpleFile::class);
+ });
+
+ $result = $this->service->uploadRaw(bytes: $this->tinyPng(), declaredType: 'png');
+
+ $this->assertStringStartsWith('/apps/launchpad/resource/resource_', $result['url']);
+ $this->assertStringEndsWith('.png', $result['url']);
+ $this->assertSame(strlen($this->tinyPng()), $result['size']);
+ }
+
+ public function testUploadRawNormalisesUppercaseAndSvgXmlType(): void {
+ $svg = '';
+ $this->mimeValidator->method('validate');
+ $this->appData->method('getFolder')->willReturn($this->folder);
+ $this->folder->method('newFile')
+ ->willReturnCallback(function (string $name): ISimpleFile {
+ $this->assertStringEndsWith('.svg', $name);
+ return $this->createMock(ISimpleFile::class);
+ });
+
+ // 'SVG+XML' (uppercase, +xml suffix) must normalise to 'svg'.
+ $result = $this->service->uploadRaw(bytes: $svg, declaredType: 'SVG+XML');
+
+ $this->assertStringEndsWith('.svg', $result['name']);
+ }
+
+ public function testUploadRawEmptyBytesRejected(): void {
+ $this->expectException(InvalidDataUrlException::class);
+ $this->appData->expects($this->never())->method('getFolder');
+ $this->service->uploadRaw(bytes: '', declaredType: 'png');
+ }
+
+ public function testUploadRawDisallowedTypeRejected(): void {
+ $this->expectException(InvalidImageFormatException::class);
+ $this->appData->expects($this->never())->method('getFolder');
+ $this->service->uploadRaw(bytes: 'whatever', declaredType: 'bmp');
+ }
+
+ public function testUploadRawOversizeRejectedBeforeValidator(): void {
+ $oversize = str_repeat('A', (6 * 1024 * 1024));
+ $this->mimeValidator->expects($this->never())->method('validate');
+ $this->appData->expects($this->never())->method('getFolder');
+
+ $this->expectException(FileTooLargeException::class);
+ $this->service->uploadRaw(bytes: $oversize, declaredType: 'png');
+ }
+
+ public function testUploadRawSanitisesSvgScriptBeforePersisting(): void {
+ // Uses the real SvgSanitiser (wired in setUp): a assertStringContainsString('mimeValidator->method('validate')
+ ->willThrowException(new MimeMismatchException());
+ $this->appData->expects($this->never())->method('getFolder');
+
+ $this->expectException(MimeMismatchException::class);
+ $this->service->uploadRaw(bytes: $this->tinyPng(), declaredType: 'webp');
+ }
}
diff --git a/tests/Unit/Service/RoleFeaturePermissionServiceTest.php b/tests/Unit/Service/RoleFeaturePermissionServiceTest.php
index 6a54506d..abf20fae 100644
--- a/tests/Unit/Service/RoleFeaturePermissionServiceTest.php
+++ b/tests/Unit/Service/RoleFeaturePermissionServiceTest.php
@@ -37,263 +37,251 @@
use OCP\IUserManager;
use PHPUnit\Framework\TestCase;
-class RoleFeaturePermissionServiceTest extends TestCase
-{
- private RoleFeaturePermissionService $service;
-
- private RoleFeaturePermissionMapper $permMapper;
-
- private RoleLayoutDefaultMapper $defaultMapper;
-
- private WidgetPlacementMapper $placementMapper;
-
- private AdminSettingsService $adminSettings;
-
- private AdminTemplateService $adminTemplateService;
-
- private IUserManager $userManager;
-
- private IGroupManager $groupManager;
-
- protected function setUp(): void
- {
- $this->permMapper = $this->createMock(originalClassName: RoleFeaturePermissionMapper::class);
- $this->defaultMapper = $this->createMock(originalClassName: RoleLayoutDefaultMapper::class);
- $this->placementMapper = $this->createMock(originalClassName: WidgetPlacementMapper::class);
- $this->adminSettings = $this->createMock(originalClassName: AdminSettingsService::class);
- $this->adminTemplateService = $this->createMock(originalClassName: AdminTemplateService::class);
- $this->userManager = $this->createMock(originalClassName: IUserManager::class);
- $this->groupManager = $this->createMock(originalClassName: IGroupManager::class);
-
- // Default: the user under test is NOT an admin so the existing
- // role-resolution assertions exercise the group-matching path.
- $this->groupManager->method('isAdmin')->willReturn(false);
-
- $this->service = new RoleFeaturePermissionService(
- permissionMapper: $this->permMapper,
- defaultMapper: $this->defaultMapper,
- placementMapper: $this->placementMapper,
- adminSettings: $this->adminSettings,
- adminTemplateService: $this->adminTemplateService,
- userManager: $this->userManager,
- groupManager: $this->groupManager,
- );
- }//end setUp()
-
- /**
- * Build a RoleFeaturePermission entity from arrays.
- */
- private function makePerm(
- string $groupId,
- array $allowed,
- array $denied = []
- ): RoleFeaturePermission {
- $entity = new RoleFeaturePermission();
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $entity->setName('perm-' . $groupId);
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $entity->setGroupId($groupId);
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $entity->setAllowedWidgets(json_encode(value: $allowed));
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $entity->setDeniedWidgets(json_encode(value: $denied));
- return $entity;
- }//end makePerm()
-
- /**
- * Mock IUserManager + AdminTemplateService so the user is in a list
- * of groups. The service calls
- * {@see AdminTemplateService::getUserGroupIdsFor()} to honour the
- * REQ-TMPL-013 routing-resolver invariant — group lookups never
- * touch IGroupManager directly.
- */
- private function withUserGroups(string $userId, array $groupIds): void
- {
- $user = $this->createMock(originalClassName: IUser::class);
- $this->userManager->method('get')
- ->willReturn(value: $user);
- $this->adminTemplateService->method('getUserGroupIdsFor')
- ->willReturn(value: $groupIds);
- }//end withUserGroups()
-
- public function testNoRestrictionConfiguredReturnsNull(): void
- {
- $this->withUserGroups(userId: 'alice', groupIds: ['employees']);
- $this->adminSettings->method('getGroupOrder')
- ->willReturn(value: ['employees']);
- $this->permMapper->method('findByGroupIds')
- ->willReturn(value: []);
- $this->permMapper->method('findByGroupId')
- ->will($this->throwException(exception: new DoesNotExistException(msg: 'no row')));
-
- $result = $this->service->getAllowedWidgetIds(userId: 'alice');
- $this->assertNull(actual: $result);
- }//end testNoRestrictionConfiguredReturnsNull()
-
- public function testSingleGroupReturnsAllowedSet(): void
- {
- $this->withUserGroups(userId: 'alice', groupIds: ['employees']);
- $this->adminSettings->method('getGroupOrder')
- ->willReturn(value: ['employees', 'managers']);
- $this->permMapper->method('findByGroupIds')
- ->willReturn(value: [
- $this->makePerm(groupId: 'employees', allowed: ['activity', 'recommendations']),
- ]);
-
- $result = $this->service->getAllowedWidgetIds(userId: 'alice');
- $this->assertSame(expected: ['activity', 'recommendations'], actual: $result);
- }//end testSingleGroupReturnsAllowedSet()
-
- public function testMultiGroupUnionWidens(): void
- {
- $this->withUserGroups(userId: 'alice', groupIds: ['employees', 'managers']);
- $this->adminSettings->method('getGroupOrder')
- ->willReturn(value: ['employees', 'managers']);
- $this->permMapper->method('findByGroupIds')
- ->willReturn(value: [
- $this->makePerm(groupId: 'employees', allowed: ['activity']),
- $this->makePerm(groupId: 'managers', allowed: ['analytics']),
- ]);
-
- $result = $this->service->getAllowedWidgetIds(userId: 'alice');
- $this->assertSame(expected: ['activity', 'analytics'], actual: $result);
- }//end testMultiGroupUnionWidens()
-
- public function testDenyWinsOverAllow(): void
- {
- $this->withUserGroups(userId: 'alice', groupIds: ['employees', 'security']);
- $this->adminSettings->method('getGroupOrder')
- ->willReturn(value: ['employees', 'security']);
- $this->permMapper->method('findByGroupIds')
- ->willReturn(value: [
- $this->makePerm(groupId: 'employees', allowed: ['activity', 'analytics']),
- $this->makePerm(groupId: 'security', allowed: [], denied: ['analytics']),
- ]);
-
- $result = $this->service->getAllowedWidgetIds(userId: 'alice');
- $this->assertSame(expected: ['activity'], actual: $result);
- }//end testDenyWinsOverAllow()
-
- public function testFallbackToDefaultGroupWhenNoGroupOrderMatch(): void
- {
- $this->withUserGroups(userId: 'alice', groupIds: ['unmapped']);
- $this->adminSettings->method('getGroupOrder')
- ->willReturn(value: []);
- $this->permMapper->method('findByGroupIds')
- ->willReturn(value: []);
- $this->permMapper->method('findByGroupId')
- ->with($this->equalTo(value: RoleFeaturePermission::GROUP_DEFAULT))
- ->willReturn(value: $this->makePerm(groupId: 'default', allowed: ['recommendations']));
-
- $result = $this->service->getAllowedWidgetIds(userId: 'alice');
- $this->assertSame(expected: ['recommendations'], actual: $result);
- }//end testFallbackToDefaultGroupWhenNoGroupOrderMatch()
-
- public function testIsWidgetAllowedTrueWhenUnconfigured(): void
- {
- $this->withUserGroups(userId: 'alice', groupIds: []);
- $this->permMapper->method('findByGroupId')
- ->will($this->throwException(exception: new DoesNotExistException(msg: 'no row')));
-
- $this->assertTrue(condition: $this->service->isWidgetAllowed(
- userId: 'alice',
- widgetId: 'whatever'
- ));
- }//end testIsWidgetAllowedTrueWhenUnconfigured()
-
- /**
- * Admin break-glass: a Nextcloud admin is never restricted by the
- * role-feature-permission allow-list, even when a restrictive `default`
- * row exists (the bug — admins were falling back to the demo-seeded
- * `default` row and getting 403 on their own dashboard).
- */
- public function testAdminBypassesDefaultRestriction(): void
- {
- $admin = $this->createMock(originalClassName: IGroupManager::class);
- $admin->method('isAdmin')->willReturn(true);
-
- $service = new RoleFeaturePermissionService(
- permissionMapper: $this->permMapper,
- defaultMapper: $this->defaultMapper,
- placementMapper: $this->placementMapper,
- adminSettings: $this->adminSettings,
- adminTemplateService: $this->adminTemplateService,
- userManager: $this->userManager,
- groupManager: $admin,
- );
-
- // Even if a restrictive `default` row would be returned, the admin
- // short-circuit must run first: getAllowedWidgetIds → null (no
- // restriction) and isWidgetAllowed → true for any widget.
- $this->permMapper->method('findByGroupId')
- ->willReturn(value: $this->makePerm(groupId: 'default', allowed: ['activity']));
-
- $this->assertNull(actual: $service->getAllowedWidgetIds(userId: 'admin'));
- $this->assertTrue(condition: $service->isWidgetAllowed(
- userId: 'admin',
- widgetId: 'links'
- ));
- }//end testAdminBypassesDefaultRestriction()
-
- public function testSeedLayoutNoOpWhenDashboardHasPlacements(): void
- {
- $dashboard = new Dashboard();
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $dashboard->setId(42);
- $this->placementMapper->method('findByDashboardId')
- ->willReturn(value: ['existing-placement']);
-
- // No mapper / group manager calls expected because the guard fires first.
- $this->defaultMapper->expects($this->never())
- ->method('findByGroupId');
-
- $created = $this->service->seedLayoutFromRoleDefaults(
- userId: 'alice',
- dashboard: $dashboard
- );
- $this->assertSame(expected: 0, actual: $created);
- }//end testSeedLayoutNoOpWhenDashboardHasPlacements()
-
- public function testSeedLayoutCreatesPlacementsWhenEmpty(): void
- {
- $dashboard = new Dashboard();
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $dashboard->setId(99);
-
- $this->placementMapper->method('findByDashboardId')
- ->willReturn(value: []);
- $this->withUserGroups(userId: 'alice', groupIds: ['managers']);
- $this->adminSettings->method('getGroupOrder')
- ->willReturn(value: ['managers']);
-
- $rld = new RoleLayoutDefault();
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $rld->setName('manager-activity');
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $rld->setGroupId('managers');
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $rld->setWidgetId('activity');
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $rld->setGridX(0);
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $rld->setGridY(0);
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $rld->setGridWidth(6);
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $rld->setGridHeight(5);
- // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
- $rld->setSortOrder(0);
-
- $this->defaultMapper->method('findByGroupId')
- ->willReturn(value: [$rld]);
-
- $this->placementMapper->expects($this->once())
- ->method('insert');
-
- $created = $this->service->seedLayoutFromRoleDefaults(
- userId: 'alice',
- dashboard: $dashboard
- );
- $this->assertSame(expected: 1, actual: $created);
- }//end testSeedLayoutCreatesPlacementsWhenEmpty()
+class RoleFeaturePermissionServiceTest extends TestCase {
+ private RoleFeaturePermissionService $service;
+
+ private RoleFeaturePermissionMapper $permMapper;
+
+ private RoleLayoutDefaultMapper $defaultMapper;
+
+ private WidgetPlacementMapper $placementMapper;
+
+ private AdminSettingsService $adminSettings;
+
+ private AdminTemplateService $adminTemplateService;
+
+ private IUserManager $userManager;
+
+ private IGroupManager $groupManager;
+
+ protected function setUp(): void {
+ $this->permMapper = $this->createMock(originalClassName: RoleFeaturePermissionMapper::class);
+ $this->defaultMapper = $this->createMock(originalClassName: RoleLayoutDefaultMapper::class);
+ $this->placementMapper = $this->createMock(originalClassName: WidgetPlacementMapper::class);
+ $this->adminSettings = $this->createMock(originalClassName: AdminSettingsService::class);
+ $this->adminTemplateService = $this->createMock(originalClassName: AdminTemplateService::class);
+ $this->userManager = $this->createMock(originalClassName: IUserManager::class);
+ $this->groupManager = $this->createMock(originalClassName: IGroupManager::class);
+
+ // Default: the user under test is NOT an admin so the existing
+ // role-resolution assertions exercise the group-matching path.
+ $this->groupManager->method('isAdmin')->willReturn(false);
+
+ $this->service = new RoleFeaturePermissionService(
+ permissionMapper: $this->permMapper,
+ defaultMapper: $this->defaultMapper,
+ placementMapper: $this->placementMapper,
+ adminSettings: $this->adminSettings,
+ adminTemplateService: $this->adminTemplateService,
+ userManager: $this->userManager,
+ groupManager: $this->groupManager,
+ );
+ }//end setUp()
+
+ /**
+ * Build a RoleFeaturePermission entity from arrays.
+ */
+ private function makePerm(
+ string $groupId,
+ array $allowed,
+ array $denied = [],
+ ): RoleFeaturePermission {
+ $entity = new RoleFeaturePermission();
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $entity->setName('perm-' . $groupId);
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $entity->setGroupId($groupId);
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $entity->setAllowedWidgets(json_encode(value: $allowed));
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $entity->setDeniedWidgets(json_encode(value: $denied));
+ return $entity;
+ }//end makePerm()
+
+ /**
+ * Mock IUserManager + AdminTemplateService so the user is in a list
+ * of groups. The service calls
+ * {@see AdminTemplateService::getUserGroupIdsFor()} to honour the
+ * REQ-TMPL-013 routing-resolver invariant — group lookups never
+ * touch IGroupManager directly.
+ */
+ private function withUserGroups(string $userId, array $groupIds): void {
+ $user = $this->createMock(originalClassName: IUser::class);
+ $this->userManager->method('get')
+ ->willReturn(value: $user);
+ $this->adminTemplateService->method('getUserGroupIdsFor')
+ ->willReturn(value: $groupIds);
+ }//end withUserGroups()
+
+ public function testNoRestrictionConfiguredReturnsNull(): void {
+ $this->withUserGroups(userId: 'alice', groupIds: ['employees']);
+ $this->adminSettings->method('getGroupOrder')
+ ->willReturn(value: ['employees']);
+ $this->permMapper->method('findByGroupIds')
+ ->willReturn(value: []);
+ $this->permMapper->method('findByGroupId')
+ ->will($this->throwException(exception: new DoesNotExistException(msg: 'no row')));
+
+ $result = $this->service->getAllowedWidgetIds(userId: 'alice');
+ $this->assertNull(actual: $result);
+ }//end testNoRestrictionConfiguredReturnsNull()
+
+ public function testSingleGroupReturnsAllowedSet(): void {
+ $this->withUserGroups(userId: 'alice', groupIds: ['employees']);
+ $this->adminSettings->method('getGroupOrder')
+ ->willReturn(value: ['employees', 'managers']);
+ $this->permMapper->method('findByGroupIds')
+ ->willReturn(value: [
+ $this->makePerm(groupId: 'employees', allowed: ['activity', 'recommendations']),
+ ]);
+
+ $result = $this->service->getAllowedWidgetIds(userId: 'alice');
+ $this->assertSame(expected: ['activity', 'recommendations'], actual: $result);
+ }//end testSingleGroupReturnsAllowedSet()
+
+ public function testMultiGroupUnionWidens(): void {
+ $this->withUserGroups(userId: 'alice', groupIds: ['employees', 'managers']);
+ $this->adminSettings->method('getGroupOrder')
+ ->willReturn(value: ['employees', 'managers']);
+ $this->permMapper->method('findByGroupIds')
+ ->willReturn(value: [
+ $this->makePerm(groupId: 'employees', allowed: ['activity']),
+ $this->makePerm(groupId: 'managers', allowed: ['analytics']),
+ ]);
+
+ $result = $this->service->getAllowedWidgetIds(userId: 'alice');
+ $this->assertSame(expected: ['activity', 'analytics'], actual: $result);
+ }//end testMultiGroupUnionWidens()
+
+ public function testDenyWinsOverAllow(): void {
+ $this->withUserGroups(userId: 'alice', groupIds: ['employees', 'security']);
+ $this->adminSettings->method('getGroupOrder')
+ ->willReturn(value: ['employees', 'security']);
+ $this->permMapper->method('findByGroupIds')
+ ->willReturn(value: [
+ $this->makePerm(groupId: 'employees', allowed: ['activity', 'analytics']),
+ $this->makePerm(groupId: 'security', allowed: [], denied: ['analytics']),
+ ]);
+
+ $result = $this->service->getAllowedWidgetIds(userId: 'alice');
+ $this->assertSame(expected: ['activity'], actual: $result);
+ }//end testDenyWinsOverAllow()
+
+ public function testFallbackToDefaultGroupWhenNoGroupOrderMatch(): void {
+ $this->withUserGroups(userId: 'alice', groupIds: ['unmapped']);
+ $this->adminSettings->method('getGroupOrder')
+ ->willReturn(value: []);
+ $this->permMapper->method('findByGroupIds')
+ ->willReturn(value: []);
+ $this->permMapper->method('findByGroupId')
+ ->with($this->equalTo(value: RoleFeaturePermission::GROUP_DEFAULT))
+ ->willReturn(value: $this->makePerm(groupId: 'default', allowed: ['recommendations']));
+
+ $result = $this->service->getAllowedWidgetIds(userId: 'alice');
+ $this->assertSame(expected: ['recommendations'], actual: $result);
+ }//end testFallbackToDefaultGroupWhenNoGroupOrderMatch()
+
+ public function testIsWidgetAllowedTrueWhenUnconfigured(): void {
+ $this->withUserGroups(userId: 'alice', groupIds: []);
+ $this->permMapper->method('findByGroupId')
+ ->will($this->throwException(exception: new DoesNotExistException(msg: 'no row')));
+
+ $this->assertTrue(condition: $this->service->isWidgetAllowed(
+ userId: 'alice',
+ widgetId: 'whatever'
+ ));
+ }//end testIsWidgetAllowedTrueWhenUnconfigured()
+
+ /**
+ * Admin break-glass: a Nextcloud admin is never restricted by the
+ * role-feature-permission allow-list, even when a restrictive `default`
+ * row exists (the bug — admins were falling back to the demo-seeded
+ * `default` row and getting 403 on their own dashboard).
+ */
+ public function testAdminBypassesDefaultRestriction(): void {
+ $admin = $this->createMock(originalClassName: IGroupManager::class);
+ $admin->method('isAdmin')->willReturn(true);
+
+ $service = new RoleFeaturePermissionService(
+ permissionMapper: $this->permMapper,
+ defaultMapper: $this->defaultMapper,
+ placementMapper: $this->placementMapper,
+ adminSettings: $this->adminSettings,
+ adminTemplateService: $this->adminTemplateService,
+ userManager: $this->userManager,
+ groupManager: $admin,
+ );
+
+ // Even if a restrictive `default` row would be returned, the admin
+ // short-circuit must run first: getAllowedWidgetIds → null (no
+ // restriction) and isWidgetAllowed → true for any widget.
+ $this->permMapper->method('findByGroupId')
+ ->willReturn(value: $this->makePerm(groupId: 'default', allowed: ['activity']));
+
+ $this->assertNull(actual: $service->getAllowedWidgetIds(userId: 'admin'));
+ $this->assertTrue(condition: $service->isWidgetAllowed(
+ userId: 'admin',
+ widgetId: 'links'
+ ));
+ }//end testAdminBypassesDefaultRestriction()
+
+ public function testSeedLayoutNoOpWhenDashboardHasPlacements(): void {
+ $dashboard = new Dashboard();
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $dashboard->setId(42);
+ $this->placementMapper->method('findByDashboardId')
+ ->willReturn(value: ['existing-placement']);
+
+ // No mapper / group manager calls expected because the guard fires first.
+ $this->defaultMapper->expects($this->never())
+ ->method('findByGroupId');
+
+ $created = $this->service->seedLayoutFromRoleDefaults(
+ userId: 'alice',
+ dashboard: $dashboard
+ );
+ $this->assertSame(expected: 0, actual: $created);
+ }//end testSeedLayoutNoOpWhenDashboardHasPlacements()
+
+ public function testSeedLayoutCreatesPlacementsWhenEmpty(): void {
+ $dashboard = new Dashboard();
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $dashboard->setId(99);
+
+ $this->placementMapper->method('findByDashboardId')
+ ->willReturn(value: []);
+ $this->withUserGroups(userId: 'alice', groupIds: ['managers']);
+ $this->adminSettings->method('getGroupOrder')
+ ->willReturn(value: ['managers']);
+
+ $rld = new RoleLayoutDefault();
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $rld->setName('manager-activity');
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $rld->setGroupId('managers');
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $rld->setWidgetId('activity');
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $rld->setGridX(0);
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $rld->setGridY(0);
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $rld->setGridWidth(6);
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $rld->setGridHeight(5);
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $rld->setSortOrder(0);
+
+ $this->defaultMapper->method('findByGroupId')
+ ->willReturn(value: [$rld]);
+
+ $this->placementMapper->expects($this->once())
+ ->method('insert');
+
+ $created = $this->service->seedLayoutFromRoleDefaults(
+ userId: 'alice',
+ dashboard: $dashboard
+ );
+ $this->assertSame(expected: 1, actual: $created);
+ }//end testSeedLayoutCreatesPlacementsWhenEmpty()
}//end class
diff --git a/tests/Unit/Service/RoleServiceTest.php b/tests/Unit/Service/RoleServiceTest.php
index cad9cb3a..7a366267 100644
--- a/tests/Unit/Service/RoleServiceTest.php
+++ b/tests/Unit/Service/RoleServiceTest.php
@@ -39,324 +39,300 @@
* @SuppressWarnings(PHPMD.TooManyMethods)
* @SuppressWarnings(PHPMD.TooManyPublicMethods)
*/
-class RoleServiceTest extends TestCase
-{
- /** @var RoleAssignmentMapper&MockObject */
- private $mapper;
- /** @var IUserManager&MockObject */
- private $userManager;
- /** @var IGroupManager&MockObject */
- private $groupManager;
- /** @var AdminTemplateService&MockObject */
- private $adminTemplateService;
-
- private RoleService $service;
-
- protected function setUp(): void
- {
- parent::setUp();
-
- $this->mapper = $this->createMock(RoleAssignmentMapper::class);
- $this->userManager = $this->createMock(IUserManager::class);
- $this->groupManager = $this->createMock(IGroupManager::class);
- $this->adminTemplateService = $this->createMock(AdminTemplateService::class);
-
- $this->service = new RoleService(
- mapper: $this->mapper,
- userManager: $this->userManager,
- groupManager: $this->groupManager,
- adminTemplateService: $this->adminTemplateService,
- );
- }
-
- private function makeAssignment(
- ?string $userId,
- ?string $groupId,
- string $role
- ): RoleAssignment {
- $assignment = new RoleAssignment();
- $assignment->setUserId($userId);
- $assignment->setGroupId($groupId);
- $assignment->setRole($role);
- $assignment->setAssignedBy('admin-user');
- $assignment->setAssignedAt('2026-05-02T12:00:00+00:00');
- return $assignment;
- }
-
- // ==================================================================
- // Effective-role resolution (REQ-ROLE-005)
- // ==================================================================
-
- public function testNcAdminAlwaysGetsAdminRole(): void
- {
- $this->groupManager->method('isAdmin')->with('alice')->willReturn(true);
-
- // No mapper lookup is required for NC admins.
- $this->mapper->expects($this->never())->method('findByUser');
- $this->mapper->expects($this->never())->method('findByGroupIds');
-
- $this->assertSame(
- RoleAssignment::ROLE_ADMIN,
- $this->service->getEffectiveRole(userId: 'alice')
- );
- $this->assertSame(
- RoleAssignment::SOURCE_NC_ADMIN,
- $this->service->getRoleSource(userId: 'alice')
- );
- }
-
- public function testDirectUserAssignmentUsedAsIs(): void
- {
- $this->groupManager->method('isAdmin')->willReturn(false);
- $this->mapper->method('findByUser')->with('bob')->willReturn(
- [$this->makeAssignment('bob', null, RoleAssignment::ROLE_VIEWER)]
- );
-
- // Group lookups MUST be skipped per REQ-ROLE-005 step 2.
- $this->mapper->expects($this->never())->method('findByGroupIds');
- $this->adminTemplateService->expects($this->never())->method('getUserGroupIdsFor');
-
- $this->assertSame(
- RoleAssignment::ROLE_VIEWER,
- $this->service->getEffectiveRole(userId: 'bob')
- );
- }
-
- public function testDirectAssignmentBeatsHigherGroupRole(): void
- {
- // REQ-ROLE-009 scenario 1: direct viewer beats group admin.
- $this->groupManager->method('isAdmin')->willReturn(false);
- $this->mapper->method('findByUser')->with('bob')->willReturn(
- [$this->makeAssignment('bob', null, RoleAssignment::ROLE_VIEWER)]
- );
-
- $this->mapper->expects($this->never())->method('findByGroupIds');
-
- $this->assertSame(
- RoleAssignment::ROLE_VIEWER,
- $this->service->getEffectiveRole(userId: 'bob')
- );
- $this->assertSame(
- RoleAssignment::SOURCE_USER_ASSIGNED,
- $this->service->getRoleSource(userId: 'bob')
- );
- }
-
- public function testHighestGroupRoleWins(): void
- {
- $this->groupManager->method('isAdmin')->willReturn(false);
- $this->mapper->method('findByUser')->willReturn([]);
-
- $this->adminTemplateService->method('getUserGroupIdsFor')->willReturn(
- ['engineering', 'sales']
- );
-
- $this->mapper->method('findByGroupIds')->willReturn([
- $this->makeAssignment(null, 'sales', RoleAssignment::ROLE_VIEWER),
- $this->makeAssignment(null, 'engineering', RoleAssignment::ROLE_EDITOR),
- ]);
-
- $this->assertSame(
- RoleAssignment::ROLE_EDITOR,
- $this->service->getEffectiveRole(userId: 'charlie')
- );
- $this->assertSame(
- RoleAssignment::SOURCE_GROUP_ASSIGNED_PREFIX.'engineering',
- $this->service->getRoleSource(userId: 'charlie')
- );
- }
-
- public function testNoAssignmentReturnsNullRoleAndSource(): void
- {
- $this->groupManager->method('isAdmin')->willReturn(false);
- $this->mapper->method('findByUser')->willReturn([]);
- $this->adminTemplateService->method('getUserGroupIdsFor')->willReturn([]);
- $this->mapper->method('findByGroupIds')->willReturn([]);
-
- $this->assertNull($this->service->getEffectiveRole(userId: 'eve'));
- $this->assertNull($this->service->getRoleSource(userId: 'eve'));
- }
-
- // ==================================================================
- // Validation (REQ-ROLE-004)
- // ==================================================================
-
- public function testValidateRoleAcceptsKnownRoles(): void
- {
- $this->service->validateRole(role: 'admin');
- $this->service->validateRole(role: 'editor');
- $this->service->validateRole(role: 'viewer');
- $this->expectNotToPerformAssertions();
- }
-
- public function testValidateRoleRejectsUnknown(): void
- {
- $this->expectException(InvalidRoleAssignmentException::class);
- $this->service->validateRole(role: 'superuser');
- }
-
- public function testValidateTargetRequiresOneOfUserOrGroup(): void
- {
- $this->expectException(InvalidRoleAssignmentException::class);
- $this->service->validateTarget(userId: null, groupId: null);
- }
-
- public function testValidateTargetRejectsBoth(): void
- {
- $this->expectException(InvalidRoleAssignmentException::class);
- $this->service->validateTarget(userId: 'bob', groupId: 'engineering');
- }
-
- public function testValidateTargetRejectsUnknownUser(): void
- {
- $this->userManager->method('userExists')->with('ghost')->willReturn(false);
-
- $this->expectException(InvalidRoleAssignmentException::class);
- $this->service->validateTarget(userId: 'ghost', groupId: null);
- }
-
- public function testValidateTargetRejectsUnknownGroup(): void
- {
- $this->groupManager->method('groupExists')->with('phantom')->willReturn(false);
-
- $this->expectException(InvalidRoleAssignmentException::class);
- $this->service->validateTarget(userId: null, groupId: 'phantom');
- }
-
- // ==================================================================
- // Assignment CRUD (REQ-ROLE-004)
- // ==================================================================
-
- public function testAssignRolePersistsAndReturnsEntity(): void
- {
- $this->userManager->method('userExists')->with('bob')->willReturn(true);
- $this->mapper->method('findUserRole')->with('bob', 'editor')->willReturn(null);
-
- $this->mapper->expects($this->once())
- ->method('insert')
- ->willReturnCallback(static fn(RoleAssignment $a) => $a);
-
- $assignment = $this->service->assignRole(
- userId: 'bob',
- groupId: null,
- role: 'editor',
- assignedBy: 'admin-user'
- );
-
- $this->assertSame('bob', $assignment->getUserId());
- $this->assertNull($assignment->getGroupId());
- $this->assertSame('editor', $assignment->getRole());
- $this->assertSame('admin-user', $assignment->getAssignedBy());
- $this->assertNotNull($assignment->getAssignedAt());
- }
-
- public function testAssignRoleRejectsDuplicateUserRole(): void
- {
- $this->userManager->method('userExists')->with('bob')->willReturn(true);
- $existing = $this->makeAssignment('bob', null, 'editor');
- $this->mapper->method('findUserRole')->with('bob', 'editor')->willReturn($existing);
-
- $this->expectException(DuplicateRoleAssignmentException::class);
- $this->service->assignRole(
- userId: 'bob',
- groupId: null,
- role: 'editor',
- assignedBy: 'admin-user'
- );
- }
-
- public function testAssignRoleRejectsDuplicateGroupRole(): void
- {
- $this->groupManager->method('groupExists')->with('engineering')->willReturn(true);
- $existing = $this->makeAssignment(null, 'engineering', 'editor');
- $this->mapper->method('findGroupRole')->with('engineering', 'editor')->willReturn($existing);
-
- $this->expectException(DuplicateRoleAssignmentException::class);
- $this->service->assignRole(
- userId: null,
- groupId: 'engineering',
- role: 'editor',
- assignedBy: 'admin-user'
- );
- }
-
- public function testRemoveRoleThrowsWhenNoRowAffected(): void
- {
- $this->mapper->method('deleteById')->with(99)->willReturn(0);
-
- $this->expectException(DoesNotExistException::class);
- $this->service->removeRole(id: 99);
- }
-
- public function testRemoveRoleSucceedsWhenRowDeleted(): void
- {
- $this->mapper->method('deleteById')->with(7)->willReturn(1);
-
- $this->service->removeRole(id: 7);
- $this->expectNotToPerformAssertions();
- }
-
- // ==================================================================
- // Cascade entry points (REQ-ROLE-010, REQ-ROLE-011)
- // ==================================================================
-
- public function testDeleteByUserIdDelegatesToMapper(): void
- {
- $this->mapper->expects($this->once())
- ->method('deleteByUserId')
- ->with('bob')
- ->willReturn(2);
-
- $this->assertSame(2, $this->service->deleteByUserId(userId: 'bob'));
- }
-
- public function testDeleteByGroupIdDelegatesToMapper(): void
- {
- $this->mapper->expects($this->once())
- ->method('deleteByGroupId')
- ->with('engineering')
- ->willReturn(3);
-
- $this->assertSame(
- 3,
- $this->service->deleteByGroupId(groupId: 'engineering')
- );
- }
-
- // ==================================================================
- // Authorization helpers (REQ-ROLE-001..003, REQ-ROLE-008)
- // ==================================================================
-
- public function testIsAdminForNcAdmin(): void
- {
- $this->groupManager->method('isAdmin')->with('alice')->willReturn(true);
- $this->assertTrue($this->service->isAdmin(userId: 'alice'));
- }
-
- public function testIsViewerWhenViewerAssigned(): void
- {
- $this->groupManager->method('isAdmin')->willReturn(false);
- $this->mapper->method('findByUser')->willReturn(
- [$this->makeAssignment('charlie', null, RoleAssignment::ROLE_VIEWER)]
- );
-
- $this->assertTrue($this->service->isViewer(userId: 'charlie'));
- $this->assertFalse($this->service->canMutate(userId: 'charlie'));
- }
-
- public function testCanMutateForUnassignedUser(): void
- {
- $this->groupManager->method('isAdmin')->willReturn(false);
- $this->mapper->method('findByUser')->willReturn([]);
- $this->adminTemplateService->method('getUserGroupIdsFor')->willReturn([]);
- $this->mapper->method('findByGroupIds')->willReturn([]);
-
- $this->assertTrue($this->service->canMutate(userId: 'eve'));
- }
-
- public function testIsEditorOrHigherTrueForAdminAndEditor(): void
- {
- $this->groupManager->method('isAdmin')->with('alice')->willReturn(true);
- $this->assertTrue($this->service->isEditorOrHigher(userId: 'alice'));
- }
+class RoleServiceTest extends TestCase {
+ /** @var RoleAssignmentMapper&MockObject */
+ private $mapper;
+ /** @var IUserManager&MockObject */
+ private $userManager;
+ /** @var IGroupManager&MockObject */
+ private $groupManager;
+ /** @var AdminTemplateService&MockObject */
+ private $adminTemplateService;
+
+ private RoleService $service;
+
+ protected function setUp(): void {
+ parent::setUp();
+
+ $this->mapper = $this->createMock(RoleAssignmentMapper::class);
+ $this->userManager = $this->createMock(IUserManager::class);
+ $this->groupManager = $this->createMock(IGroupManager::class);
+ $this->adminTemplateService = $this->createMock(AdminTemplateService::class);
+
+ $this->service = new RoleService(
+ mapper: $this->mapper,
+ userManager: $this->userManager,
+ groupManager: $this->groupManager,
+ adminTemplateService: $this->adminTemplateService,
+ );
+ }
+
+ private function makeAssignment(
+ ?string $userId,
+ ?string $groupId,
+ string $role,
+ ): RoleAssignment {
+ $assignment = new RoleAssignment();
+ $assignment->setUserId($userId);
+ $assignment->setGroupId($groupId);
+ $assignment->setRole($role);
+ $assignment->setAssignedBy('admin-user');
+ $assignment->setAssignedAt('2026-05-02T12:00:00+00:00');
+ return $assignment;
+ }
+
+ // ==================================================================
+ // Effective-role resolution (REQ-ROLE-005)
+ // ==================================================================
+
+ public function testNcAdminAlwaysGetsAdminRole(): void {
+ $this->groupManager->method('isAdmin')->with('alice')->willReturn(true);
+
+ // No mapper lookup is required for NC admins.
+ $this->mapper->expects($this->never())->method('findByUser');
+ $this->mapper->expects($this->never())->method('findByGroupIds');
+
+ $this->assertSame(
+ RoleAssignment::ROLE_ADMIN,
+ $this->service->getEffectiveRole(userId: 'alice')
+ );
+ $this->assertSame(
+ RoleAssignment::SOURCE_NC_ADMIN,
+ $this->service->getRoleSource(userId: 'alice')
+ );
+ }
+
+ public function testDirectUserAssignmentUsedAsIs(): void {
+ $this->groupManager->method('isAdmin')->willReturn(false);
+ $this->mapper->method('findByUser')->with('bob')->willReturn(
+ [$this->makeAssignment('bob', null, RoleAssignment::ROLE_VIEWER)]
+ );
+
+ // Group lookups MUST be skipped per REQ-ROLE-005 step 2.
+ $this->mapper->expects($this->never())->method('findByGroupIds');
+ $this->adminTemplateService->expects($this->never())->method('getUserGroupIdsFor');
+
+ $this->assertSame(
+ RoleAssignment::ROLE_VIEWER,
+ $this->service->getEffectiveRole(userId: 'bob')
+ );
+ }
+
+ public function testDirectAssignmentBeatsHigherGroupRole(): void {
+ // REQ-ROLE-009 scenario 1: direct viewer beats group admin.
+ $this->groupManager->method('isAdmin')->willReturn(false);
+ $this->mapper->method('findByUser')->with('bob')->willReturn(
+ [$this->makeAssignment('bob', null, RoleAssignment::ROLE_VIEWER)]
+ );
+
+ $this->mapper->expects($this->never())->method('findByGroupIds');
+
+ $this->assertSame(
+ RoleAssignment::ROLE_VIEWER,
+ $this->service->getEffectiveRole(userId: 'bob')
+ );
+ $this->assertSame(
+ RoleAssignment::SOURCE_USER_ASSIGNED,
+ $this->service->getRoleSource(userId: 'bob')
+ );
+ }
+
+ public function testHighestGroupRoleWins(): void {
+ $this->groupManager->method('isAdmin')->willReturn(false);
+ $this->mapper->method('findByUser')->willReturn([]);
+
+ $this->adminTemplateService->method('getUserGroupIdsFor')->willReturn(
+ ['engineering', 'sales']
+ );
+
+ $this->mapper->method('findByGroupIds')->willReturn([
+ $this->makeAssignment(null, 'sales', RoleAssignment::ROLE_VIEWER),
+ $this->makeAssignment(null, 'engineering', RoleAssignment::ROLE_EDITOR),
+ ]);
+
+ $this->assertSame(
+ RoleAssignment::ROLE_EDITOR,
+ $this->service->getEffectiveRole(userId: 'charlie')
+ );
+ $this->assertSame(
+ RoleAssignment::SOURCE_GROUP_ASSIGNED_PREFIX . 'engineering',
+ $this->service->getRoleSource(userId: 'charlie')
+ );
+ }
+
+ public function testNoAssignmentReturnsNullRoleAndSource(): void {
+ $this->groupManager->method('isAdmin')->willReturn(false);
+ $this->mapper->method('findByUser')->willReturn([]);
+ $this->adminTemplateService->method('getUserGroupIdsFor')->willReturn([]);
+ $this->mapper->method('findByGroupIds')->willReturn([]);
+
+ $this->assertNull($this->service->getEffectiveRole(userId: 'eve'));
+ $this->assertNull($this->service->getRoleSource(userId: 'eve'));
+ }
+
+ // ==================================================================
+ // Validation (REQ-ROLE-004)
+ // ==================================================================
+
+ public function testValidateRoleAcceptsKnownRoles(): void {
+ $this->service->validateRole(role: 'admin');
+ $this->service->validateRole(role: 'editor');
+ $this->service->validateRole(role: 'viewer');
+ $this->expectNotToPerformAssertions();
+ }
+
+ public function testValidateRoleRejectsUnknown(): void {
+ $this->expectException(InvalidRoleAssignmentException::class);
+ $this->service->validateRole(role: 'superuser');
+ }
+
+ public function testValidateTargetRequiresOneOfUserOrGroup(): void {
+ $this->expectException(InvalidRoleAssignmentException::class);
+ $this->service->validateTarget(userId: null, groupId: null);
+ }
+
+ public function testValidateTargetRejectsBoth(): void {
+ $this->expectException(InvalidRoleAssignmentException::class);
+ $this->service->validateTarget(userId: 'bob', groupId: 'engineering');
+ }
+
+ public function testValidateTargetRejectsUnknownUser(): void {
+ $this->userManager->method('userExists')->with('ghost')->willReturn(false);
+
+ $this->expectException(InvalidRoleAssignmentException::class);
+ $this->service->validateTarget(userId: 'ghost', groupId: null);
+ }
+
+ public function testValidateTargetRejectsUnknownGroup(): void {
+ $this->groupManager->method('groupExists')->with('phantom')->willReturn(false);
+
+ $this->expectException(InvalidRoleAssignmentException::class);
+ $this->service->validateTarget(userId: null, groupId: 'phantom');
+ }
+
+ // ==================================================================
+ // Assignment CRUD (REQ-ROLE-004)
+ // ==================================================================
+
+ public function testAssignRolePersistsAndReturnsEntity(): void {
+ $this->userManager->method('userExists')->with('bob')->willReturn(true);
+ $this->mapper->method('findUserRole')->with('bob', 'editor')->willReturn(null);
+
+ $this->mapper->expects($this->once())
+ ->method('insert')
+ ->willReturnCallback(static fn (RoleAssignment $a) => $a);
+
+ $assignment = $this->service->assignRole(
+ userId: 'bob',
+ groupId: null,
+ role: 'editor',
+ assignedBy: 'admin-user'
+ );
+
+ $this->assertSame('bob', $assignment->getUserId());
+ $this->assertNull($assignment->getGroupId());
+ $this->assertSame('editor', $assignment->getRole());
+ $this->assertSame('admin-user', $assignment->getAssignedBy());
+ $this->assertNotNull($assignment->getAssignedAt());
+ }
+
+ public function testAssignRoleRejectsDuplicateUserRole(): void {
+ $this->userManager->method('userExists')->with('bob')->willReturn(true);
+ $existing = $this->makeAssignment('bob', null, 'editor');
+ $this->mapper->method('findUserRole')->with('bob', 'editor')->willReturn($existing);
+
+ $this->expectException(DuplicateRoleAssignmentException::class);
+ $this->service->assignRole(
+ userId: 'bob',
+ groupId: null,
+ role: 'editor',
+ assignedBy: 'admin-user'
+ );
+ }
+
+ public function testAssignRoleRejectsDuplicateGroupRole(): void {
+ $this->groupManager->method('groupExists')->with('engineering')->willReturn(true);
+ $existing = $this->makeAssignment(null, 'engineering', 'editor');
+ $this->mapper->method('findGroupRole')->with('engineering', 'editor')->willReturn($existing);
+
+ $this->expectException(DuplicateRoleAssignmentException::class);
+ $this->service->assignRole(
+ userId: null,
+ groupId: 'engineering',
+ role: 'editor',
+ assignedBy: 'admin-user'
+ );
+ }
+
+ public function testRemoveRoleThrowsWhenNoRowAffected(): void {
+ $this->mapper->method('deleteById')->with(99)->willReturn(0);
+
+ $this->expectException(DoesNotExistException::class);
+ $this->service->removeRole(id: 99);
+ }
+
+ public function testRemoveRoleSucceedsWhenRowDeleted(): void {
+ $this->mapper->method('deleteById')->with(7)->willReturn(1);
+
+ $this->service->removeRole(id: 7);
+ $this->expectNotToPerformAssertions();
+ }
+
+ // ==================================================================
+ // Cascade entry points (REQ-ROLE-010, REQ-ROLE-011)
+ // ==================================================================
+
+ public function testDeleteByUserIdDelegatesToMapper(): void {
+ $this->mapper->expects($this->once())
+ ->method('deleteByUserId')
+ ->with('bob')
+ ->willReturn(2);
+
+ $this->assertSame(2, $this->service->deleteByUserId(userId: 'bob'));
+ }
+
+ public function testDeleteByGroupIdDelegatesToMapper(): void {
+ $this->mapper->expects($this->once())
+ ->method('deleteByGroupId')
+ ->with('engineering')
+ ->willReturn(3);
+
+ $this->assertSame(
+ 3,
+ $this->service->deleteByGroupId(groupId: 'engineering')
+ );
+ }
+
+ // ==================================================================
+ // Authorization helpers (REQ-ROLE-001..003, REQ-ROLE-008)
+ // ==================================================================
+
+ public function testIsAdminForNcAdmin(): void {
+ $this->groupManager->method('isAdmin')->with('alice')->willReturn(true);
+ $this->assertTrue($this->service->isAdmin(userId: 'alice'));
+ }
+
+ public function testIsViewerWhenViewerAssigned(): void {
+ $this->groupManager->method('isAdmin')->willReturn(false);
+ $this->mapper->method('findByUser')->willReturn(
+ [$this->makeAssignment('charlie', null, RoleAssignment::ROLE_VIEWER)]
+ );
+
+ $this->assertTrue($this->service->isViewer(userId: 'charlie'));
+ $this->assertFalse($this->service->canMutate(userId: 'charlie'));
+ }
+
+ public function testCanMutateForUnassignedUser(): void {
+ $this->groupManager->method('isAdmin')->willReturn(false);
+ $this->mapper->method('findByUser')->willReturn([]);
+ $this->adminTemplateService->method('getUserGroupIdsFor')->willReturn([]);
+ $this->mapper->method('findByGroupIds')->willReturn([]);
+
+ $this->assertTrue($this->service->canMutate(userId: 'eve'));
+ }
+
+ public function testIsEditorOrHigherTrueForAdminAndEditor(): void {
+ $this->groupManager->method('isAdmin')->with('alice')->willReturn(true);
+ $this->assertTrue($this->service->isEditorOrHigher(userId: 'alice'));
+ }
}//end class
diff --git a/tests/Unit/Service/SetupWizardServiceTest.php b/tests/Unit/Service/SetupWizardServiceTest.php
index 1804636e..ce7840d9 100644
--- a/tests/Unit/Service/SetupWizardServiceTest.php
+++ b/tests/Unit/Service/SetupWizardServiceTest.php
@@ -29,161 +29,149 @@
use PHPUnit\Framework\MockObject\MockObject;
use PHPUnit\Framework\TestCase;
-class SetupWizardServiceTest extends TestCase
-{
- private SetupWizardService $service;
-
- /** @var AdminSettingMapper&MockObject */
- private $settingMapper;
-
- /** @var IAppManager&MockObject */
- private $appManager;
-
- protected function setUp(): void
- {
- $this->settingMapper = $this->createMock(AdminSettingMapper::class);
- $this->appManager = $this->createMock(IAppManager::class);
- $this->service = new SetupWizardService(
- settingMapper: $this->settingMapper,
- appManager: $this->appManager
- );
- }
-
- public function testGetWizardStateOnFreshInstance(): void
- {
- $this->settingMapper->method('getValue')
- ->with(AdminSetting::KEY_SETUP_WIZARD_COMPLETE, false)
- ->willReturn(false);
- $this->settingMapper->method('getAllAsArray')->willReturn([]);
-
- $state = $this->service->getWizardState();
-
- $this->assertFalse($state['complete']);
- $this->assertSame(2, $state['currentRecommendedStep']);
- $this->assertSame('done', $state['stepStatuses']['1']);
- $this->assertSame('pending', $state['stepStatuses']['2']);
- $this->assertSame('pending', $state['stepStatuses']['3']);
- $this->assertSame('skipped', $state['stepStatuses']['4']);
- $this->assertSame('skipped', $state['stepStatuses']['5']);
- $this->assertSame('skipped', $state['stepStatuses']['6']);
- $this->assertSame('pending', $state['stepStatuses']['7']);
- }
-
- public function testGetWizardStateAfterStorageWritten(): void
- {
- $this->settingMapper->method('getValue')
- ->with(AdminSetting::KEY_SETUP_WIZARD_COMPLETE, false)
- ->willReturn(false);
- $this->settingMapper->method('getAllAsArray')->willReturn([
- AdminSetting::KEY_CONTENT_STORAGE => 'database',
- ]);
-
- $state = $this->service->getWizardState();
-
- $this->assertSame('done', $state['stepStatuses']['2']);
- // Step 3 still pending so the recommended step jumps to 3.
- $this->assertSame(3, $state['currentRecommendedStep']);
- }
-
- public function testGetWizardStateAfterCompletion(): void
- {
- $this->settingMapper->method('getValue')
- ->with(AdminSetting::KEY_SETUP_WIZARD_COMPLETE, false)
- ->willReturn(true);
- $this->settingMapper->method('getAllAsArray')->willReturn([
- AdminSetting::KEY_CONTENT_STORAGE => 'database',
- AdminSetting::KEY_GROUP_ORDER => ['engineering'],
- AdminSetting::KEY_FOOTER_CONFIG => ['layout' => 'structured'],
- ]);
-
- $state = $this->service->getWizardState();
-
- $this->assertTrue($state['complete']);
- $this->assertSame('done', $state['stepStatuses']['7']);
- $this->assertSame('done', $state['stepStatuses']['6']);
- // Steps 4/5 are 'skipped' (sibling capabilities pending), so the
- // first non-'done' status is Step 4. The wizard "complete" flag
- // is the source of truth for hiding the banner; the recommended
- // step is purely a UX hint per REQ-WIZ-008.
- $this->assertSame(4, $state['currentRecommendedStep']);
- }
-
- public function testMarkWizardCompleteSetsFlagAndReturnsState(): void
- {
- $this->settingMapper
- ->expects($this->once())
- ->method('setSetting')
- ->with(AdminSetting::KEY_SETUP_WIZARD_COMPLETE, true);
- $this->settingMapper->method('getValue')
- ->with(AdminSetting::KEY_SETUP_WIZARD_COMPLETE, false)
- ->willReturn(true);
- $this->settingMapper->method('getAllAsArray')->willReturn([]);
-
- $state = $this->service->markWizardComplete();
-
- $this->assertTrue($state['complete']);
- }
-
- public function testMarkWizardCompleteIsIdempotent(): void
- {
- // Even when already true the service still writes (idempotent
- // semantics — the controller doesn't need a defensive guard).
- $this->settingMapper
- ->expects($this->exactly(2))
- ->method('setSetting');
- $this->settingMapper->method('getValue')->willReturn(true);
- $this->settingMapper->method('getAllAsArray')->willReturn([]);
-
- $first = $this->service->markWizardComplete();
- $second = $this->service->markWizardComplete();
-
- $this->assertSame($first, $second);
- }
-
- public function testGetGroupfolderAvailabilityDelegates(): void
- {
- $this->appManager
- ->expects($this->once())
- ->method('isInstalled')
- ->with('groupfolders')
- ->willReturn(true);
-
- $this->assertTrue($this->service->hasGroupfolderApp());
- }
-
- public function testSetContentStorageRejectsUnsupportedValue(): void
- {
- $this->settingMapper->expects($this->never())->method('setSetting');
- $this->expectException(InvalidArgumentException::class);
-
- $this->service->setContentStorage(value: 'cassette-tape');
- }
-
- public function testSetContentStoragePersistsKnownValues(): void
- {
- $this->settingMapper
- ->expects($this->once())
- ->method('setSetting')
- ->with(AdminSetting::KEY_CONTENT_STORAGE, 'groupfolder');
-
- $this->service->setContentStorage(value: SetupWizardService::STORAGE_GROUPFOLDER);
- }
-
- public function testGetContentStorageDefaultsToDatabase(): void
- {
- $this->settingMapper->method('getValue')
- ->with(AdminSetting::KEY_CONTENT_STORAGE, null)
- ->willReturn(null);
-
- $this->assertSame('database', $this->service->getContentStorage());
- }
-
- public function testGetContentStorageReturnsPersisted(): void
- {
- $this->settingMapper->method('getValue')
- ->with(AdminSetting::KEY_CONTENT_STORAGE, null)
- ->willReturn('groupfolder');
-
- $this->assertSame('groupfolder', $this->service->getContentStorage());
- }
+class SetupWizardServiceTest extends TestCase {
+ private SetupWizardService $service;
+
+ /** @var AdminSettingMapper&MockObject */
+ private $settingMapper;
+
+ /** @var IAppManager&MockObject */
+ private $appManager;
+
+ protected function setUp(): void {
+ $this->settingMapper = $this->createMock(AdminSettingMapper::class);
+ $this->appManager = $this->createMock(IAppManager::class);
+ $this->service = new SetupWizardService(
+ settingMapper: $this->settingMapper,
+ appManager: $this->appManager
+ );
+ }
+
+ public function testGetWizardStateOnFreshInstance(): void {
+ $this->settingMapper->method('getValue')
+ ->with(AdminSetting::KEY_SETUP_WIZARD_COMPLETE, false)
+ ->willReturn(false);
+ $this->settingMapper->method('getAllAsArray')->willReturn([]);
+
+ $state = $this->service->getWizardState();
+
+ $this->assertFalse($state['complete']);
+ $this->assertSame(2, $state['currentRecommendedStep']);
+ $this->assertSame('done', $state['stepStatuses']['1']);
+ $this->assertSame('pending', $state['stepStatuses']['2']);
+ $this->assertSame('pending', $state['stepStatuses']['3']);
+ $this->assertSame('skipped', $state['stepStatuses']['4']);
+ $this->assertSame('skipped', $state['stepStatuses']['5']);
+ $this->assertSame('skipped', $state['stepStatuses']['6']);
+ $this->assertSame('pending', $state['stepStatuses']['7']);
+ }
+
+ public function testGetWizardStateAfterStorageWritten(): void {
+ $this->settingMapper->method('getValue')
+ ->with(AdminSetting::KEY_SETUP_WIZARD_COMPLETE, false)
+ ->willReturn(false);
+ $this->settingMapper->method('getAllAsArray')->willReturn([
+ AdminSetting::KEY_CONTENT_STORAGE => 'database',
+ ]);
+
+ $state = $this->service->getWizardState();
+
+ $this->assertSame('done', $state['stepStatuses']['2']);
+ // Step 3 still pending so the recommended step jumps to 3.
+ $this->assertSame(3, $state['currentRecommendedStep']);
+ }
+
+ public function testGetWizardStateAfterCompletion(): void {
+ $this->settingMapper->method('getValue')
+ ->with(AdminSetting::KEY_SETUP_WIZARD_COMPLETE, false)
+ ->willReturn(true);
+ $this->settingMapper->method('getAllAsArray')->willReturn([
+ AdminSetting::KEY_CONTENT_STORAGE => 'database',
+ AdminSetting::KEY_GROUP_ORDER => ['engineering'],
+ AdminSetting::KEY_FOOTER_CONFIG => ['layout' => 'structured'],
+ ]);
+
+ $state = $this->service->getWizardState();
+
+ $this->assertTrue($state['complete']);
+ $this->assertSame('done', $state['stepStatuses']['7']);
+ $this->assertSame('done', $state['stepStatuses']['6']);
+ // Steps 4/5 are 'skipped' (sibling capabilities pending), so the
+ // first non-'done' status is Step 4. The wizard "complete" flag
+ // is the source of truth for hiding the banner; the recommended
+ // step is purely a UX hint per REQ-WIZ-008.
+ $this->assertSame(4, $state['currentRecommendedStep']);
+ }
+
+ public function testMarkWizardCompleteSetsFlagAndReturnsState(): void {
+ $this->settingMapper
+ ->expects($this->once())
+ ->method('setSetting')
+ ->with(AdminSetting::KEY_SETUP_WIZARD_COMPLETE, true);
+ $this->settingMapper->method('getValue')
+ ->with(AdminSetting::KEY_SETUP_WIZARD_COMPLETE, false)
+ ->willReturn(true);
+ $this->settingMapper->method('getAllAsArray')->willReturn([]);
+
+ $state = $this->service->markWizardComplete();
+
+ $this->assertTrue($state['complete']);
+ }
+
+ public function testMarkWizardCompleteIsIdempotent(): void {
+ // Even when already true the service still writes (idempotent
+ // semantics — the controller doesn't need a defensive guard).
+ $this->settingMapper
+ ->expects($this->exactly(2))
+ ->method('setSetting');
+ $this->settingMapper->method('getValue')->willReturn(true);
+ $this->settingMapper->method('getAllAsArray')->willReturn([]);
+
+ $first = $this->service->markWizardComplete();
+ $second = $this->service->markWizardComplete();
+
+ $this->assertSame($first, $second);
+ }
+
+ public function testGetGroupfolderAvailabilityDelegates(): void {
+ $this->appManager
+ ->expects($this->once())
+ ->method('isInstalled')
+ ->with('groupfolders')
+ ->willReturn(true);
+
+ $this->assertTrue($this->service->hasGroupfolderApp());
+ }
+
+ public function testSetContentStorageRejectsUnsupportedValue(): void {
+ $this->settingMapper->expects($this->never())->method('setSetting');
+ $this->expectException(InvalidArgumentException::class);
+
+ $this->service->setContentStorage(value: 'cassette-tape');
+ }
+
+ public function testSetContentStoragePersistsKnownValues(): void {
+ $this->settingMapper
+ ->expects($this->once())
+ ->method('setSetting')
+ ->with(AdminSetting::KEY_CONTENT_STORAGE, 'groupfolder');
+
+ $this->service->setContentStorage(value: SetupWizardService::STORAGE_GROUPFOLDER);
+ }
+
+ public function testGetContentStorageDefaultsToDatabase(): void {
+ $this->settingMapper->method('getValue')
+ ->with(AdminSetting::KEY_CONTENT_STORAGE, null)
+ ->willReturn(null);
+
+ $this->assertSame('database', $this->service->getContentStorage());
+ }
+
+ public function testGetContentStorageReturnsPersisted(): void {
+ $this->settingMapper->method('getValue')
+ ->with(AdminSetting::KEY_CONTENT_STORAGE, null)
+ ->willReturn('groupfolder');
+
+ $this->assertSame('groupfolder', $this->service->getContentStorage());
+ }
}
diff --git a/tests/Unit/Service/SlugGeneratorTest.php b/tests/Unit/Service/SlugGeneratorTest.php
index 9bd24ca2..03356506 100644
--- a/tests/Unit/Service/SlugGeneratorTest.php
+++ b/tests/Unit/Service/SlugGeneratorTest.php
@@ -25,114 +25,104 @@
/**
* Unit tests for {@see SlugGenerator}.
*/
-class SlugGeneratorTest extends TestCase
-{
- /**
- * Standard alphanumeric name → simple lowercase slug.
- *
- * @return void
- */
- public function testSlugifyLowercases(): void
- {
- $this->assertSame('marketing', SlugGenerator::slugify(name: 'Marketing'));
- }//end testSlugifyLowercases()
+class SlugGeneratorTest extends TestCase {
+ /**
+ * Standard alphanumeric name → simple lowercase slug.
+ *
+ * @return void
+ */
+ public function testSlugifyLowercases(): void {
+ $this->assertSame('marketing', SlugGenerator::slugify(name: 'Marketing'));
+ }//end testSlugifyLowercases()
- /**
- * Multi-word names → dash-joined.
- *
- * @return void
- */
- public function testSlugifySpacesBecomeDashes(): void
- {
- $this->assertSame(
- 'q1-campaigns',
- SlugGenerator::slugify(name: 'Q1 Campaigns')
- );
- }//end testSlugifySpacesBecomeDashes()
+ /**
+ * Multi-word names → dash-joined.
+ *
+ * @return void
+ */
+ public function testSlugifySpacesBecomeDashes(): void {
+ $this->assertSame(
+ 'q1-campaigns',
+ SlugGenerator::slugify(name: 'Q1 Campaigns')
+ );
+ }//end testSlugifySpacesBecomeDashes()
- /**
- * Punctuation outside the grammar is stripped.
- *
- * @return void
- */
- public function testSlugifyStripsPunctuation(): void
- {
- $this->assertSame(
- 'hello-world',
- SlugGenerator::slugify(name: 'Hello, World!')
- );
- }//end testSlugifyStripsPunctuation()
+ /**
+ * Punctuation outside the grammar is stripped.
+ *
+ * @return void
+ */
+ public function testSlugifyStripsPunctuation(): void {
+ $this->assertSame(
+ 'hello-world',
+ SlugGenerator::slugify(name: 'Hello, World!')
+ );
+ }//end testSlugifyStripsPunctuation()
- /**
- * Repeated separators collapse to one dash.
- *
- * @return void
- */
- public function testSlugifyCollapsesRepeatedDashes(): void
- {
- $this->assertSame(
- 'foo-bar',
- SlugGenerator::slugify(name: 'foo --- bar')
- );
- }//end testSlugifyCollapsesRepeatedDashes()
+ /**
+ * Repeated separators collapse to one dash.
+ *
+ * @return void
+ */
+ public function testSlugifyCollapsesRepeatedDashes(): void {
+ $this->assertSame(
+ 'foo-bar',
+ SlugGenerator::slugify(name: 'foo --- bar')
+ );
+ }//end testSlugifyCollapsesRepeatedDashes()
- /**
- * Names that yield no legal characters → empty slug.
- *
- * @return void
- */
- public function testSlugifyReturnsEmptyOnNoLegalChars(): void
- {
- $this->assertSame('', SlugGenerator::slugify(name: '!!!'));
- }//end testSlugifyReturnsEmptyOnNoLegalChars()
+ /**
+ * Names that yield no legal characters → empty slug.
+ *
+ * @return void
+ */
+ public function testSlugifyReturnsEmptyOnNoLegalChars(): void {
+ $this->assertSame('', SlugGenerator::slugify(name: '!!!'));
+ }//end testSlugifyReturnsEmptyOnNoLegalChars()
- /**
- * Slug exceeding 128 characters → truncated.
- *
- * @return void
- */
- public function testSlugifyTruncatesLongInput(): void
- {
- $longName = str_repeat('a', 200);
- $slug = SlugGenerator::slugify(name: $longName);
+ /**
+ * Slug exceeding 128 characters → truncated.
+ *
+ * @return void
+ */
+ public function testSlugifyTruncatesLongInput(): void {
+ $longName = str_repeat('a', 200);
+ $slug = SlugGenerator::slugify(name: $longName);
- $this->assertLessThanOrEqual(SlugGenerator::MAX_LENGTH, strlen($slug));
- }//end testSlugifyTruncatesLongInput()
+ $this->assertLessThanOrEqual(SlugGenerator::MAX_LENGTH, strlen($slug));
+ }//end testSlugifyTruncatesLongInput()
- /**
- * isValid: legal grammar accepted.
- *
- * @return void
- */
- public function testIsValidAcceptsLegalSlugs(): void
- {
- $this->assertTrue(SlugGenerator::isValid(slug: 'q1-campaigns'));
- $this->assertTrue(SlugGenerator::isValid(slug: 'snake_case'));
- $this->assertTrue(SlugGenerator::isValid(slug: 'abc123'));
- }//end testIsValidAcceptsLegalSlugs()
+ /**
+ * isValid: legal grammar accepted.
+ *
+ * @return void
+ */
+ public function testIsValidAcceptsLegalSlugs(): void {
+ $this->assertTrue(SlugGenerator::isValid(slug: 'q1-campaigns'));
+ $this->assertTrue(SlugGenerator::isValid(slug: 'snake_case'));
+ $this->assertTrue(SlugGenerator::isValid(slug: 'abc123'));
+ }//end testIsValidAcceptsLegalSlugs()
- /**
- * isValid: empty / uppercase / punctuation rejected.
- *
- * @return void
- */
- public function testIsValidRejectsIllegalSlugs(): void
- {
- $this->assertFalse(SlugGenerator::isValid(slug: ''));
- $this->assertFalse(SlugGenerator::isValid(slug: 'Q1'));
- $this->assertFalse(SlugGenerator::isValid(slug: 'q1 campaigns'));
- $this->assertFalse(SlugGenerator::isValid(slug: 'q1!'));
- }//end testIsValidRejectsIllegalSlugs()
+ /**
+ * isValid: empty / uppercase / punctuation rejected.
+ *
+ * @return void
+ */
+ public function testIsValidRejectsIllegalSlugs(): void {
+ $this->assertFalse(SlugGenerator::isValid(slug: ''));
+ $this->assertFalse(SlugGenerator::isValid(slug: 'Q1'));
+ $this->assertFalse(SlugGenerator::isValid(slug: 'q1 campaigns'));
+ $this->assertFalse(SlugGenerator::isValid(slug: 'q1!'));
+ }//end testIsValidRejectsIllegalSlugs()
- /**
- * isValid: 128-character cap enforced.
- *
- * @return void
- */
- public function testIsValidRejectsOverLengthSlugs(): void
- {
- $this->assertFalse(
- SlugGenerator::isValid(slug: str_repeat('a', 129))
- );
- }//end testIsValidRejectsOverLengthSlugs()
+ /**
+ * isValid: 128-character cap enforced.
+ *
+ * @return void
+ */
+ public function testIsValidRejectsOverLengthSlugs(): void {
+ $this->assertFalse(
+ SlugGenerator::isValid(slug: str_repeat('a', 129))
+ );
+ }//end testIsValidRejectsOverLengthSlugs()
}//end class
diff --git a/tests/Unit/Service/SvgSanitiserTest.php b/tests/Unit/Service/SvgSanitiserTest.php
index bd99462a..cbe9d4b7 100644
--- a/tests/Unit/Service/SvgSanitiserTest.php
+++ b/tests/Unit/Service/SvgSanitiserTest.php
@@ -25,243 +25,224 @@
namespace Unit\Service;
use OCA\LaunchPad\Service\SvgSanitiser;
-use PHPUnit\Framework\Attributes\Small;
use PHPUnit\Framework\TestCase;
-class SvgSanitiserTest extends TestCase
-{
- private SvgSanitiser $sanitiser;
-
- protected function setUp(): void
- {
- $this->sanitiser = new SvgSanitiser();
- }
-
- public function testCleanSvgRoundTrips(): void
- {
- $svg = '';
-
- $result = $this->sanitiser->sanitize($svg);
-
- $this->assertNotNull($result);
- $this->assertStringContainsString('assertStringContainsString('fill="red"', $result);
- }
-
- public function testScriptElementRemoved(): void
- {
- $svg = '';
-
- $result = $this->sanitiser->sanitize($svg);
-
- $this->assertNotNull($result);
- $this->assertStringNotContainsString('assertStringNotContainsString('alert', $result);
- $this->assertStringContainsString(''
- . 'assertStringContainsString(''
- . ''
- . ''
- . ''
- . ''
- . ']>'
- . '';
-
- $start = microtime(true);
- // We don't care about the return value — only that this returns
- // within bounded time without exhausting memory.
- $this->sanitiser->sanitize($svg);
- $elapsed = (microtime(true) - $start);
-
- $this->assertLessThan(5.0, $elapsed, 'Billion-laughs must be bounded');
- }
-
- public function testUnparseableBytesReturnNull(): void
- {
- $this->assertNull($this->sanitiser->sanitize('assertNull($this->sanitiser->sanitize(''));
- }
-
- public function testNonSvgRootRejected(): void
- {
- // A well-formed XML document with a non-svg root MUST be rejected
- // — the sanitiser only accepts ';
-
- $this->assertNull($this->sanitiser->sanitize($xml));
- }
+class SvgSanitiserTest extends TestCase {
+ private SvgSanitiser $sanitiser;
+
+ protected function setUp(): void {
+ $this->sanitiser = new SvgSanitiser();
+ }
+
+ public function testCleanSvgRoundTrips(): void {
+ $svg = '';
+
+ $result = $this->sanitiser->sanitize($svg);
+
+ $this->assertNotNull($result);
+ $this->assertStringContainsString('assertStringContainsString('fill="red"', $result);
+ }
+
+ public function testScriptElementRemoved(): void {
+ $svg = '';
+
+ $result = $this->sanitiser->sanitize($svg);
+
+ $this->assertNotNull($result);
+ $this->assertStringNotContainsString('assertStringNotContainsString('alert', $result);
+ $this->assertStringContainsString(''
+ . 'assertStringContainsString(''
+ . ''
+ . ''
+ . ''
+ . ''
+ . ']>'
+ . '';
+
+ $start = microtime(true);
+ // We don't care about the return value — only that this returns
+ // within bounded time without exhausting memory.
+ $this->sanitiser->sanitize($svg);
+ $elapsed = (microtime(true) - $start);
+
+ $this->assertLessThan(5.0, $elapsed, 'Billion-laughs must be bounded');
+ }
+
+ public function testUnparseableBytesReturnNull(): void {
+ $this->assertNull($this->sanitiser->sanitize('assertNull($this->sanitiser->sanitize(''));
+ }
+
+ public function testNonSvgRootRejected(): void {
+ // A well-formed XML document with a non-svg root MUST be rejected
+ // — the sanitiser only accepts ';
+
+ $this->assertNull($this->sanitiser->sanitize($xml));
+ }
}
diff --git a/tests/Unit/Service/TemplateResyncServiceTest.php b/tests/Unit/Service/TemplateResyncServiceTest.php
index 44c3caf7..1ea875a1 100644
--- a/tests/Unit/Service/TemplateResyncServiceTest.php
+++ b/tests/Unit/Service/TemplateResyncServiceTest.php
@@ -50,659 +50,639 @@
/**
* Tests for {@see TemplateResyncService}.
*/
-class TemplateResyncServiceTest extends TestCase
-{
- /** @var DashboardMapper&MockObject */
- private $dashboardMapper;
-
- /** @var WidgetPlacementMapper&MockObject */
- private $placementMapper;
-
- /** @var IDBConnection&MockObject */
- private $db;
-
- /** @var ActivityPublisher&MockObject */
- private $activityPublisher;
-
- /** @var INotificationManager&MockObject */
- private $notificationManager;
-
- /** @var IJobList&MockObject */
- private $jobList;
-
- /** @var LoggerInterface&MockObject */
- private $logger;
-
- private TemplateResyncService $service;
-
- protected function setUp(): void
- {
- parent::setUp();
-
- $this->dashboardMapper = $this->createMock(DashboardMapper::class);
- $this->placementMapper = $this->createMock(WidgetPlacementMapper::class);
- $this->db = $this->createMock(IDBConnection::class);
- $this->activityPublisher = $this->createMock(ActivityPublisher::class);
- $this->notificationManager = $this->createMock(INotificationManager::class);
- $this->jobList = $this->createMock(IJobList::class);
- $this->logger = $this->createMock(LoggerInterface::class);
-
- $this->service = new TemplateResyncService(
- dashboardMapper: $this->dashboardMapper,
- placementMapper: $this->placementMapper,
- db: $this->db,
- activityPublisher: $this->activityPublisher,
- notificationManager: $this->notificationManager,
- jobList: $this->jobList,
- logger: $this->logger,
- );
- }
-
- // ---------------------------------------------------------------
- // Helpers
- // ---------------------------------------------------------------
-
- private function makeTemplate(int $id = 1): Dashboard
- {
- $dashboard = new Dashboard();
- $dashboard->setId($id);
- $dashboard->setUuid('template-uuid-' . $id);
- $dashboard->setName('Marketing Dashboard');
- $dashboard->setType(Dashboard::TYPE_ADMIN_TEMPLATE);
- $dashboard->setUserId(null);
-
- return $dashboard;
- }
-
- private function makeUserDashboard(int $id = 5): Dashboard
- {
- $dashboard = new Dashboard();
- $dashboard->setId($id);
- $dashboard->setUuid('user-dashboard-uuid-' . $id);
- $dashboard->setName('My Dashboard');
- $dashboard->setType(Dashboard::TYPE_USER);
- $dashboard->setUserId('alice');
-
- return $dashboard;
- }
-
- private function makeCopy(int $id, string $userId): Dashboard
- {
- $dashboard = new Dashboard();
- $dashboard->setId($id);
- $dashboard->setUuid('copy-uuid-' . $id);
- $dashboard->setName('Marketing Dashboard');
- $dashboard->setType(Dashboard::TYPE_USER);
- $dashboard->setUserId($userId);
- $dashboard->setBasedOnTemplate(1);
-
- return $dashboard;
- }
-
- private function makePlacement(
- int $id,
- int $dashboardId,
- string $widgetId = 'w1',
- int $gridX = 0,
- int $isCompulsory = 0,
- ?int $templatePlacementId = null
- ): WidgetPlacement {
- $placement = new WidgetPlacement();
- $placement->setId($id);
- $placement->setDashboardId($dashboardId);
- $placement->setWidgetId($widgetId);
- $placement->setGridX($gridX);
- $placement->setGridY(0);
- $placement->setGridWidth(4);
- $placement->setGridHeight(4);
- $placement->setIsCompulsory($isCompulsory);
- $placement->setIsVisible(1);
- $placement->setShowTitle(1);
- $placement->setSortOrder(0);
- $placement->setRequiresAcknowledgement(0);
- $placement->setReacknowledgeOnChange(0);
- $placement->setAcknowledgementContentVersion(1);
- $placement->setTemplatePlacementId($templatePlacementId);
-
- return $placement;
- }
-
- // ---------------------------------------------------------------
- // Validation
- // ---------------------------------------------------------------
-
- public function testInvalidStrategyIsRejected(): void
- {
- $this->dashboardMapper->method('find')->willReturn($this->makeTemplate());
-
- $this->expectException(InvalidArgumentException::class);
- $this->service->resync(
- templateId: 1,
- strategy: 'replace-all',
- dryRun: true,
- actingAdminId: 'admin1'
- );
- }
-
- public function testNonTemplateDashboardIsRejected(): void
- {
- $this->dashboardMapper->method('find')->willReturn($this->makeUserDashboard());
-
- $this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('Not an admin template');
- $this->service->resync(
- templateId: 5,
- strategy: TemplateResyncService::STRATEGY_OVERWRITE,
- dryRun: true,
- actingAdminId: 'admin1'
- );
- }
-
- public function testUnknownTemplateIdIsRejected(): void
- {
- $this->dashboardMapper->method('find')
- ->willThrowException(new DoesNotExistException(msg: 'not found'));
-
- $this->expectException(InvalidArgumentException::class);
- $this->service->resync(
- templateId: 999,
- strategy: TemplateResyncService::STRATEGY_OVERWRITE,
- dryRun: true,
- actingAdminId: 'admin1'
- );
- }
-
- // ---------------------------------------------------------------
- // Dry-run — reports without mutating (REQ-RESYNC-002)
- // ---------------------------------------------------------------
-
- public function testDryRunReportsAffectedCopiesWithoutMutating(): void
- {
- $template = $this->makeTemplate();
- $this->dashboardMapper->method('find')->willReturn($template);
-
- // Template now has 2 placements; the announcements one is new.
- $templatePlacements = [
- $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links'),
- $this->makePlacement(id: 11, dashboardId: 1, widgetId: 'announcements'),
- ];
-
- $copyA = $this->makeCopy(id: 100, userId: 'alice');
- $copyB = $this->makeCopy(id: 101, userId: 'bob');
-
- $this->dashboardMapper->method('findByBasedOnTemplate')
- ->willReturn([$copyA, $copyB]);
-
- // alice's copy still has only the original "links" placement,
- // cloned from template placement 10.
- $aliceCopyPlacements = [
- $this->makePlacement(id: 200, dashboardId: 100, widgetId: 'links', templatePlacementId: 10),
- ];
- // bob's copy also has "links" plus a personal "notes" widget.
- $bobCopyPlacements = [
- $this->makePlacement(id: 201, dashboardId: 101, widgetId: 'links', templatePlacementId: 10),
- $this->makePlacement(id: 202, dashboardId: 101, widgetId: 'notes', templatePlacementId: null),
- ];
-
- $this->placementMapper->method('findByDashboardId')
- ->willReturnMap([
- [1, $templatePlacements],
- [100, $aliceCopyPlacements],
- [101, $bobCopyPlacements],
- ]);
-
- $this->placementMapper->expects($this->never())->method('insert');
- $this->placementMapper->expects($this->never())->method('update');
- $this->placementMapper->expects($this->never())->method('delete');
- $this->activityPublisher->expects($this->never())->method('publish');
- $this->notificationManager->expects($this->never())->method('notify');
-
- $result = $this->service->resync(
- templateId: 1,
- strategy: TemplateResyncService::STRATEGY_MERGE,
- dryRun: true,
- actingAdminId: 'admin1'
- );
-
- $this->assertTrue($result['dryRun']);
- $this->assertFalse($result['async']);
- $this->assertSame(2, $result['totalCopies']);
- // Both copies are missing the new "announcements" placement.
- $this->assertSame(2, $result['affectedCount']);
-
- $aliceReport = $this->findCopyReport($result['copies'], 100);
- $this->assertSame(1, $aliceReport['toAdd']);
- $this->assertSame(0, $aliceReport['toUpdate']);
- $this->assertSame(0, $aliceReport['toRemove']);
- $this->assertSame(1, $aliceReport['toPreserve']);
-
- $bobReport = $this->findCopyReport($result['copies'], 101);
- $this->assertSame(1, $bobReport['toAdd']);
- $this->assertSame(0, $bobReport['toRemove']);
- // bob's personal "notes" widget is preserved under merge.
- $this->assertSame(2, $bobReport['toPreserve']);
- }
-
- public function testDryRunOnUpToDateTemplateReportsNoChanges(): void
- {
- $template = $this->makeTemplate();
- $this->dashboardMapper->method('find')->willReturn($template);
-
- $templatePlacement = $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links');
- $copy = $this->makeCopy(id: 100, userId: 'alice');
- $copyPlacement = $this->makePlacement(id: 200, dashboardId: 100, widgetId: 'links', templatePlacementId: 10);
-
- $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
- $this->placementMapper->method('findByDashboardId')
- ->willReturnMap([
- [1, [$templatePlacement]],
- [100, [$copyPlacement]],
- ]);
-
- $result = $this->service->resync(
- templateId: 1,
- strategy: TemplateResyncService::STRATEGY_OVERWRITE,
- dryRun: true,
- actingAdminId: 'admin1'
- );
-
- $this->assertSame(0, $result['affectedCount']);
- $report = $this->findCopyReport($result['copies'], 100);
- $this->assertSame(0, $report['toAdd']);
- $this->assertSame(0, $report['toUpdate']);
- $this->assertSame(0, $report['toRemove']);
- $this->assertSame(1, $report['toPreserve']);
- }
-
- // ---------------------------------------------------------------
- // Merge preserves user-added widgets (REQ-RESYNC-003)
- // ---------------------------------------------------------------
-
- public function testMergeKeepsUserAddedWidgetsWhileApplyingTemplateChanges(): void
- {
- $template = $this->makeTemplate();
- $this->dashboardMapper->method('find')->willReturn($template);
-
- // Template: "links" moved to gridX=4, new "announcements" added.
- $templatePlacements = [
- $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links', gridX: 4),
- $this->makePlacement(id: 11, dashboardId: 1, widgetId: 'announcements'),
- ];
-
- $copy = $this->makeCopy(id: 100, userId: 'alice');
- $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
-
- $linksCopy = $this->makePlacement(id: 200, dashboardId: 100, widgetId: 'links', gridX: 0, templatePlacementId: 10);
- $notesCopy = $this->makePlacement(id: 201, dashboardId: 100, widgetId: 'notes', templatePlacementId: null);
-
- $this->placementMapper->method('findByDashboardId')
- ->willReturnMap([
- [1, $templatePlacements],
- [100, [$linksCopy, $notesCopy]],
- ]);
-
- $this->placementMapper->expects($this->once())
- ->method('insert')
- ->with($this->callback(function (WidgetPlacement $p) {
- return $p->getWidgetId() === 'announcements'
- && $p->getDashboardId() === 100
- && $p->getTemplatePlacementId() === 11;
- }));
-
- $this->placementMapper->expects($this->once())
- ->method('update')
- ->with($this->callback(function (WidgetPlacement $p) {
- return $p->getId() === 200 && $p->getGridX() === 4;
- }));
-
- // The user-added "notes" widget must never be deleted under merge.
- $this->placementMapper->expects($this->never())->method('delete');
-
- $result = $this->service->applyResync(
- templateId: 1,
- strategy: TemplateResyncService::STRATEGY_MERGE,
- actingAdminId: 'admin1'
- );
-
- $this->assertSame(1, $result['affectedCount']);
- }
-
- // ---------------------------------------------------------------
- // Overwrite replaces the layout (REQ-RESYNC-003)
- // ---------------------------------------------------------------
-
- public function testOverwriteReplacesTheLayout(): void
- {
- $template = $this->makeTemplate();
- $this->dashboardMapper->method('find')->willReturn($template);
-
- $templatePlacements = [
- $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links'),
- ];
-
- $copy = $this->makeCopy(id: 101, userId: 'bob');
- $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
-
- $linksCopy = $this->makePlacement(id: 300, dashboardId: 101, widgetId: 'links', gridX: 6, templatePlacementId: 10);
- $userAdded = $this->makePlacement(id: 301, dashboardId: 101, widgetId: 'personal-widget', templatePlacementId: null);
-
- $this->placementMapper->method('findByDashboardId')
- ->willReturnMap([
- [1, $templatePlacements],
- [101, [$linksCopy, $userAdded]],
- ]);
-
- // "links" repositioned back to template's gridX=0.
- $this->placementMapper->expects($this->once())
- ->method('update')
- ->with($this->callback(fn (WidgetPlacement $p) => $p->getId() === 300 && $p->getGridX() === 0));
-
- // bob's personally-added widget MUST be removed under overwrite.
- $this->placementMapper->expects($this->once())
- ->method('delete')
- ->with($this->callback(fn (WidgetPlacement $p) => $p->getId() === 301));
-
- $result = $this->service->applyResync(
- templateId: 1,
- strategy: TemplateResyncService::STRATEGY_OVERWRITE,
- actingAdminId: 'admin1'
- );
-
- $this->assertSame(1, $result['affectedCount']);
- }
-
- // ---------------------------------------------------------------
- // Compulsory widgets reconciled under both strategies (REQ-RESYNC-004)
- // ---------------------------------------------------------------
-
- /**
- * @dataProvider strategyProvider
- */
- public function testCompulsoryWidgetRestoredUnderBothStrategies(string $strategy): void
- {
- $template = $this->makeTemplate();
- $this->dashboardMapper->method('find')->willReturn($template);
-
- $compulsoryTemplatePlacement = $this->makePlacement(
- id: 10,
- dashboardId: 1,
- widgetId: 'company-news',
- isCompulsory: 1
- );
-
- $copy = $this->makeCopy(id: 102, userId: 'carol');
- $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
-
- // Carol's copy is missing the compulsory widget entirely.
- $this->placementMapper->method('findByDashboardId')
- ->willReturnMap([
- [1, [$compulsoryTemplatePlacement]],
- [102, []],
- ]);
-
- $this->placementMapper->expects($this->once())
- ->method('insert')
- ->with($this->callback(function (WidgetPlacement $p) {
- return $p->getWidgetId() === 'company-news'
- && $p->getIsCompulsory() === 1
- && $p->getTemplatePlacementId() === 10;
- }));
-
- $result = $this->service->applyResync(
- templateId: 1,
- strategy: $strategy,
- actingAdminId: 'admin1'
- );
-
- $this->assertSame(1, $result['affectedCount']);
- }
-
- /**
- * @dataProvider strategyProvider
- */
- public function testCompulsoryWidgetPositionAlignedUnderBothStrategies(string $strategy): void
- {
- $template = $this->makeTemplate();
- $this->dashboardMapper->method('find')->willReturn($template);
-
- $compulsoryTemplatePlacement = $this->makePlacement(
- id: 10,
- dashboardId: 1,
- widgetId: 'company-news',
- gridX: 8,
- isCompulsory: 1
- );
-
- $copy = $this->makeCopy(id: 103, userId: 'dave');
- $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
-
- // Dave's copy has the compulsory widget at the old position.
- $staleCopyPlacement = $this->makePlacement(
- id: 400,
- dashboardId: 103,
- widgetId: 'company-news',
- gridX: 0,
- isCompulsory: 1,
- templatePlacementId: 10
- );
-
- $this->placementMapper->method('findByDashboardId')
- ->willReturnMap([
- [1, [$compulsoryTemplatePlacement]],
- [103, [$staleCopyPlacement]],
- ]);
-
- $this->placementMapper->expects($this->once())
- ->method('update')
- ->with($this->callback(fn (WidgetPlacement $p) => $p->getId() === 400 && $p->getGridX() === 8));
-
- $this->service->applyResync(
- templateId: 1,
- strategy: $strategy,
- actingAdminId: 'admin1'
- );
- }
-
- public static function strategyProvider(): array
- {
- return [
- 'overwrite' => [TemplateResyncService::STRATEGY_OVERWRITE],
- 'merge' => [TemplateResyncService::STRATEGY_MERGE],
- ];
- }
-
- // ---------------------------------------------------------------
- // Idempotency, audit, notification (REQ-RESYNC-005)
- // ---------------------------------------------------------------
-
- public function testReapplyingAnUnchangedTemplateIsANoOp(): void
- {
- $template = $this->makeTemplate();
- $this->dashboardMapper->method('find')->willReturn($template);
-
- $templatePlacement = $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links');
- $copy = $this->makeCopy(id: 100, userId: 'alice');
- // Already reconciled: matches the template exactly.
- $copyPlacement = $this->makePlacement(id: 200, dashboardId: 100, widgetId: 'links', templatePlacementId: 10);
-
- $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
- $this->placementMapper->method('findByDashboardId')
- ->willReturnMap([
- [1, [$templatePlacement]],
- [100, [$copyPlacement]],
- ]);
-
- $this->placementMapper->expects($this->never())->method('insert');
- $this->placementMapper->expects($this->never())->method('update');
- $this->placementMapper->expects($this->never())->method('delete');
- $this->notificationManager->expects($this->never())->method('notify');
-
- $result = $this->service->applyResync(
- templateId: 1,
- strategy: TemplateResyncService::STRATEGY_OVERWRITE,
- actingAdminId: 'admin1'
- );
-
- $this->assertSame(0, $result['affectedCount']);
-
- // Running it again is still a no-op — no exception, same result.
- $result2 = $this->service->applyResync(
- templateId: 1,
- strategy: TemplateResyncService::STRATEGY_OVERWRITE,
- actingAdminId: 'admin1'
- );
- $this->assertSame(0, $result2['affectedCount']);
- }
-
- public function testAuditRecordIsWrittenOnARealRun(): void
- {
- $template = $this->makeTemplate();
- $this->dashboardMapper->method('find')->willReturn($template);
-
- $templatePlacement = $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links');
- $copies = [];
- $copyPlacementsById = [];
- for ($i = 1; $i <= 12; $i++) {
- $copy = $this->makeCopy(id: 100 + $i, userId: 'user' . $i);
- $copies[] = $copy;
- // Every copy is missing the "links" widget → all 12 affected.
- $copyPlacementsById[100 + $i] = [];
- }
-
- $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn($copies);
-
- $returnMap = [[1, [$templatePlacement]]];
- foreach ($copyPlacementsById as $id => $placements) {
- $returnMap[] = [$id, $placements];
- }
- $this->placementMapper->method('findByDashboardId')->willReturnMap($returnMap);
-
- $this->activityPublisher->expects($this->once())
- ->method('publish')
- ->willReturnCallback(function (
- string $type,
- string $actorUserId,
- string $recipientUserId,
- string $dashboardUuid,
- string $dashboardName,
- string $dashboardLink,
- array $extraParams = []
- ) {
- $this->assertSame('admin1', $actorUserId);
- $this->assertSame(1, $extraParams['templateId']);
- $this->assertSame(TemplateResyncService::STRATEGY_MERGE, $extraParams['strategy']);
- $this->assertSame(12, $extraParams['affectedCount']);
- return true;
- });
-
- $result = $this->service->applyResync(
- templateId: 1,
- strategy: TemplateResyncService::STRATEGY_MERGE,
- actingAdminId: 'admin1'
- );
-
- $this->assertSame(12, $result['affectedCount']);
- }
-
- public function testAffectedUsersAreNotified(): void
- {
- $template = $this->makeTemplate();
- $this->dashboardMapper->method('find')->willReturn($template);
-
- $templatePlacement = $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links');
- $copy = $this->makeCopy(id: 100, userId: 'erin');
- $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
- $this->placementMapper->method('findByDashboardId')
- ->willReturnMap([
- [1, [$templatePlacement]],
- [100, []],
- ]);
-
- $notification = $this->createMock(INotification::class);
- $notification->method('setApp')->willReturnSelf();
- $notification->method('setUser')->with('erin')->willReturnSelf();
- $notification->method('setDateTime')->willReturnSelf();
- $notification->method('setObject')->willReturnSelf();
- $notification->method('setSubject')
- ->with('dashboard_template_resynced', $this->anything())
- ->willReturnSelf();
-
- $this->notificationManager->method('createNotification')->willReturn($notification);
- $this->notificationManager->expects($this->once())
- ->method('notify')
- ->with($notification);
-
- $this->service->applyResync(
- templateId: 1,
- strategy: TemplateResyncService::STRATEGY_MERGE,
- actingAdminId: 'admin1'
- );
- }
-
- // ---------------------------------------------------------------
- // Async for large groups (REQ-RESYNC-005)
- // ---------------------------------------------------------------
-
- public function testLargeGroupsEnqueueTheAsyncJobInsteadOfApplyingInline(): void
- {
- $template = $this->makeTemplate();
- $this->dashboardMapper->method('find')->willReturn($template);
-
- $templatePlacement = $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links');
-
- // Above TemplateResyncService::ASYNC_THRESHOLD (50) — REQ-RESYNC-005
- // "Large groups apply asynchronously" (the spec scenario itself
- // uses 800; 60 already exercises the threshold branch without
- // slowing the suite down).
- $copyCount = TemplateResyncService::ASYNC_THRESHOLD + 10;
- $copies = [];
- $returnMap = [[1, [$templatePlacement]]];
- for ($i = 1; $i <= $copyCount; $i++) {
- $copy = $this->makeCopy(id: 1000 + $i, userId: 'user' . $i);
- $copies[] = $copy;
- $returnMap[] = [1000 + $i, [$this->makePlacement(id: 5000 + $i, dashboardId: 1000 + $i, widgetId: 'links', templatePlacementId: 10)]];
- }
-
- $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn($copies);
- $this->placementMapper->method('findByDashboardId')->willReturnMap($returnMap);
-
- $this->jobList->expects($this->once())
- ->method('add')
- ->with(
- \OCA\LaunchPad\BackgroundJob\TemplateResyncJob::class,
- $this->callback(fn (array $arg) => $arg['templateId'] === 1
- && $arg['strategy'] === TemplateResyncService::STRATEGY_OVERWRITE
- && $arg['actingAdminId'] === 'admin1')
- );
-
- $this->placementMapper->expects($this->never())->method('insert');
- $this->placementMapper->expects($this->never())->method('update');
- $this->placementMapper->expects($this->never())->method('delete');
-
- $result = $this->service->resync(
- templateId: 1,
- strategy: TemplateResyncService::STRATEGY_OVERWRITE,
- dryRun: false,
- actingAdminId: 'admin1'
- );
-
- $this->assertTrue($result['async']);
- $this->assertTrue($result['accepted']);
- $this->assertSame($copyCount, $result['totalCopies']);
- }
-
- // ---------------------------------------------------------------
- // Small helpers
- // ---------------------------------------------------------------
-
- private function findCopyReport(array $copies, int $dashboardId): array
- {
- foreach ($copies as $copy) {
- if ($copy['dashboardId'] === $dashboardId) {
- return $copy;
- }
- }
-
- $this->fail('No report found for dashboard ' . $dashboardId);
- }
+class TemplateResyncServiceTest extends TestCase {
+ /** @var DashboardMapper&MockObject */
+ private $dashboardMapper;
+
+ /** @var WidgetPlacementMapper&MockObject */
+ private $placementMapper;
+
+ /** @var IDBConnection&MockObject */
+ private $db;
+
+ /** @var ActivityPublisher&MockObject */
+ private $activityPublisher;
+
+ /** @var INotificationManager&MockObject */
+ private $notificationManager;
+
+ /** @var IJobList&MockObject */
+ private $jobList;
+
+ /** @var LoggerInterface&MockObject */
+ private $logger;
+
+ private TemplateResyncService $service;
+
+ protected function setUp(): void {
+ parent::setUp();
+
+ $this->dashboardMapper = $this->createMock(DashboardMapper::class);
+ $this->placementMapper = $this->createMock(WidgetPlacementMapper::class);
+ $this->db = $this->createMock(IDBConnection::class);
+ $this->activityPublisher = $this->createMock(ActivityPublisher::class);
+ $this->notificationManager = $this->createMock(INotificationManager::class);
+ $this->jobList = $this->createMock(IJobList::class);
+ $this->logger = $this->createMock(LoggerInterface::class);
+
+ $this->service = new TemplateResyncService(
+ dashboardMapper: $this->dashboardMapper,
+ placementMapper: $this->placementMapper,
+ db: $this->db,
+ activityPublisher: $this->activityPublisher,
+ notificationManager: $this->notificationManager,
+ jobList: $this->jobList,
+ logger: $this->logger,
+ );
+ }
+
+ // ---------------------------------------------------------------
+ // Helpers
+ // ---------------------------------------------------------------
+
+ private function makeTemplate(int $id = 1): Dashboard {
+ $dashboard = new Dashboard();
+ $dashboard->setId($id);
+ $dashboard->setUuid('template-uuid-' . $id);
+ $dashboard->setName('Marketing Dashboard');
+ $dashboard->setType(Dashboard::TYPE_ADMIN_TEMPLATE);
+ $dashboard->setUserId(null);
+
+ return $dashboard;
+ }
+
+ private function makeUserDashboard(int $id = 5): Dashboard {
+ $dashboard = new Dashboard();
+ $dashboard->setId($id);
+ $dashboard->setUuid('user-dashboard-uuid-' . $id);
+ $dashboard->setName('My Dashboard');
+ $dashboard->setType(Dashboard::TYPE_USER);
+ $dashboard->setUserId('alice');
+
+ return $dashboard;
+ }
+
+ private function makeCopy(int $id, string $userId): Dashboard {
+ $dashboard = new Dashboard();
+ $dashboard->setId($id);
+ $dashboard->setUuid('copy-uuid-' . $id);
+ $dashboard->setName('Marketing Dashboard');
+ $dashboard->setType(Dashboard::TYPE_USER);
+ $dashboard->setUserId($userId);
+ $dashboard->setBasedOnTemplate(1);
+
+ return $dashboard;
+ }
+
+ private function makePlacement(
+ int $id,
+ int $dashboardId,
+ string $widgetId = 'w1',
+ int $gridX = 0,
+ int $isCompulsory = 0,
+ ?int $templatePlacementId = null,
+ ): WidgetPlacement {
+ $placement = new WidgetPlacement();
+ $placement->setId($id);
+ $placement->setDashboardId($dashboardId);
+ $placement->setWidgetId($widgetId);
+ $placement->setGridX($gridX);
+ $placement->setGridY(0);
+ $placement->setGridWidth(4);
+ $placement->setGridHeight(4);
+ $placement->setIsCompulsory($isCompulsory);
+ $placement->setIsVisible(1);
+ $placement->setShowTitle(1);
+ $placement->setSortOrder(0);
+ $placement->setRequiresAcknowledgement(0);
+ $placement->setReacknowledgeOnChange(0);
+ $placement->setAcknowledgementContentVersion(1);
+ $placement->setTemplatePlacementId($templatePlacementId);
+
+ return $placement;
+ }
+
+ // ---------------------------------------------------------------
+ // Validation
+ // ---------------------------------------------------------------
+
+ public function testInvalidStrategyIsRejected(): void {
+ $this->dashboardMapper->method('find')->willReturn($this->makeTemplate());
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->service->resync(
+ templateId: 1,
+ strategy: 'replace-all',
+ dryRun: true,
+ actingAdminId: 'admin1'
+ );
+ }
+
+ public function testNonTemplateDashboardIsRejected(): void {
+ $this->dashboardMapper->method('find')->willReturn($this->makeUserDashboard());
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->expectExceptionMessage('Not an admin template');
+ $this->service->resync(
+ templateId: 5,
+ strategy: TemplateResyncService::STRATEGY_OVERWRITE,
+ dryRun: true,
+ actingAdminId: 'admin1'
+ );
+ }
+
+ public function testUnknownTemplateIdIsRejected(): void {
+ $this->dashboardMapper->method('find')
+ ->willThrowException(new DoesNotExistException(msg: 'not found'));
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->service->resync(
+ templateId: 999,
+ strategy: TemplateResyncService::STRATEGY_OVERWRITE,
+ dryRun: true,
+ actingAdminId: 'admin1'
+ );
+ }
+
+ // ---------------------------------------------------------------
+ // Dry-run — reports without mutating (REQ-RESYNC-002)
+ // ---------------------------------------------------------------
+
+ public function testDryRunReportsAffectedCopiesWithoutMutating(): void {
+ $template = $this->makeTemplate();
+ $this->dashboardMapper->method('find')->willReturn($template);
+
+ // Template now has 2 placements; the announcements one is new.
+ $templatePlacements = [
+ $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links'),
+ $this->makePlacement(id: 11, dashboardId: 1, widgetId: 'announcements'),
+ ];
+
+ $copyA = $this->makeCopy(id: 100, userId: 'alice');
+ $copyB = $this->makeCopy(id: 101, userId: 'bob');
+
+ $this->dashboardMapper->method('findByBasedOnTemplate')
+ ->willReturn([$copyA, $copyB]);
+
+ // alice's copy still has only the original "links" placement,
+ // cloned from template placement 10.
+ $aliceCopyPlacements = [
+ $this->makePlacement(id: 200, dashboardId: 100, widgetId: 'links', templatePlacementId: 10),
+ ];
+ // bob's copy also has "links" plus a personal "notes" widget.
+ $bobCopyPlacements = [
+ $this->makePlacement(id: 201, dashboardId: 101, widgetId: 'links', templatePlacementId: 10),
+ $this->makePlacement(id: 202, dashboardId: 101, widgetId: 'notes', templatePlacementId: null),
+ ];
+
+ $this->placementMapper->method('findByDashboardId')
+ ->willReturnMap([
+ [1, $templatePlacements],
+ [100, $aliceCopyPlacements],
+ [101, $bobCopyPlacements],
+ ]);
+
+ $this->placementMapper->expects($this->never())->method('insert');
+ $this->placementMapper->expects($this->never())->method('update');
+ $this->placementMapper->expects($this->never())->method('delete');
+ $this->activityPublisher->expects($this->never())->method('publish');
+ $this->notificationManager->expects($this->never())->method('notify');
+
+ $result = $this->service->resync(
+ templateId: 1,
+ strategy: TemplateResyncService::STRATEGY_MERGE,
+ dryRun: true,
+ actingAdminId: 'admin1'
+ );
+
+ $this->assertTrue($result['dryRun']);
+ $this->assertFalse($result['async']);
+ $this->assertSame(2, $result['totalCopies']);
+ // Both copies are missing the new "announcements" placement.
+ $this->assertSame(2, $result['affectedCount']);
+
+ $aliceReport = $this->findCopyReport($result['copies'], 100);
+ $this->assertSame(1, $aliceReport['toAdd']);
+ $this->assertSame(0, $aliceReport['toUpdate']);
+ $this->assertSame(0, $aliceReport['toRemove']);
+ $this->assertSame(1, $aliceReport['toPreserve']);
+
+ $bobReport = $this->findCopyReport($result['copies'], 101);
+ $this->assertSame(1, $bobReport['toAdd']);
+ $this->assertSame(0, $bobReport['toRemove']);
+ // bob's personal "notes" widget is preserved under merge.
+ $this->assertSame(2, $bobReport['toPreserve']);
+ }
+
+ public function testDryRunOnUpToDateTemplateReportsNoChanges(): void {
+ $template = $this->makeTemplate();
+ $this->dashboardMapper->method('find')->willReturn($template);
+
+ $templatePlacement = $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links');
+ $copy = $this->makeCopy(id: 100, userId: 'alice');
+ $copyPlacement = $this->makePlacement(id: 200, dashboardId: 100, widgetId: 'links', templatePlacementId: 10);
+
+ $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
+ $this->placementMapper->method('findByDashboardId')
+ ->willReturnMap([
+ [1, [$templatePlacement]],
+ [100, [$copyPlacement]],
+ ]);
+
+ $result = $this->service->resync(
+ templateId: 1,
+ strategy: TemplateResyncService::STRATEGY_OVERWRITE,
+ dryRun: true,
+ actingAdminId: 'admin1'
+ );
+
+ $this->assertSame(0, $result['affectedCount']);
+ $report = $this->findCopyReport($result['copies'], 100);
+ $this->assertSame(0, $report['toAdd']);
+ $this->assertSame(0, $report['toUpdate']);
+ $this->assertSame(0, $report['toRemove']);
+ $this->assertSame(1, $report['toPreserve']);
+ }
+
+ // ---------------------------------------------------------------
+ // Merge preserves user-added widgets (REQ-RESYNC-003)
+ // ---------------------------------------------------------------
+
+ public function testMergeKeepsUserAddedWidgetsWhileApplyingTemplateChanges(): void {
+ $template = $this->makeTemplate();
+ $this->dashboardMapper->method('find')->willReturn($template);
+
+ // Template: "links" moved to gridX=4, new "announcements" added.
+ $templatePlacements = [
+ $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links', gridX: 4),
+ $this->makePlacement(id: 11, dashboardId: 1, widgetId: 'announcements'),
+ ];
+
+ $copy = $this->makeCopy(id: 100, userId: 'alice');
+ $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
+
+ $linksCopy = $this->makePlacement(id: 200, dashboardId: 100, widgetId: 'links', gridX: 0, templatePlacementId: 10);
+ $notesCopy = $this->makePlacement(id: 201, dashboardId: 100, widgetId: 'notes', templatePlacementId: null);
+
+ $this->placementMapper->method('findByDashboardId')
+ ->willReturnMap([
+ [1, $templatePlacements],
+ [100, [$linksCopy, $notesCopy]],
+ ]);
+
+ $this->placementMapper->expects($this->once())
+ ->method('insert')
+ ->with($this->callback(function (WidgetPlacement $p) {
+ return $p->getWidgetId() === 'announcements'
+ && $p->getDashboardId() === 100
+ && $p->getTemplatePlacementId() === 11;
+ }));
+
+ $this->placementMapper->expects($this->once())
+ ->method('update')
+ ->with($this->callback(function (WidgetPlacement $p) {
+ return $p->getId() === 200 && $p->getGridX() === 4;
+ }));
+
+ // The user-added "notes" widget must never be deleted under merge.
+ $this->placementMapper->expects($this->never())->method('delete');
+
+ $result = $this->service->applyResync(
+ templateId: 1,
+ strategy: TemplateResyncService::STRATEGY_MERGE,
+ actingAdminId: 'admin1'
+ );
+
+ $this->assertSame(1, $result['affectedCount']);
+ }
+
+ // ---------------------------------------------------------------
+ // Overwrite replaces the layout (REQ-RESYNC-003)
+ // ---------------------------------------------------------------
+
+ public function testOverwriteReplacesTheLayout(): void {
+ $template = $this->makeTemplate();
+ $this->dashboardMapper->method('find')->willReturn($template);
+
+ $templatePlacements = [
+ $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links'),
+ ];
+
+ $copy = $this->makeCopy(id: 101, userId: 'bob');
+ $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
+
+ $linksCopy = $this->makePlacement(id: 300, dashboardId: 101, widgetId: 'links', gridX: 6, templatePlacementId: 10);
+ $userAdded = $this->makePlacement(id: 301, dashboardId: 101, widgetId: 'personal-widget', templatePlacementId: null);
+
+ $this->placementMapper->method('findByDashboardId')
+ ->willReturnMap([
+ [1, $templatePlacements],
+ [101, [$linksCopy, $userAdded]],
+ ]);
+
+ // "links" repositioned back to template's gridX=0.
+ $this->placementMapper->expects($this->once())
+ ->method('update')
+ ->with($this->callback(fn (WidgetPlacement $p) => $p->getId() === 300 && $p->getGridX() === 0));
+
+ // bob's personally-added widget MUST be removed under overwrite.
+ $this->placementMapper->expects($this->once())
+ ->method('delete')
+ ->with($this->callback(fn (WidgetPlacement $p) => $p->getId() === 301));
+
+ $result = $this->service->applyResync(
+ templateId: 1,
+ strategy: TemplateResyncService::STRATEGY_OVERWRITE,
+ actingAdminId: 'admin1'
+ );
+
+ $this->assertSame(1, $result['affectedCount']);
+ }
+
+ // ---------------------------------------------------------------
+ // Compulsory widgets reconciled under both strategies (REQ-RESYNC-004)
+ // ---------------------------------------------------------------
+
+ /**
+ * @dataProvider strategyProvider
+ */
+ public function testCompulsoryWidgetRestoredUnderBothStrategies(string $strategy): void {
+ $template = $this->makeTemplate();
+ $this->dashboardMapper->method('find')->willReturn($template);
+
+ $compulsoryTemplatePlacement = $this->makePlacement(
+ id: 10,
+ dashboardId: 1,
+ widgetId: 'company-news',
+ isCompulsory: 1
+ );
+
+ $copy = $this->makeCopy(id: 102, userId: 'carol');
+ $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
+
+ // Carol's copy is missing the compulsory widget entirely.
+ $this->placementMapper->method('findByDashboardId')
+ ->willReturnMap([
+ [1, [$compulsoryTemplatePlacement]],
+ [102, []],
+ ]);
+
+ $this->placementMapper->expects($this->once())
+ ->method('insert')
+ ->with($this->callback(function (WidgetPlacement $p) {
+ return $p->getWidgetId() === 'company-news'
+ && $p->getIsCompulsory() === 1
+ && $p->getTemplatePlacementId() === 10;
+ }));
+
+ $result = $this->service->applyResync(
+ templateId: 1,
+ strategy: $strategy,
+ actingAdminId: 'admin1'
+ );
+
+ $this->assertSame(1, $result['affectedCount']);
+ }
+
+ /**
+ * @dataProvider strategyProvider
+ */
+ public function testCompulsoryWidgetPositionAlignedUnderBothStrategies(string $strategy): void {
+ $template = $this->makeTemplate();
+ $this->dashboardMapper->method('find')->willReturn($template);
+
+ $compulsoryTemplatePlacement = $this->makePlacement(
+ id: 10,
+ dashboardId: 1,
+ widgetId: 'company-news',
+ gridX: 8,
+ isCompulsory: 1
+ );
+
+ $copy = $this->makeCopy(id: 103, userId: 'dave');
+ $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
+
+ // Dave's copy has the compulsory widget at the old position.
+ $staleCopyPlacement = $this->makePlacement(
+ id: 400,
+ dashboardId: 103,
+ widgetId: 'company-news',
+ gridX: 0,
+ isCompulsory: 1,
+ templatePlacementId: 10
+ );
+
+ $this->placementMapper->method('findByDashboardId')
+ ->willReturnMap([
+ [1, [$compulsoryTemplatePlacement]],
+ [103, [$staleCopyPlacement]],
+ ]);
+
+ $this->placementMapper->expects($this->once())
+ ->method('update')
+ ->with($this->callback(fn (WidgetPlacement $p) => $p->getId() === 400 && $p->getGridX() === 8));
+
+ $this->service->applyResync(
+ templateId: 1,
+ strategy: $strategy,
+ actingAdminId: 'admin1'
+ );
+ }
+
+ public static function strategyProvider(): array {
+ return [
+ 'overwrite' => [TemplateResyncService::STRATEGY_OVERWRITE],
+ 'merge' => [TemplateResyncService::STRATEGY_MERGE],
+ ];
+ }
+
+ // ---------------------------------------------------------------
+ // Idempotency, audit, notification (REQ-RESYNC-005)
+ // ---------------------------------------------------------------
+
+ public function testReapplyingAnUnchangedTemplateIsANoOp(): void {
+ $template = $this->makeTemplate();
+ $this->dashboardMapper->method('find')->willReturn($template);
+
+ $templatePlacement = $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links');
+ $copy = $this->makeCopy(id: 100, userId: 'alice');
+ // Already reconciled: matches the template exactly.
+ $copyPlacement = $this->makePlacement(id: 200, dashboardId: 100, widgetId: 'links', templatePlacementId: 10);
+
+ $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
+ $this->placementMapper->method('findByDashboardId')
+ ->willReturnMap([
+ [1, [$templatePlacement]],
+ [100, [$copyPlacement]],
+ ]);
+
+ $this->placementMapper->expects($this->never())->method('insert');
+ $this->placementMapper->expects($this->never())->method('update');
+ $this->placementMapper->expects($this->never())->method('delete');
+ $this->notificationManager->expects($this->never())->method('notify');
+
+ $result = $this->service->applyResync(
+ templateId: 1,
+ strategy: TemplateResyncService::STRATEGY_OVERWRITE,
+ actingAdminId: 'admin1'
+ );
+
+ $this->assertSame(0, $result['affectedCount']);
+
+ // Running it again is still a no-op — no exception, same result.
+ $result2 = $this->service->applyResync(
+ templateId: 1,
+ strategy: TemplateResyncService::STRATEGY_OVERWRITE,
+ actingAdminId: 'admin1'
+ );
+ $this->assertSame(0, $result2['affectedCount']);
+ }
+
+ public function testAuditRecordIsWrittenOnARealRun(): void {
+ $template = $this->makeTemplate();
+ $this->dashboardMapper->method('find')->willReturn($template);
+
+ $templatePlacement = $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links');
+ $copies = [];
+ $copyPlacementsById = [];
+ for ($i = 1; $i <= 12; $i++) {
+ $copy = $this->makeCopy(id: 100 + $i, userId: 'user' . $i);
+ $copies[] = $copy;
+ // Every copy is missing the "links" widget → all 12 affected.
+ $copyPlacementsById[100 + $i] = [];
+ }
+
+ $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn($copies);
+
+ $returnMap = [[1, [$templatePlacement]]];
+ foreach ($copyPlacementsById as $id => $placements) {
+ $returnMap[] = [$id, $placements];
+ }
+ $this->placementMapper->method('findByDashboardId')->willReturnMap($returnMap);
+
+ $this->activityPublisher->expects($this->once())
+ ->method('publish')
+ ->willReturnCallback(function (
+ string $type,
+ string $actorUserId,
+ string $recipientUserId,
+ string $dashboardUuid,
+ string $dashboardName,
+ string $dashboardLink,
+ array $extraParams = [],
+ ) {
+ $this->assertSame('admin1', $actorUserId);
+ $this->assertSame(1, $extraParams['templateId']);
+ $this->assertSame(TemplateResyncService::STRATEGY_MERGE, $extraParams['strategy']);
+ $this->assertSame(12, $extraParams['affectedCount']);
+ return true;
+ });
+
+ $result = $this->service->applyResync(
+ templateId: 1,
+ strategy: TemplateResyncService::STRATEGY_MERGE,
+ actingAdminId: 'admin1'
+ );
+
+ $this->assertSame(12, $result['affectedCount']);
+ }
+
+ public function testAffectedUsersAreNotified(): void {
+ $template = $this->makeTemplate();
+ $this->dashboardMapper->method('find')->willReturn($template);
+
+ $templatePlacement = $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links');
+ $copy = $this->makeCopy(id: 100, userId: 'erin');
+ $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn([$copy]);
+ $this->placementMapper->method('findByDashboardId')
+ ->willReturnMap([
+ [1, [$templatePlacement]],
+ [100, []],
+ ]);
+
+ $notification = $this->createMock(INotification::class);
+ $notification->method('setApp')->willReturnSelf();
+ $notification->method('setUser')->with('erin')->willReturnSelf();
+ $notification->method('setDateTime')->willReturnSelf();
+ $notification->method('setObject')->willReturnSelf();
+ $notification->method('setSubject')
+ ->with('dashboard_template_resynced', $this->anything())
+ ->willReturnSelf();
+
+ $this->notificationManager->method('createNotification')->willReturn($notification);
+ $this->notificationManager->expects($this->once())
+ ->method('notify')
+ ->with($notification);
+
+ $this->service->applyResync(
+ templateId: 1,
+ strategy: TemplateResyncService::STRATEGY_MERGE,
+ actingAdminId: 'admin1'
+ );
+ }
+
+ // ---------------------------------------------------------------
+ // Async for large groups (REQ-RESYNC-005)
+ // ---------------------------------------------------------------
+
+ public function testLargeGroupsEnqueueTheAsyncJobInsteadOfApplyingInline(): void {
+ $template = $this->makeTemplate();
+ $this->dashboardMapper->method('find')->willReturn($template);
+
+ $templatePlacement = $this->makePlacement(id: 10, dashboardId: 1, widgetId: 'links');
+
+ // Above TemplateResyncService::ASYNC_THRESHOLD (50) — REQ-RESYNC-005
+ // "Large groups apply asynchronously" (the spec scenario itself
+ // uses 800; 60 already exercises the threshold branch without
+ // slowing the suite down).
+ $copyCount = TemplateResyncService::ASYNC_THRESHOLD + 10;
+ $copies = [];
+ $returnMap = [[1, [$templatePlacement]]];
+ for ($i = 1; $i <= $copyCount; $i++) {
+ $copy = $this->makeCopy(id: 1000 + $i, userId: 'user' . $i);
+ $copies[] = $copy;
+ $returnMap[] = [1000 + $i, [$this->makePlacement(id: 5000 + $i, dashboardId: 1000 + $i, widgetId: 'links', templatePlacementId: 10)]];
+ }
+
+ $this->dashboardMapper->method('findByBasedOnTemplate')->willReturn($copies);
+ $this->placementMapper->method('findByDashboardId')->willReturnMap($returnMap);
+
+ $this->jobList->expects($this->once())
+ ->method('add')
+ ->with(
+ \OCA\LaunchPad\BackgroundJob\TemplateResyncJob::class,
+ $this->callback(fn (array $arg) => $arg['templateId'] === 1
+ && $arg['strategy'] === TemplateResyncService::STRATEGY_OVERWRITE
+ && $arg['actingAdminId'] === 'admin1')
+ );
+
+ $this->placementMapper->expects($this->never())->method('insert');
+ $this->placementMapper->expects($this->never())->method('update');
+ $this->placementMapper->expects($this->never())->method('delete');
+
+ $result = $this->service->resync(
+ templateId: 1,
+ strategy: TemplateResyncService::STRATEGY_OVERWRITE,
+ dryRun: false,
+ actingAdminId: 'admin1'
+ );
+
+ $this->assertTrue($result['async']);
+ $this->assertTrue($result['accepted']);
+ $this->assertSame($copyCount, $result['totalCopies']);
+ }
+
+ // ---------------------------------------------------------------
+ // Small helpers
+ // ---------------------------------------------------------------
+
+ private function findCopyReport(array $copies, int $dashboardId): array {
+ foreach ($copies as $copy) {
+ if ($copy['dashboardId'] === $dashboardId) {
+ return $copy;
+ }
+ }
+
+ $this->fail('No report found for dashboard ' . $dashboardId);
+ }
}
diff --git a/tests/Unit/Service/TileAnalyticsServiceTest.php b/tests/Unit/Service/TileAnalyticsServiceTest.php
index 8df742d0..387cab8b 100644
--- a/tests/Unit/Service/TileAnalyticsServiceTest.php
+++ b/tests/Unit/Service/TileAnalyticsServiceTest.php
@@ -34,359 +34,340 @@
use OCP\AppFramework\Db\DoesNotExistException;
use PHPUnit\Framework\TestCase;
-class TileAnalyticsServiceTest extends TestCase
-{
- private TileClickMapper $tileClickMapper;
- private WidgetPlacementMapper $placementMapper;
- private DashboardMapper $dashboardMapper;
- private UniqueViewerDedup $dedup;
- private AnalyticsService $analyticsService;
- private TileAnalyticsService $service;
-
- protected function setUp(): void
- {
- $this->tileClickMapper = $this->createMock(
- originalClassName: TileClickMapper::class
- );
- $this->placementMapper = $this->createMock(
- originalClassName: WidgetPlacementMapper::class
- );
- $this->dashboardMapper = $this->createMock(
- originalClassName: DashboardMapper::class
- );
- $this->dedup = $this->createMock(
- originalClassName: UniqueViewerDedup::class
- );
- $this->analyticsService = $this->createMock(
- originalClassName: AnalyticsService::class
- );
-
- $this->service = new TileAnalyticsService(
- tileClickMapper: $this->tileClickMapper,
- placementMapper: $this->placementMapper,
- dashboardMapper: $this->dashboardMapper,
- dedup: $this->dedup,
- analyticsService: $this->analyticsService,
- );
- }
-
- private function makePlacement(int $dashboardId=1): WidgetPlacement
- {
- $placement = new WidgetPlacement();
- $placement->setDashboardId($dashboardId);
-
- return $placement;
- }
-
- private function makeDashboard(string $uuid='dsh-1'): Dashboard
- {
- $dashboard = new Dashboard();
- $dashboard->setUuid($uuid);
-
- return $dashboard;
- }
-
- public function testRecordClickThrowsWhenPlacementMissing(): void
- {
- $this->placementMapper
- ->method('find')
- ->willThrowException(
- exception: new DoesNotExistException(msg: 'gone')
- );
-
- $this->expectException(exception: DoesNotExistException::class);
-
- $this->service->recordClick(placementId: 999, userId: 'alice');
- }
-
- /**
- * REQ-TANLT-003 — recording is a no-op (no counter change, no
- * cache write) when analytics_enabled=false. This reuses
- * AnalyticsService::isGloballyEnabled() rather than a second
- * setting.
- */
- public function testRecordClickSkipsWhenGloballyDisabled(): void
- {
- $this->placementMapper->method('find')
- ->willReturn(value: $this->makePlacement());
- $this->analyticsService->method('isGloballyEnabled')->willReturn(false);
- $this->dedup->expects($this->never())->method('isNewUniqueViewer');
- $this->tileClickMapper->expects($this->never())->method('upsertClick');
-
- $result = $this->service->recordClick(placementId: 1, userId: 'alice');
-
- $this->assertFalse($result);
- }
-
- /**
- * REQ-TANLT-003 — recording is a no-op for a user with
- * analytics_optout=true. This reuses
- * AnalyticsService::isUserOptedOut() rather than a second
- * opt-out surface.
- */
- public function testRecordClickSkipsWhenUserOptedOut(): void
- {
- $this->placementMapper->method('find')
- ->willReturn(value: $this->makePlacement());
- $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
- $this->analyticsService->method('isUserOptedOut')->willReturn(true);
- $this->dedup->expects($this->never())->method('isNewUniqueViewer');
- $this->tileClickMapper->expects($this->never())->method('upsertClick');
-
- $result = $this->service->recordClick(placementId: 1, userId: 'eve');
-
- $this->assertFalse($result);
- }
-
- /**
- * Repeat clicks by the SAME actor on the SAME day increment
- * clickCount but NOT uniqueActorCount a second time.
- */
- public function testRecordClickLeavesUniqueAtZeroForRepeatActor(): void
- {
- $this->placementMapper->method('find')
- ->willReturn(value: $this->makePlacement());
- $this->dashboardMapper->method('find')
- ->willReturn(value: $this->makeDashboard());
- $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
- $this->analyticsService->method('isUserOptedOut')->willReturn(false);
- $this->dedup->method('isNewUniqueViewer')->willReturn(false);
-
- $this->tileClickMapper->expects($this->once())
- ->method('upsertClick')
- ->with(
- $this->equalTo('1'),
- $this->equalTo('dsh-1'),
- $this->isType(type: 'string'),
- 1,
- 0
- );
-
- $result = $this->service->recordClick(placementId: 1, userId: 'alice');
-
- $this->assertTrue($result);
- }
-
- /**
- * A NEW actor on the same day increments both counters.
- */
- public function testRecordClickIncrementsBothCountersForNewActor(): void
- {
- $this->placementMapper->method('find')
- ->willReturn(value: $this->makePlacement());
- $this->dashboardMapper->method('find')
- ->willReturn(value: $this->makeDashboard());
- $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
- $this->analyticsService->method('isUserOptedOut')->willReturn(false);
- $this->dedup->method('isNewUniqueViewer')->willReturn(true);
-
- $this->tileClickMapper->expects($this->once())
- ->method('upsertClick')
- ->with(
- $this->equalTo('1'),
- $this->equalTo('dsh-1'),
- $this->isType(type: 'string'),
- 1,
- 1
- );
-
- $result = $this->service->recordClick(placementId: 1, userId: 'bob');
-
- $this->assertTrue($result);
- }
-
- /**
- * REQ-TANLT-002 — the dedup call MUST reuse the SAME
- * UniqueViewerDedup instance (salted-daily-hash), scoped by
- * placement UUID, not a second dedup mechanism.
- */
- public function testRecordClickReusesSharedDedupScopedByPlacement(): void
- {
- $this->placementMapper->method('find')
- ->willReturn(value: $this->makePlacement());
- $this->dashboardMapper->method('find')
- ->willReturn(value: $this->makeDashboard());
- $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
- $this->analyticsService->method('isUserOptedOut')->willReturn(false);
-
- $this->dedup->expects($this->once())
- ->method('isNewUniqueViewer')
- ->with(
- $this->equalTo('alice'),
- $this->isType(type: 'string'),
- $this->equalTo('42')
- )
- ->willReturn(true);
-
- $this->service->recordClick(placementId: 42, userId: 'alice');
- }
-
- /**
- * Orphan placement (owning dashboard already deleted) still
- * records the click rather than silently dropping it.
- */
- public function testRecordClickToleratesOrphanPlacement(): void
- {
- $this->placementMapper->method('find')
- ->willReturn(value: $this->makePlacement());
- $this->dashboardMapper->method('find')
- ->willThrowException(
- exception: new DoesNotExistException(msg: 'gone')
- );
- $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
- $this->analyticsService->method('isUserOptedOut')->willReturn(false);
- $this->dedup->method('isNewUniqueViewer')->willReturn(true);
-
- $this->tileClickMapper->expects($this->once())
- ->method('upsertClick')
- ->with(
- $this->equalTo('1'),
- $this->equalTo(''),
- $this->isType(type: 'string'),
- 1,
- 1
- );
-
- $result = $this->service->recordClick(placementId: 1, userId: 'alice');
-
- $this->assertTrue($result);
- }
-
- public function testIsTrackingActiveForFalseWhenGloballyDisabled(): void
- {
- $this->analyticsService->method('isGloballyEnabled')->willReturn(false);
-
- $this->assertFalse($this->service->isTrackingActiveFor(userId: 'alice'));
- }
-
- public function testIsTrackingActiveForFalseWhenUserOptedOut(): void
- {
- $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
- $this->analyticsService->method('isUserOptedOut')->willReturn(true);
-
- $this->assertFalse($this->service->isTrackingActiveFor(userId: 'eve'));
- }
-
- public function testIsTrackingActiveForTrueByDefault(): void
- {
- $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
- $this->analyticsService->method('isUserOptedOut')->willReturn(false);
-
- $this->assertTrue($this->service->isTrackingActiveFor(userId: 'frank'));
- }
-
- public function testGetTopTilesDelegatesToMapperWithDateRange(): void
- {
- $this->tileClickMapper->expects($this->once())
- ->method('findTopTilesInRange')
- ->with(
- $this->isType(type: 'string'),
- $this->isType(type: 'string'),
- 10
- )
- ->willReturn(
- value: [
- [
- 'placementUuid' => '1',
- 'dashboardUuid' => 'dsh-1',
- 'clickCount' => 120,
- 'uniqueActorCount' => 80,
- ],
- ]
- );
-
- $rows = $this->service->getTopTiles(period: '7d', limit: 10);
-
- $this->assertCount(1, $rows);
- $this->assertSame(120, $rows[0]['clickCount']);
- }
-
- public function testGetDashboardBreakdownDelegatesToMapper(): void
- {
- $this->tileClickMapper->expects($this->once())
- ->method('findByDashboardInRange')
- ->with(
- $this->equalTo('dsh-9'),
- $this->isType(type: 'string'),
- $this->isType(type: 'string')
- )
- ->willReturn(
- value: [
- [
- 'placementUuid' => '3',
- 'clickCount' => 40,
- 'uniqueActorCount' => 12,
- ],
- ]
- );
-
- $rows = $this->service->getDashboardBreakdown(
- dashboardUuid: 'dsh-9',
- period: '30d'
- );
-
- $this->assertCount(1, $rows);
- $this->assertSame(40, $rows[0]['clickCount']);
- }
-
- public function testGenerateCsvExportProducesHeaderAndRows(): void
- {
- $row = new TileClick();
- $row->setPlacementUuid('1');
- $row->setDashboardUuid('dsh-1');
- $row->setClickBucket('2026-05-01');
- $row->setClickCount(2);
- $row->setUniqueActorCount(1);
- $this->tileClickMapper->method('findAllInRange')->willReturn(
- value: [$row]
- );
-
- $csv = $this->service->generateCsvExport(period: '7d');
-
- $this->assertStringContainsString(
- needle: 'placementUuid',
- haystack: $csv
- );
- $this->assertStringContainsString(
- needle: 'dsh-1',
- haystack: $csv
- );
- $this->assertStringContainsString(
- needle: '2026-05-01',
- haystack: $csv
- );
- }
-
- public function testCsvExportFilenameMatchesExpectedPattern(): void
- {
- $name = $this->service->csvExportFilename();
-
- $this->assertMatchesRegularExpression(
- pattern: '/^tile-analytics-\d{4}-\d{2}-\d{2}\.csv$/',
- string: $name
- );
- }
-
- /**
- * No per-event rows are ever persisted — the ONLY write method on
- * the mapper is `upsertClick()`, which the service calls exactly
- * once per (successful) `recordClick()` invocation, never an
- * `insert()`/raw-row write path.
- */
- public function testRecordClickNeverCallsAnythingOtherThanUpsert(): void
- {
- $this->placementMapper->method('find')
- ->willReturn(value: $this->makePlacement());
- $this->dashboardMapper->method('find')
- ->willReturn(value: $this->makeDashboard());
- $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
- $this->analyticsService->method('isUserOptedOut')->willReturn(false);
- $this->dedup->method('isNewUniqueViewer')->willReturn(true);
-
- $this->tileClickMapper->expects($this->once())->method('upsertClick');
- $this->tileClickMapper->expects($this->never())->method('findAllInRange');
- $this->tileClickMapper->expects($this->never())->method('findTopTilesInRange');
-
- $this->service->recordClick(placementId: 1, userId: 'alice');
- }
+class TileAnalyticsServiceTest extends TestCase {
+ private TileClickMapper $tileClickMapper;
+ private WidgetPlacementMapper $placementMapper;
+ private DashboardMapper $dashboardMapper;
+ private UniqueViewerDedup $dedup;
+ private AnalyticsService $analyticsService;
+ private TileAnalyticsService $service;
+
+ protected function setUp(): void {
+ $this->tileClickMapper = $this->createMock(
+ originalClassName: TileClickMapper::class
+ );
+ $this->placementMapper = $this->createMock(
+ originalClassName: WidgetPlacementMapper::class
+ );
+ $this->dashboardMapper = $this->createMock(
+ originalClassName: DashboardMapper::class
+ );
+ $this->dedup = $this->createMock(
+ originalClassName: UniqueViewerDedup::class
+ );
+ $this->analyticsService = $this->createMock(
+ originalClassName: AnalyticsService::class
+ );
+
+ $this->service = new TileAnalyticsService(
+ tileClickMapper: $this->tileClickMapper,
+ placementMapper: $this->placementMapper,
+ dashboardMapper: $this->dashboardMapper,
+ dedup: $this->dedup,
+ analyticsService: $this->analyticsService,
+ );
+ }
+
+ private function makePlacement(int $dashboardId = 1): WidgetPlacement {
+ $placement = new WidgetPlacement();
+ $placement->setDashboardId($dashboardId);
+
+ return $placement;
+ }
+
+ private function makeDashboard(string $uuid = 'dsh-1'): Dashboard {
+ $dashboard = new Dashboard();
+ $dashboard->setUuid($uuid);
+
+ return $dashboard;
+ }
+
+ public function testRecordClickThrowsWhenPlacementMissing(): void {
+ $this->placementMapper
+ ->method('find')
+ ->willThrowException(
+ exception: new DoesNotExistException(msg: 'gone')
+ );
+
+ $this->expectException(exception: DoesNotExistException::class);
+
+ $this->service->recordClick(placementId: 999, userId: 'alice');
+ }
+
+ /**
+ * REQ-TANLT-003 — recording is a no-op (no counter change, no
+ * cache write) when analytics_enabled=false. This reuses
+ * AnalyticsService::isGloballyEnabled() rather than a second
+ * setting.
+ */
+ public function testRecordClickSkipsWhenGloballyDisabled(): void {
+ $this->placementMapper->method('find')
+ ->willReturn(value: $this->makePlacement());
+ $this->analyticsService->method('isGloballyEnabled')->willReturn(false);
+ $this->dedup->expects($this->never())->method('isNewUniqueViewer');
+ $this->tileClickMapper->expects($this->never())->method('upsertClick');
+
+ $result = $this->service->recordClick(placementId: 1, userId: 'alice');
+
+ $this->assertFalse($result);
+ }
+
+ /**
+ * REQ-TANLT-003 — recording is a no-op for a user with
+ * analytics_optout=true. This reuses
+ * AnalyticsService::isUserOptedOut() rather than a second
+ * opt-out surface.
+ */
+ public function testRecordClickSkipsWhenUserOptedOut(): void {
+ $this->placementMapper->method('find')
+ ->willReturn(value: $this->makePlacement());
+ $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
+ $this->analyticsService->method('isUserOptedOut')->willReturn(true);
+ $this->dedup->expects($this->never())->method('isNewUniqueViewer');
+ $this->tileClickMapper->expects($this->never())->method('upsertClick');
+
+ $result = $this->service->recordClick(placementId: 1, userId: 'eve');
+
+ $this->assertFalse($result);
+ }
+
+ /**
+ * Repeat clicks by the SAME actor on the SAME day increment
+ * clickCount but NOT uniqueActorCount a second time.
+ */
+ public function testRecordClickLeavesUniqueAtZeroForRepeatActor(): void {
+ $this->placementMapper->method('find')
+ ->willReturn(value: $this->makePlacement());
+ $this->dashboardMapper->method('find')
+ ->willReturn(value: $this->makeDashboard());
+ $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
+ $this->analyticsService->method('isUserOptedOut')->willReturn(false);
+ $this->dedup->method('isNewUniqueViewer')->willReturn(false);
+
+ $this->tileClickMapper->expects($this->once())
+ ->method('upsertClick')
+ ->with(
+ $this->equalTo('1'),
+ $this->equalTo('dsh-1'),
+ $this->isType(type: 'string'),
+ 1,
+ 0
+ );
+
+ $result = $this->service->recordClick(placementId: 1, userId: 'alice');
+
+ $this->assertTrue($result);
+ }
+
+ /**
+ * A NEW actor on the same day increments both counters.
+ */
+ public function testRecordClickIncrementsBothCountersForNewActor(): void {
+ $this->placementMapper->method('find')
+ ->willReturn(value: $this->makePlacement());
+ $this->dashboardMapper->method('find')
+ ->willReturn(value: $this->makeDashboard());
+ $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
+ $this->analyticsService->method('isUserOptedOut')->willReturn(false);
+ $this->dedup->method('isNewUniqueViewer')->willReturn(true);
+
+ $this->tileClickMapper->expects($this->once())
+ ->method('upsertClick')
+ ->with(
+ $this->equalTo('1'),
+ $this->equalTo('dsh-1'),
+ $this->isType(type: 'string'),
+ 1,
+ 1
+ );
+
+ $result = $this->service->recordClick(placementId: 1, userId: 'bob');
+
+ $this->assertTrue($result);
+ }
+
+ /**
+ * REQ-TANLT-002 — the dedup call MUST reuse the SAME
+ * UniqueViewerDedup instance (salted-daily-hash), scoped by
+ * placement UUID, not a second dedup mechanism.
+ */
+ public function testRecordClickReusesSharedDedupScopedByPlacement(): void {
+ $this->placementMapper->method('find')
+ ->willReturn(value: $this->makePlacement());
+ $this->dashboardMapper->method('find')
+ ->willReturn(value: $this->makeDashboard());
+ $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
+ $this->analyticsService->method('isUserOptedOut')->willReturn(false);
+
+ $this->dedup->expects($this->once())
+ ->method('isNewUniqueViewer')
+ ->with(
+ $this->equalTo('alice'),
+ $this->isType(type: 'string'),
+ $this->equalTo('42')
+ )
+ ->willReturn(true);
+
+ $this->service->recordClick(placementId: 42, userId: 'alice');
+ }
+
+ /**
+ * Orphan placement (owning dashboard already deleted) still
+ * records the click rather than silently dropping it.
+ */
+ public function testRecordClickToleratesOrphanPlacement(): void {
+ $this->placementMapper->method('find')
+ ->willReturn(value: $this->makePlacement());
+ $this->dashboardMapper->method('find')
+ ->willThrowException(
+ exception: new DoesNotExistException(msg: 'gone')
+ );
+ $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
+ $this->analyticsService->method('isUserOptedOut')->willReturn(false);
+ $this->dedup->method('isNewUniqueViewer')->willReturn(true);
+
+ $this->tileClickMapper->expects($this->once())
+ ->method('upsertClick')
+ ->with(
+ $this->equalTo('1'),
+ $this->equalTo(''),
+ $this->isType(type: 'string'),
+ 1,
+ 1
+ );
+
+ $result = $this->service->recordClick(placementId: 1, userId: 'alice');
+
+ $this->assertTrue($result);
+ }
+
+ public function testIsTrackingActiveForFalseWhenGloballyDisabled(): void {
+ $this->analyticsService->method('isGloballyEnabled')->willReturn(false);
+
+ $this->assertFalse($this->service->isTrackingActiveFor(userId: 'alice'));
+ }
+
+ public function testIsTrackingActiveForFalseWhenUserOptedOut(): void {
+ $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
+ $this->analyticsService->method('isUserOptedOut')->willReturn(true);
+
+ $this->assertFalse($this->service->isTrackingActiveFor(userId: 'eve'));
+ }
+
+ public function testIsTrackingActiveForTrueByDefault(): void {
+ $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
+ $this->analyticsService->method('isUserOptedOut')->willReturn(false);
+
+ $this->assertTrue($this->service->isTrackingActiveFor(userId: 'frank'));
+ }
+
+ public function testGetTopTilesDelegatesToMapperWithDateRange(): void {
+ $this->tileClickMapper->expects($this->once())
+ ->method('findTopTilesInRange')
+ ->with(
+ $this->isType(type: 'string'),
+ $this->isType(type: 'string'),
+ 10
+ )
+ ->willReturn(
+ value: [
+ [
+ 'placementUuid' => '1',
+ 'dashboardUuid' => 'dsh-1',
+ 'clickCount' => 120,
+ 'uniqueActorCount' => 80,
+ ],
+ ]
+ );
+
+ $rows = $this->service->getTopTiles(period: '7d', limit: 10);
+
+ $this->assertCount(1, $rows);
+ $this->assertSame(120, $rows[0]['clickCount']);
+ }
+
+ public function testGetDashboardBreakdownDelegatesToMapper(): void {
+ $this->tileClickMapper->expects($this->once())
+ ->method('findByDashboardInRange')
+ ->with(
+ $this->equalTo('dsh-9'),
+ $this->isType(type: 'string'),
+ $this->isType(type: 'string')
+ )
+ ->willReturn(
+ value: [
+ [
+ 'placementUuid' => '3',
+ 'clickCount' => 40,
+ 'uniqueActorCount' => 12,
+ ],
+ ]
+ );
+
+ $rows = $this->service->getDashboardBreakdown(
+ dashboardUuid: 'dsh-9',
+ period: '30d'
+ );
+
+ $this->assertCount(1, $rows);
+ $this->assertSame(40, $rows[0]['clickCount']);
+ }
+
+ public function testGenerateCsvExportProducesHeaderAndRows(): void {
+ $row = new TileClick();
+ $row->setPlacementUuid('1');
+ $row->setDashboardUuid('dsh-1');
+ $row->setClickBucket('2026-05-01');
+ $row->setClickCount(2);
+ $row->setUniqueActorCount(1);
+ $this->tileClickMapper->method('findAllInRange')->willReturn(
+ value: [$row]
+ );
+
+ $csv = $this->service->generateCsvExport(period: '7d');
+
+ $this->assertStringContainsString(
+ needle: 'placementUuid',
+ haystack: $csv
+ );
+ $this->assertStringContainsString(
+ needle: 'dsh-1',
+ haystack: $csv
+ );
+ $this->assertStringContainsString(
+ needle: '2026-05-01',
+ haystack: $csv
+ );
+ }
+
+ public function testCsvExportFilenameMatchesExpectedPattern(): void {
+ $name = $this->service->csvExportFilename();
+
+ $this->assertMatchesRegularExpression(
+ pattern: '/^tile-analytics-\d{4}-\d{2}-\d{2}\.csv$/',
+ string: $name
+ );
+ }
+
+ /**
+ * No per-event rows are ever persisted — the ONLY write method on
+ * the mapper is `upsertClick()`, which the service calls exactly
+ * once per (successful) `recordClick()` invocation, never an
+ * `insert()`/raw-row write path.
+ */
+ public function testRecordClickNeverCallsAnythingOtherThanUpsert(): void {
+ $this->placementMapper->method('find')
+ ->willReturn(value: $this->makePlacement());
+ $this->dashboardMapper->method('find')
+ ->willReturn(value: $this->makeDashboard());
+ $this->analyticsService->method('isGloballyEnabled')->willReturn(true);
+ $this->analyticsService->method('isUserOptedOut')->willReturn(false);
+ $this->dedup->method('isNewUniqueViewer')->willReturn(true);
+
+ $this->tileClickMapper->expects($this->once())->method('upsertClick');
+ $this->tileClickMapper->expects($this->never())->method('findAllInRange');
+ $this->tileClickMapper->expects($this->never())->method('findTopTilesInRange');
+
+ $this->service->recordClick(placementId: 1, userId: 'alice');
+ }
}
diff --git a/tests/Unit/Service/UniqueViewerDedupTest.php b/tests/Unit/Service/UniqueViewerDedupTest.php
index 1e7143ce..f3c17886 100644
--- a/tests/Unit/Service/UniqueViewerDedupTest.php
+++ b/tests/Unit/Service/UniqueViewerDedupTest.php
@@ -28,253 +28,241 @@
use OCP\ICacheFactory;
use PHPUnit\Framework\TestCase;
-class UniqueViewerDedupTest extends TestCase
-{
- private IAppConfig $appConfig;
- private ICacheFactory $cacheFactory;
- private ICache $cache;
- private UniqueViewerDedup $dedup;
-
- protected function setUp(): void
- {
- $this->appConfig = $this->createMock(originalClassName: IAppConfig::class);
- $this->cacheFactory = $this->createMock(originalClassName: ICacheFactory::class);
- $this->cache = $this->createMock(originalClassName: ICache::class);
-
- $this->cacheFactory->method('createDistributed')->willReturn(
- $this->cache
- );
-
- $this->dedup = new UniqueViewerDedup(
- cacheFactory: $this->cacheFactory,
- appConfig: $this->appConfig,
- );
- }
-
- public function testUtcDateForFormatsCorrectly(): void
- {
- $when = new DateTimeImmutable(
- datetime: '2026-05-01 23:30:00',
- timezone: new DateTimeZone(timezone: 'UTC')
- );
-
- $this->assertSame(
- '2026-05-01',
- UniqueViewerDedup::utcDateFor(when: $when)
- );
- }
-
- public function testSecondsUntilNextUtcMidnightIsPositive(): void
- {
- $when = new DateTimeImmutable(
- datetime: '2026-05-01 23:30:00',
- timezone: new DateTimeZone(timezone: 'UTC')
- );
-
- $delta = UniqueViewerDedup::secondsUntilNextUtcMidnight(when: $when);
-
- // 30 minutes = 1800 seconds.
- $this->assertSame(1800, $delta);
- }
-
- public function testSecondsUntilNextUtcMidnightFloorsAtOne(): void
- {
- // Exactly midnight — the modify('tomorrow') still goes a day
- // forward so this is 86400 not 0; check at one second before
- // midnight.
- $when = new DateTimeImmutable(
- datetime: '2026-05-01 23:59:59',
- timezone: new DateTimeZone(timezone: 'UTC')
- );
-
- $delta = UniqueViewerDedup::secondsUntilNextUtcMidnight(when: $when);
-
- $this->assertSame(1, $delta);
- }
-
- public function testGetSaltForDateReturnsExistingWhenDateMatches(): void
- {
- $this->appConfig
- ->method('getValueString')
- ->willReturnMap(
- valueMap: [
- [
- 'launchpad',
- UniqueViewerDedup::CONFIG_KEY_SALT,
- '',
- false,
- 'cafef00d',
- ],
- [
- 'launchpad',
- UniqueViewerDedup::CONFIG_KEY_SALT_DATE,
- '',
- false,
- '2026-05-01',
- ],
- ]
- );
- $this->appConfig->expects($this->never())->method('setValueString');
-
- $salt = $this->dedup->getSaltForDate(viewBucketDate: '2026-05-01');
-
- $this->assertSame('cafef00d', $salt);
- }
-
- public function testGetSaltForDateRotatesWhenDateIsStale(): void
- {
- $this->appConfig
- ->method('getValueString')
- ->willReturnMap(
- valueMap: [
- [
- 'launchpad',
- UniqueViewerDedup::CONFIG_KEY_SALT,
- '',
- false,
- 'oldsalt',
- ],
- [
- 'launchpad',
- UniqueViewerDedup::CONFIG_KEY_SALT_DATE,
- '',
- false,
- '2026-04-30',
- ],
- ]
- );
-
- $captured = [];
- $this->appConfig
- ->expects($this->exactly(2))
- ->method('setValueString')
- ->willReturnCallback(
- static function (
- string $app,
- string $key,
- string $value
- ) use (&$captured): bool {
- $captured[$key] = $value;
-
- return true;
- }
- );
-
- $salt = $this->dedup->getSaltForDate(viewBucketDate: '2026-05-01');
-
- $this->assertNotSame('oldsalt', $salt);
- $this->assertSame(64, strlen(string: $salt));
- $this->assertSame(
- $salt,
- $captured[UniqueViewerDedup::CONFIG_KEY_SALT]
- );
- $this->assertSame(
- '2026-05-01',
- $captured[UniqueViewerDedup::CONFIG_KEY_SALT_DATE]
- );
- }
-
- public function testIsNewUniqueViewerReturnsTrueOnFirstView(): void
- {
- $this->appConfig->method('getValueString')->willReturnCallback(
- static function (string $a, string $k, string $d): string {
- if ($k === UniqueViewerDedup::CONFIG_KEY_SALT) {
- return 'fixed-salt-value';
- }
- if ($k === UniqueViewerDedup::CONFIG_KEY_SALT_DATE) {
- return '2026-05-01';
- }
- return $d;
- }
- );
- $this->cache->method('hasKey')->willReturn(false);
- $this->cache->expects($this->once())->method('set');
-
- $result = $this->dedup->isNewUniqueViewer(
- userId: 'alice',
- viewBucketDate: '2026-05-01',
- dashboardUuid: 'uuid-1'
- );
-
- $this->assertTrue($result);
- }
-
- public function testIsNewUniqueViewerReturnsFalseOnRepeat(): void
- {
- $this->appConfig->method('getValueString')->willReturnCallback(
- static function (string $a, string $k, string $d): string {
- if ($k === UniqueViewerDedup::CONFIG_KEY_SALT) {
- return 'fixed-salt-value';
- }
- if ($k === UniqueViewerDedup::CONFIG_KEY_SALT_DATE) {
- return '2026-05-01';
- }
- return $d;
- }
- );
- $this->cache->method('hasKey')->willReturn(true);
- $this->cache->expects($this->never())->method('set');
-
-
- $result = $this->dedup->isNewUniqueViewer(
- userId: 'alice',
- viewBucketDate: '2026-05-01',
- dashboardUuid: 'uuid-1'
- );
-
- $this->assertFalse($result);
- }
-
- public function testHashUserForDateIsDeterministicWithSameSalt(): void
- {
- $this->appConfig->method('getValueString')->willReturnCallback(
- static function (string $a, string $k, string $d): string {
- if ($k === UniqueViewerDedup::CONFIG_KEY_SALT) {
- return 'fixed-salt';
- }
- if ($k === UniqueViewerDedup::CONFIG_KEY_SALT_DATE) {
- return '2026-05-01';
- }
- return $d;
- }
- );
-
- $first = $this->dedup->hashUserForDate(
- userId: 'alice',
- viewBucketDate: '2026-05-01'
- );
- $second = $this->dedup->hashUserForDate(
- userId: 'alice',
- viewBucketDate: '2026-05-01'
- );
-
- $this->assertSame($first, $second);
- $this->assertSame(64, strlen(string: $first));
- }
-
- public function testRotateSaltOverwritesPreviousValueWithoutHistory(): void
- {
- $writes = [];
- $this->appConfig
- ->expects($this->exactly(2))
- ->method('setValueString')
- ->willReturnCallback(
- static function (string $a, string $k, string $v) use (&$writes): bool {
- $writes[$k] = $v;
- return true;
- }
- );
-
- $newSalt = $this->dedup->rotateSalt(viewBucketDate: '2026-05-02');
-
- $this->assertSame(64, strlen(string: $newSalt));
- $this->assertSame(
- $newSalt,
- $writes[UniqueViewerDedup::CONFIG_KEY_SALT]
- );
- $this->assertSame(
- '2026-05-02',
- $writes[UniqueViewerDedup::CONFIG_KEY_SALT_DATE]
- );
- }
+class UniqueViewerDedupTest extends TestCase {
+ private IAppConfig $appConfig;
+ private ICacheFactory $cacheFactory;
+ private ICache $cache;
+ private UniqueViewerDedup $dedup;
+
+ protected function setUp(): void {
+ $this->appConfig = $this->createMock(originalClassName: IAppConfig::class);
+ $this->cacheFactory = $this->createMock(originalClassName: ICacheFactory::class);
+ $this->cache = $this->createMock(originalClassName: ICache::class);
+
+ $this->cacheFactory->method('createDistributed')->willReturn(
+ $this->cache
+ );
+
+ $this->dedup = new UniqueViewerDedup(
+ cacheFactory: $this->cacheFactory,
+ appConfig: $this->appConfig,
+ );
+ }
+
+ public function testUtcDateForFormatsCorrectly(): void {
+ $when = new DateTimeImmutable(
+ datetime: '2026-05-01 23:30:00',
+ timezone: new DateTimeZone(timezone: 'UTC')
+ );
+
+ $this->assertSame(
+ '2026-05-01',
+ UniqueViewerDedup::utcDateFor(when: $when)
+ );
+ }
+
+ public function testSecondsUntilNextUtcMidnightIsPositive(): void {
+ $when = new DateTimeImmutable(
+ datetime: '2026-05-01 23:30:00',
+ timezone: new DateTimeZone(timezone: 'UTC')
+ );
+
+ $delta = UniqueViewerDedup::secondsUntilNextUtcMidnight(when: $when);
+
+ // 30 minutes = 1800 seconds.
+ $this->assertSame(1800, $delta);
+ }
+
+ public function testSecondsUntilNextUtcMidnightFloorsAtOne(): void {
+ // Exactly midnight — the modify('tomorrow') still goes a day
+ // forward so this is 86400 not 0; check at one second before
+ // midnight.
+ $when = new DateTimeImmutable(
+ datetime: '2026-05-01 23:59:59',
+ timezone: new DateTimeZone(timezone: 'UTC')
+ );
+
+ $delta = UniqueViewerDedup::secondsUntilNextUtcMidnight(when: $when);
+
+ $this->assertSame(1, $delta);
+ }
+
+ public function testGetSaltForDateReturnsExistingWhenDateMatches(): void {
+ $this->appConfig
+ ->method('getValueString')
+ ->willReturnMap(
+ valueMap: [
+ [
+ 'launchpad',
+ UniqueViewerDedup::CONFIG_KEY_SALT,
+ '',
+ false,
+ 'cafef00d',
+ ],
+ [
+ 'launchpad',
+ UniqueViewerDedup::CONFIG_KEY_SALT_DATE,
+ '',
+ false,
+ '2026-05-01',
+ ],
+ ]
+ );
+ $this->appConfig->expects($this->never())->method('setValueString');
+
+ $salt = $this->dedup->getSaltForDate(viewBucketDate: '2026-05-01');
+
+ $this->assertSame('cafef00d', $salt);
+ }
+
+ public function testGetSaltForDateRotatesWhenDateIsStale(): void {
+ $this->appConfig
+ ->method('getValueString')
+ ->willReturnMap(
+ valueMap: [
+ [
+ 'launchpad',
+ UniqueViewerDedup::CONFIG_KEY_SALT,
+ '',
+ false,
+ 'oldsalt',
+ ],
+ [
+ 'launchpad',
+ UniqueViewerDedup::CONFIG_KEY_SALT_DATE,
+ '',
+ false,
+ '2026-04-30',
+ ],
+ ]
+ );
+
+ $captured = [];
+ $this->appConfig
+ ->expects($this->exactly(2))
+ ->method('setValueString')
+ ->willReturnCallback(
+ static function (
+ string $app,
+ string $key,
+ string $value,
+ ) use (&$captured): bool {
+ $captured[$key] = $value;
+
+ return true;
+ }
+ );
+
+ $salt = $this->dedup->getSaltForDate(viewBucketDate: '2026-05-01');
+
+ $this->assertNotSame('oldsalt', $salt);
+ $this->assertSame(64, strlen(string: $salt));
+ $this->assertSame(
+ $salt,
+ $captured[UniqueViewerDedup::CONFIG_KEY_SALT]
+ );
+ $this->assertSame(
+ '2026-05-01',
+ $captured[UniqueViewerDedup::CONFIG_KEY_SALT_DATE]
+ );
+ }
+
+ public function testIsNewUniqueViewerReturnsTrueOnFirstView(): void {
+ $this->appConfig->method('getValueString')->willReturnCallback(
+ static function (string $a, string $k, string $d): string {
+ if ($k === UniqueViewerDedup::CONFIG_KEY_SALT) {
+ return 'fixed-salt-value';
+ }
+ if ($k === UniqueViewerDedup::CONFIG_KEY_SALT_DATE) {
+ return '2026-05-01';
+ }
+ return $d;
+ }
+ );
+ $this->cache->method('hasKey')->willReturn(false);
+ $this->cache->expects($this->once())->method('set');
+
+ $result = $this->dedup->isNewUniqueViewer(
+ userId: 'alice',
+ viewBucketDate: '2026-05-01',
+ dashboardUuid: 'uuid-1'
+ );
+
+ $this->assertTrue($result);
+ }
+
+ public function testIsNewUniqueViewerReturnsFalseOnRepeat(): void {
+ $this->appConfig->method('getValueString')->willReturnCallback(
+ static function (string $a, string $k, string $d): string {
+ if ($k === UniqueViewerDedup::CONFIG_KEY_SALT) {
+ return 'fixed-salt-value';
+ }
+ if ($k === UniqueViewerDedup::CONFIG_KEY_SALT_DATE) {
+ return '2026-05-01';
+ }
+ return $d;
+ }
+ );
+ $this->cache->method('hasKey')->willReturn(true);
+ $this->cache->expects($this->never())->method('set');
+
+ $result = $this->dedup->isNewUniqueViewer(
+ userId: 'alice',
+ viewBucketDate: '2026-05-01',
+ dashboardUuid: 'uuid-1'
+ );
+
+ $this->assertFalse($result);
+ }
+
+ public function testHashUserForDateIsDeterministicWithSameSalt(): void {
+ $this->appConfig->method('getValueString')->willReturnCallback(
+ static function (string $a, string $k, string $d): string {
+ if ($k === UniqueViewerDedup::CONFIG_KEY_SALT) {
+ return 'fixed-salt';
+ }
+ if ($k === UniqueViewerDedup::CONFIG_KEY_SALT_DATE) {
+ return '2026-05-01';
+ }
+ return $d;
+ }
+ );
+
+ $first = $this->dedup->hashUserForDate(
+ userId: 'alice',
+ viewBucketDate: '2026-05-01'
+ );
+ $second = $this->dedup->hashUserForDate(
+ userId: 'alice',
+ viewBucketDate: '2026-05-01'
+ );
+
+ $this->assertSame($first, $second);
+ $this->assertSame(64, strlen(string: $first));
+ }
+
+ public function testRotateSaltOverwritesPreviousValueWithoutHistory(): void {
+ $writes = [];
+ $this->appConfig
+ ->expects($this->exactly(2))
+ ->method('setValueString')
+ ->willReturnCallback(
+ static function (string $a, string $k, string $v) use (&$writes): bool {
+ $writes[$k] = $v;
+ return true;
+ }
+ );
+
+ $newSalt = $this->dedup->rotateSalt(viewBucketDate: '2026-05-02');
+
+ $this->assertSame(64, strlen(string: $newSalt));
+ $this->assertSame(
+ $newSalt,
+ $writes[UniqueViewerDedup::CONFIG_KEY_SALT]
+ );
+ $this->assertSame(
+ '2026-05-02',
+ $writes[UniqueViewerDedup::CONFIG_KEY_SALT_DATE]
+ );
+ }
}
diff --git a/tests/Unit/Service/VisibilityCheckerTest.php b/tests/Unit/Service/VisibilityCheckerTest.php
index bb5997e8..edd78490 100644
--- a/tests/Unit/Service/VisibilityCheckerTest.php
+++ b/tests/Unit/Service/VisibilityCheckerTest.php
@@ -19,232 +19,214 @@
use OCA\LaunchPad\Service\VisibilityChecker;
use PHPUnit\Framework\TestCase;
-class VisibilityCheckerTest extends TestCase
-{
- private VisibilityChecker $checker;
- private RuleEvaluatorService $ruleEvaluator;
-
- protected function setUp(): void
- {
- $this->ruleEvaluator = $this->createMock(RuleEvaluatorService::class);
- $this->checker = new VisibilityChecker(
- ruleEvaluator: $this->ruleEvaluator,
- );
- }
-
- private function createRule(bool $isInclude): ConditionalRule
- {
- $rule = new ConditionalRule();
- $rule->setIsInclude($isInclude);
- $rule->setRuleType('group');
- return $rule;
- }
-
- private function createRuleWithId(bool $isInclude, int $id): ConditionalRule
- {
- $rule = $this->createRule($isInclude);
- $rule->setId($id);
- return $rule;
- }
-
- public function testNoRulesReturnsVisible(): void
- {
- $this->assertTrue(
- $this->checker->checkRules(rules: [], userId: 'alice')
- );
- }
-
- public function testSingleIncludeRuleMatching(): void
- {
- $rule = $this->createRule(true);
- $this->ruleEvaluator->method('evaluateRule')->willReturn(true);
-
- $this->assertTrue(
- $this->checker->checkRules(rules: [$rule], userId: 'alice')
- );
- }
-
- public function testSingleIncludeRuleNotMatching(): void
- {
- $rule = $this->createRule(true);
- $this->ruleEvaluator->method('evaluateRule')->willReturn(false);
-
- $this->assertFalse(
- $this->checker->checkRules(rules: [$rule], userId: 'alice')
- );
- }
-
- public function testIncludeRulesOrLogicOneMatches(): void
- {
- $rule1 = $this->createRule(true);
- $rule2 = $this->createRule(true);
-
- $this->ruleEvaluator->method('evaluateRule')
- ->willReturnOnConsecutiveCalls(false, true);
-
- $this->assertTrue(
- $this->checker->checkRules(
- rules: [$rule1, $rule2],
- userId: 'alice'
- )
- );
- }
-
- public function testIncludeRulesOrLogicNoneMatch(): void
- {
- $rule1 = $this->createRule(true);
- $rule2 = $this->createRule(true);
-
- $this->ruleEvaluator->method('evaluateRule')->willReturn(false);
-
- $this->assertFalse(
- $this->checker->checkRules(
- rules: [$rule1, $rule2],
- userId: 'alice'
- )
- );
- }
-
- public function testSingleExcludeRuleMatching(): void
- {
- $rule = $this->createRule(false);
- $this->ruleEvaluator->method('evaluateRule')->willReturn(true);
-
- $this->assertFalse(
- $this->checker->checkRules(rules: [$rule], userId: 'alice')
- );
- }
-
- public function testSingleExcludeRuleNotMatching(): void
- {
- $rule = $this->createRule(false);
- $this->ruleEvaluator->method('evaluateRule')->willReturn(false);
-
- $this->assertTrue(
- $this->checker->checkRules(rules: [$rule], userId: 'alice')
- );
- }
-
- public function testExcludeRulesAndLogicAnyMatchHides(): void
- {
- $rule1 = $this->createRule(false);
- $rule2 = $this->createRule(false);
-
- $this->ruleEvaluator->method('evaluateRule')
- ->willReturnOnConsecutiveCalls(true, false);
-
- $this->assertFalse(
- $this->checker->checkRules(
- rules: [$rule1, $rule2],
- userId: 'alice'
- )
- );
- }
-
- public function testMixedRulesIncludePassesExcludeFails(): void
- {
- $include = $this->createRule(true);
- $exclude = $this->createRule(false);
-
- $this->ruleEvaluator->method('evaluateRule')
- ->willReturnCallback(function ($rule) {
- // Include rule matches, exclude rule also matches
- return true;
- });
-
- // Include passes (OR: one matches), but exclude fails (match = hide)
- $this->assertFalse(
- $this->checker->checkRules(
- rules: [$include, $exclude],
- userId: 'alice'
- )
- );
- }
-
- public function testMixedRulesIncludePassesExcludePasses(): void
- {
- $include = $this->createRule(true);
- $exclude = $this->createRule(false);
-
- $this->ruleEvaluator->method('evaluateRule')
- ->willReturnCallback(function ($rule) {
- // Include matches, exclude does NOT match
- return $rule->getIsInclude();
- });
-
- $this->assertTrue(
- $this->checker->checkRules(
- rules: [$include, $exclude],
- userId: 'alice'
- )
- );
- }
-
- // -----------------------------------------------------------------------
- // evaluateRuleSet() — conditional-visibility-editor REQ-CVUI-005.
- // checkRules() above proves the boolean is unchanged; these prove the
- // SAME method also reports which rules matched, and that checkRules()
- // is a thin wrapper over it (no forked combination logic).
- // -----------------------------------------------------------------------
-
- public function testEvaluateRuleSetReportsMatchedIncludeRuleId(): void
- {
- $rule = $this->createRuleWithId(true, 1);
- $this->ruleEvaluator->method('evaluateRule')->willReturn(true);
-
- $result = $this->checker->evaluateRuleSet(rules: [$rule], userId: 'alice');
-
- $this->assertTrue($result['visible']);
- $this->assertSame([1], $result['matchedIncludeRuleIds']);
- $this->assertSame([], $result['matchedExcludeRuleIds']);
- }
-
- public function testEvaluateRuleSetReportsMatchedExcludeRuleIdAsOverrideReason(): void
- {
- $include = $this->createRuleWithId(true, 1);
- $exclude = $this->createRuleWithId(false, 2);
- $this->ruleEvaluator->method('evaluateRule')->willReturn(true);
-
- $result = $this->checker->evaluateRuleSet(
- rules: [$include, $exclude],
- userId: 'alice'
- );
-
- $this->assertFalse($result['visible']);
- $this->assertSame([1], $result['matchedIncludeRuleIds']);
- $this->assertSame([2], $result['matchedExcludeRuleIds']);
- }
-
- public function testCheckRulesIsAThinWrapperOverEvaluateRuleSet(): void
- {
- $rule = $this->createRuleWithId(true, 1);
- $this->ruleEvaluator->method('evaluateRule')->willReturn(true);
-
- $bool = $this->checker->checkRules(rules: [$rule], userId: 'alice');
- $set = $this->checker->evaluateRuleSet(rules: [$rule], userId: 'alice');
-
- $this->assertSame($set['visible'], $bool);
- }
-
- public function testEvaluateRuleSetForwardsGroupsOverrideToRuleEvaluator(): void
- {
- $rule = $this->createRuleWithId(true, 1);
- $this->ruleEvaluator->expects($this->once())
- ->method('evaluateRule')
- ->with(
- rule: $rule,
- userId: 'alice',
- groupsOverride: ['marketing'],
- nowOverride: null
- )
- ->willReturn(true);
-
- $result = $this->checker->evaluateRuleSet(
- rules: [$rule],
- userId: 'alice',
- groupsOverride: ['marketing']
- );
-
- $this->assertTrue($result['visible']);
- }
+class VisibilityCheckerTest extends TestCase {
+ private VisibilityChecker $checker;
+ private RuleEvaluatorService $ruleEvaluator;
+
+ protected function setUp(): void {
+ $this->ruleEvaluator = $this->createMock(RuleEvaluatorService::class);
+ $this->checker = new VisibilityChecker(
+ ruleEvaluator: $this->ruleEvaluator,
+ );
+ }
+
+ private function createRule(bool $isInclude): ConditionalRule {
+ $rule = new ConditionalRule();
+ $rule->setIsInclude($isInclude);
+ $rule->setRuleType('group');
+ return $rule;
+ }
+
+ private function createRuleWithId(bool $isInclude, int $id): ConditionalRule {
+ $rule = $this->createRule($isInclude);
+ $rule->setId($id);
+ return $rule;
+ }
+
+ public function testNoRulesReturnsVisible(): void {
+ $this->assertTrue(
+ $this->checker->checkRules(rules: [], userId: 'alice')
+ );
+ }
+
+ public function testSingleIncludeRuleMatching(): void {
+ $rule = $this->createRule(true);
+ $this->ruleEvaluator->method('evaluateRule')->willReturn(true);
+
+ $this->assertTrue(
+ $this->checker->checkRules(rules: [$rule], userId: 'alice')
+ );
+ }
+
+ public function testSingleIncludeRuleNotMatching(): void {
+ $rule = $this->createRule(true);
+ $this->ruleEvaluator->method('evaluateRule')->willReturn(false);
+
+ $this->assertFalse(
+ $this->checker->checkRules(rules: [$rule], userId: 'alice')
+ );
+ }
+
+ public function testIncludeRulesOrLogicOneMatches(): void {
+ $rule1 = $this->createRule(true);
+ $rule2 = $this->createRule(true);
+
+ $this->ruleEvaluator->method('evaluateRule')
+ ->willReturnOnConsecutiveCalls(false, true);
+
+ $this->assertTrue(
+ $this->checker->checkRules(
+ rules: [$rule1, $rule2],
+ userId: 'alice'
+ )
+ );
+ }
+
+ public function testIncludeRulesOrLogicNoneMatch(): void {
+ $rule1 = $this->createRule(true);
+ $rule2 = $this->createRule(true);
+
+ $this->ruleEvaluator->method('evaluateRule')->willReturn(false);
+
+ $this->assertFalse(
+ $this->checker->checkRules(
+ rules: [$rule1, $rule2],
+ userId: 'alice'
+ )
+ );
+ }
+
+ public function testSingleExcludeRuleMatching(): void {
+ $rule = $this->createRule(false);
+ $this->ruleEvaluator->method('evaluateRule')->willReturn(true);
+
+ $this->assertFalse(
+ $this->checker->checkRules(rules: [$rule], userId: 'alice')
+ );
+ }
+
+ public function testSingleExcludeRuleNotMatching(): void {
+ $rule = $this->createRule(false);
+ $this->ruleEvaluator->method('evaluateRule')->willReturn(false);
+
+ $this->assertTrue(
+ $this->checker->checkRules(rules: [$rule], userId: 'alice')
+ );
+ }
+
+ public function testExcludeRulesAndLogicAnyMatchHides(): void {
+ $rule1 = $this->createRule(false);
+ $rule2 = $this->createRule(false);
+
+ $this->ruleEvaluator->method('evaluateRule')
+ ->willReturnOnConsecutiveCalls(true, false);
+
+ $this->assertFalse(
+ $this->checker->checkRules(
+ rules: [$rule1, $rule2],
+ userId: 'alice'
+ )
+ );
+ }
+
+ public function testMixedRulesIncludePassesExcludeFails(): void {
+ $include = $this->createRule(true);
+ $exclude = $this->createRule(false);
+
+ $this->ruleEvaluator->method('evaluateRule')
+ ->willReturnCallback(function ($rule) {
+ // Include rule matches, exclude rule also matches
+ return true;
+ });
+
+ // Include passes (OR: one matches), but exclude fails (match = hide)
+ $this->assertFalse(
+ $this->checker->checkRules(
+ rules: [$include, $exclude],
+ userId: 'alice'
+ )
+ );
+ }
+
+ public function testMixedRulesIncludePassesExcludePasses(): void {
+ $include = $this->createRule(true);
+ $exclude = $this->createRule(false);
+
+ $this->ruleEvaluator->method('evaluateRule')
+ ->willReturnCallback(function ($rule) {
+ // Include matches, exclude does NOT match
+ return $rule->getIsInclude();
+ });
+
+ $this->assertTrue(
+ $this->checker->checkRules(
+ rules: [$include, $exclude],
+ userId: 'alice'
+ )
+ );
+ }
+
+ // -----------------------------------------------------------------------
+ // evaluateRuleSet() — conditional-visibility-editor REQ-CVUI-005.
+ // checkRules() above proves the boolean is unchanged; these prove the
+ // SAME method also reports which rules matched, and that checkRules()
+ // is a thin wrapper over it (no forked combination logic).
+ // -----------------------------------------------------------------------
+
+ public function testEvaluateRuleSetReportsMatchedIncludeRuleId(): void {
+ $rule = $this->createRuleWithId(true, 1);
+ $this->ruleEvaluator->method('evaluateRule')->willReturn(true);
+
+ $result = $this->checker->evaluateRuleSet(rules: [$rule], userId: 'alice');
+
+ $this->assertTrue($result['visible']);
+ $this->assertSame([1], $result['matchedIncludeRuleIds']);
+ $this->assertSame([], $result['matchedExcludeRuleIds']);
+ }
+
+ public function testEvaluateRuleSetReportsMatchedExcludeRuleIdAsOverrideReason(): void {
+ $include = $this->createRuleWithId(true, 1);
+ $exclude = $this->createRuleWithId(false, 2);
+ $this->ruleEvaluator->method('evaluateRule')->willReturn(true);
+
+ $result = $this->checker->evaluateRuleSet(
+ rules: [$include, $exclude],
+ userId: 'alice'
+ );
+
+ $this->assertFalse($result['visible']);
+ $this->assertSame([1], $result['matchedIncludeRuleIds']);
+ $this->assertSame([2], $result['matchedExcludeRuleIds']);
+ }
+
+ public function testCheckRulesIsAThinWrapperOverEvaluateRuleSet(): void {
+ $rule = $this->createRuleWithId(true, 1);
+ $this->ruleEvaluator->method('evaluateRule')->willReturn(true);
+
+ $bool = $this->checker->checkRules(rules: [$rule], userId: 'alice');
+ $set = $this->checker->evaluateRuleSet(rules: [$rule], userId: 'alice');
+
+ $this->assertSame($set['visible'], $bool);
+ }
+
+ public function testEvaluateRuleSetForwardsGroupsOverrideToRuleEvaluator(): void {
+ $rule = $this->createRuleWithId(true, 1);
+ $this->ruleEvaluator->expects($this->once())
+ ->method('evaluateRule')
+ ->with(
+ rule: $rule,
+ userId: 'alice',
+ groupsOverride: ['marketing'],
+ nowOverride: null
+ )
+ ->willReturn(true);
+
+ $result = $this->checker->evaluateRuleSet(
+ rules: [$rule],
+ userId: 'alice',
+ groupsOverride: ['marketing']
+ );
+
+ $this->assertTrue($result['visible']);
+ }
}
diff --git a/tests/Unit/Service/WeatherServiceTest.php b/tests/Unit/Service/WeatherServiceTest.php
index 560371ae..fe6a9324 100644
--- a/tests/Unit/Service/WeatherServiceTest.php
+++ b/tests/Unit/Service/WeatherServiceTest.php
@@ -28,7 +28,6 @@
use OCP\AppFramework\Db\DoesNotExistException;
use OCP\Http\Client\IClient;
use OCP\Http\Client\IClientService;
-use OCP\Http\Client\IResponse;
use OCP\IAppConfig;
use OCP\ICache;
use OCP\ICacheFactory;
@@ -38,302 +37,291 @@
use Psr\Log\LoggerInterface;
use RuntimeException;
-class WeatherServiceTest extends TestCase
-{
- private IAppManager $appManager;
- private ContainerInterface $container;
- private IClientService $clientService;
- private ICacheFactory $cacheFactory;
- private IAppConfig $appConfig;
- private WidgetPlacementMapper $placementMapper;
- private IConfig $config;
- private LoggerInterface $logger;
- private ICache $cache;
-
- protected function setUp(): void
- {
- $this->appManager = $this->createMock(originalClassName: IAppManager::class);
- $this->container = $this->createMock(originalClassName: ContainerInterface::class);
- $this->clientService = $this->createMock(originalClassName: IClientService::class);
- $this->cacheFactory = $this->createMock(originalClassName: ICacheFactory::class);
- $this->appConfig = $this->createMock(originalClassName: IAppConfig::class);
- $this->placementMapper = $this->createMock(originalClassName: WidgetPlacementMapper::class);
- $this->config = $this->createMock(originalClassName: IConfig::class);
- $this->logger = $this->createMock(originalClassName: LoggerInterface::class);
- $this->cache = $this->createMock(originalClassName: ICache::class);
-
- $this->cacheFactory->method('createDistributed')->willReturn($this->cache);
- }//end setUp()
-
- /**
- * Build the service under test with the current mock set.
- *
- * @return WeatherService
- */
- private function service(): WeatherService
- {
- return new WeatherService(
- $this->appManager,
- $this->container,
- $this->clientService,
- $this->cacheFactory,
- $this->appConfig,
- $this->placementMapper,
- $this->config,
- $this->logger,
- );
- }//end service()
-
- /**
- * Stub a placement whose widgetContent carries the given config.
- *
- * @param array $content The placement config.
- *
- * @return WidgetPlacement
- */
- private function placementWith(array $content): WidgetPlacement
- {
- $placement = $this->createMock(originalClassName: WidgetPlacement::class);
- $placement->method('getContentArray')->willReturn($content);
-
- return $placement;
- }//end placementWith()
-
- /**
- * A cached reading inside its TTL MUST be served without any upstream
- * call, and MUST be marked fresh (REQ-WEATHER-002).
- *
- * @return void
- */
- public function testCacheHitWithinTtlServesWithoutUpstreamCall(): void
- {
- $this->placementMapper->method('find')->willReturn(
- $this->placementWith(['location' => 'Utrecht'])
- );
- $this->appConfig->method('getValueInt')->willReturn(900);
- $this->appConfig->method('getValueString')->willReturn('');
- $this->config->method('getUserValue')->willReturn('');
-
- $this->cache->method('get')->willReturn(
- json_encode([
- 'location' => 'Utrecht',
- 'tempValue' => 12.5,
- 'units' => 'metric',
- 'condition' => 'cloudy',
- 'conditionText' => 'Cloudy',
- 'language' => 'en',
- 'fetchedAtTs' => time(),
- ])
- );
-
- // Any upstream fetch would need a client — assert none is requested.
- $this->clientService->expects($this->never())->method('newClient');
-
- $result = $this->service()->resolveForPlacement(placementId: 1, userId: 'alice');
-
- $this->assertSame('Utrecht', $result['location']);
- $this->assertSame(12.5, $result['tempValue']);
- $this->assertFalse($result['stale']);
- }//end testCacheHitWithinTtlServesWithoutUpstreamCall()
-
- /**
- * When the upstream fails but a previous (TTL-expired) reading exists,
- * the service MUST degrade to that reading with `stale = true` rather
- * than erroring (REQ-WEATHER-002).
- *
- * @return void
- */
- public function testStaleFallbackWhenUpstreamFails(): void
- {
- $this->placementMapper->method('find')->willReturn(
- $this->placementWith(['location' => 'Utrecht'])
- );
- $this->appConfig->method('getValueInt')->willReturn(900);
- // Provider URL configured so the provider path is attempted.
- $this->appConfig->method('getValueString')->willReturn('https://example.invalid/w?q={location}');
- $this->config->method('getUserValue')->willReturn('');
-
- // Cached reading is older than the TTL → refresh attempted.
- $this->cache->method('get')->willReturn(
- json_encode([
- 'location' => 'Utrecht',
- 'tempValue' => 9.0,
- 'units' => 'metric',
- 'condition' => 'rain',
- 'conditionText' => 'Rain',
- 'language' => 'en',
- 'fetchedAtTs' => (time() - 100000),
- ])
- );
-
- $client = $this->createMock(originalClassName: IClient::class);
- $client->method('get')->willThrowException(new RuntimeException('upstream down'));
- $this->clientService->method('newClient')->willReturn($client);
-
- $result = $this->service()->resolveForPlacement(placementId: 1, userId: 'alice');
-
- $this->assertSame(9.0, $result['tempValue']);
- $this->assertTrue($result['stale'], 'a served-past-TTL reading must be flagged stale');
- }//end testStaleFallbackWhenUpstreamFails()
-
- /**
- * With no cache and a failing upstream the service MUST return the
- * error shape rather than throwing (REQ-WEATHER-002).
- *
- * @return void
- */
- public function testNoCacheAndUpstreamFailureReturnsErrorShape(): void
- {
- $this->placementMapper->method('find')->willReturn(
- $this->placementWith(['location' => 'Utrecht'])
- );
- $this->appConfig->method('getValueInt')->willReturn(900);
- $this->appConfig->method('getValueString')->willReturn('https://example.invalid/w?q={location}');
- $this->config->method('getUserValue')->willReturn('');
- $this->cache->method('get')->willReturn(null);
-
- $client = $this->createMock(originalClassName: IClient::class);
- $client->method('get')->willThrowException(new RuntimeException('upstream down'));
- $this->clientService->method('newClient')->willReturn($client);
-
- $result = $this->service()->resolveForPlacement(placementId: 1, userId: 'alice');
-
- $this->assertSame(['error' => 'weather_unavailable'], $result);
- }//end testNoCacheAndUpstreamFailureReturnsErrorShape()
-
- /**
- * A missing placement MUST return the error shape, never throw.
- *
- * @return void
- */
- public function testMissingPlacementReturnsErrorShape(): void
- {
- $this->placementMapper->method('find')->willThrowException(new DoesNotExistException('nope'));
-
- $result = $this->service()->resolveForPlacement(placementId: 404, userId: 'alice');
-
- $this->assertSame(['error' => 'placement_not_found'], $result);
- }//end testMissingPlacementReturnsErrorShape()
-
- /**
- * The public response MUST NOT leak the provider API key or raw
- * provider URL, whatever the upstream returned (REQ-WEATHER-001).
- *
- * @return void
- */
- public function testResponseNeverContainsApiKeyOrProviderUrl(): void
- {
- $this->placementMapper->method('find')->willReturn(
- $this->placementWith(['location' => 'Utrecht'])
- );
- $this->appConfig->method('getValueInt')->willReturn(900);
- $this->appConfig->method('getValueString')->willReturn('');
- $this->config->method('getUserValue')->willReturn('');
-
- $this->cache->method('get')->willReturn(
- json_encode([
- 'location' => 'Utrecht',
- 'tempValue' => 12.5,
- 'units' => 'metric',
- 'condition' => 'cloudy',
- 'conditionText' => 'Cloudy',
- 'language' => 'en',
- 'fetchedAtTs' => time(),
- // Deliberately smuggle secrets into the cached payload.
- 'apiKey' => 'SUPER-SECRET-KEY',
- 'providerUrl' => 'https://provider.example/api?key=SUPER-SECRET-KEY',
- ])
- );
-
- $result = $this->service()->resolveForPlacement(placementId: 1, userId: 'alice');
-
- $encoded = json_encode($result);
- $this->assertStringNotContainsString('SUPER-SECRET-KEY', $encoded);
- $this->assertStringNotContainsString('provider.example', $encoded);
- $this->assertArrayNotHasKey('apiKey', $result);
- $this->assertArrayNotHasKey('providerUrl', $result);
- // The public contract keys are exactly these.
- $this->assertSame(
- ['location', 'tempValue', 'units', 'condition', 'conditionText', 'language', 'fetchedAt', 'stale'],
- array_keys($result)
- );
- }//end testResponseNeverContainsApiKeyOrProviderUrl()
-
- /**
- * Units MUST follow the viewer's locale by default (regression guard
- * against hardcoded imperial/metric) — REQ-WEATHER-003.
- *
- * @return void
- */
- public function testUnitsFollowViewerLocaleByDefault(): void
- {
- $this->placementMapper->method('find')->willReturn(
- $this->placementWith(['location' => 'Boston'])
- );
- $this->appConfig->method('getValueInt')->willReturn(900);
- $this->appConfig->method('getValueString')->willReturn('');
-
- // A US locale viewer.
- $this->config->method('getUserValue')->willReturnCallback(
- static function (string $uid, string $app, string $key, $default = '') {
- if ($key === 'locale') {
- return 'en_US';
- }
-
- return $default;
- }
- );
-
- $this->cache->method('get')->willReturn(null);
- $client = $this->createMock(originalClassName: IClient::class);
- $client->method('get')->willThrowException(new RuntimeException('no upstream in test'));
- $this->clientService->method('newClient')->willReturn($client);
-
- // The cache key is derived from units; assert the units the service
- // resolved by observing the value it tried to persist/lookup.
- $observedKeys = [];
- $this->cache->method('get')->willReturnCallback(
- static function (string $key) use (&$observedKeys) {
- $observedKeys[] = $key;
-
- return null;
- }
- );
-
- $this->service()->resolveForPlacement(placementId: 1, userId: 'usviewer');
-
- $this->assertNotEmpty($observedKeys, 'service must consult the cache with a units-derived key');
- }//end testUnitsFollowViewerLocaleByDefault()
-
- /**
- * An explicit author units override MUST win over the locale default
- * (REQ-WEATHER-003).
- *
- * @return void
- */
- public function testAuthorUnitsOverrideWinsOverLocale(): void
- {
- $this->placementMapper->method('find')->willReturn(
- $this->placementWith(['location' => 'Utrecht', 'unitsOverride' => 'imperial'])
- );
- $this->appConfig->method('getValueInt')->willReturn(900);
- $this->appConfig->method('getValueString')->willReturn('');
- $this->config->method('getUserValue')->willReturn('nl_NL');
-
- $this->cache->method('get')->willReturn(
- json_encode([
- 'location' => 'Utrecht',
- 'tempValue' => 54.0,
- 'units' => 'imperial',
- 'condition' => 'cloudy',
- 'conditionText' => 'Cloudy',
- 'language' => 'nl',
- 'fetchedAtTs' => time(),
- ])
- );
-
- $result = $this->service()->resolveForPlacement(placementId: 1, userId: 'nlviewer');
-
- $this->assertSame('imperial', $result['units'], 'author override must beat the nl_NL locale default');
- }//end testAuthorUnitsOverrideWinsOverLocale()
+class WeatherServiceTest extends TestCase {
+ private IAppManager $appManager;
+ private ContainerInterface $container;
+ private IClientService $clientService;
+ private ICacheFactory $cacheFactory;
+ private IAppConfig $appConfig;
+ private WidgetPlacementMapper $placementMapper;
+ private IConfig $config;
+ private LoggerInterface $logger;
+ private ICache $cache;
+
+ protected function setUp(): void {
+ $this->appManager = $this->createMock(originalClassName: IAppManager::class);
+ $this->container = $this->createMock(originalClassName: ContainerInterface::class);
+ $this->clientService = $this->createMock(originalClassName: IClientService::class);
+ $this->cacheFactory = $this->createMock(originalClassName: ICacheFactory::class);
+ $this->appConfig = $this->createMock(originalClassName: IAppConfig::class);
+ $this->placementMapper = $this->createMock(originalClassName: WidgetPlacementMapper::class);
+ $this->config = $this->createMock(originalClassName: IConfig::class);
+ $this->logger = $this->createMock(originalClassName: LoggerInterface::class);
+ $this->cache = $this->createMock(originalClassName: ICache::class);
+
+ $this->cacheFactory->method('createDistributed')->willReturn($this->cache);
+ }//end setUp()
+
+ /**
+ * Build the service under test with the current mock set.
+ *
+ * @return WeatherService
+ */
+ private function service(): WeatherService {
+ return new WeatherService(
+ $this->appManager,
+ $this->container,
+ $this->clientService,
+ $this->cacheFactory,
+ $this->appConfig,
+ $this->placementMapper,
+ $this->config,
+ $this->logger,
+ );
+ }//end service()
+
+ /**
+ * Stub a placement whose widgetContent carries the given config.
+ *
+ * @param array $content The placement config.
+ *
+ * @return WidgetPlacement
+ */
+ private function placementWith(array $content): WidgetPlacement {
+ $placement = $this->createMock(originalClassName: WidgetPlacement::class);
+ $placement->method('getContentArray')->willReturn($content);
+
+ return $placement;
+ }//end placementWith()
+
+ /**
+ * A cached reading inside its TTL MUST be served without any upstream
+ * call, and MUST be marked fresh (REQ-WEATHER-002).
+ *
+ * @return void
+ */
+ public function testCacheHitWithinTtlServesWithoutUpstreamCall(): void {
+ $this->placementMapper->method('find')->willReturn(
+ $this->placementWith(['location' => 'Utrecht'])
+ );
+ $this->appConfig->method('getValueInt')->willReturn(900);
+ $this->appConfig->method('getValueString')->willReturn('');
+ $this->config->method('getUserValue')->willReturn('');
+
+ $this->cache->method('get')->willReturn(
+ json_encode([
+ 'location' => 'Utrecht',
+ 'tempValue' => 12.5,
+ 'units' => 'metric',
+ 'condition' => 'cloudy',
+ 'conditionText' => 'Cloudy',
+ 'language' => 'en',
+ 'fetchedAtTs' => time(),
+ ])
+ );
+
+ // Any upstream fetch would need a client — assert none is requested.
+ $this->clientService->expects($this->never())->method('newClient');
+
+ $result = $this->service()->resolveForPlacement(placementId: 1, userId: 'alice');
+
+ $this->assertSame('Utrecht', $result['location']);
+ $this->assertSame(12.5, $result['tempValue']);
+ $this->assertFalse($result['stale']);
+ }//end testCacheHitWithinTtlServesWithoutUpstreamCall()
+
+ /**
+ * When the upstream fails but a previous (TTL-expired) reading exists,
+ * the service MUST degrade to that reading with `stale = true` rather
+ * than erroring (REQ-WEATHER-002).
+ *
+ * @return void
+ */
+ public function testStaleFallbackWhenUpstreamFails(): void {
+ $this->placementMapper->method('find')->willReturn(
+ $this->placementWith(['location' => 'Utrecht'])
+ );
+ $this->appConfig->method('getValueInt')->willReturn(900);
+ // Provider URL configured so the provider path is attempted.
+ $this->appConfig->method('getValueString')->willReturn('https://example.invalid/w?q={location}');
+ $this->config->method('getUserValue')->willReturn('');
+
+ // Cached reading is older than the TTL → refresh attempted.
+ $this->cache->method('get')->willReturn(
+ json_encode([
+ 'location' => 'Utrecht',
+ 'tempValue' => 9.0,
+ 'units' => 'metric',
+ 'condition' => 'rain',
+ 'conditionText' => 'Rain',
+ 'language' => 'en',
+ 'fetchedAtTs' => (time() - 100000),
+ ])
+ );
+
+ $client = $this->createMock(originalClassName: IClient::class);
+ $client->method('get')->willThrowException(new RuntimeException('upstream down'));
+ $this->clientService->method('newClient')->willReturn($client);
+
+ $result = $this->service()->resolveForPlacement(placementId: 1, userId: 'alice');
+
+ $this->assertSame(9.0, $result['tempValue']);
+ $this->assertTrue($result['stale'], 'a served-past-TTL reading must be flagged stale');
+ }//end testStaleFallbackWhenUpstreamFails()
+
+ /**
+ * With no cache and a failing upstream the service MUST return the
+ * error shape rather than throwing (REQ-WEATHER-002).
+ *
+ * @return void
+ */
+ public function testNoCacheAndUpstreamFailureReturnsErrorShape(): void {
+ $this->placementMapper->method('find')->willReturn(
+ $this->placementWith(['location' => 'Utrecht'])
+ );
+ $this->appConfig->method('getValueInt')->willReturn(900);
+ $this->appConfig->method('getValueString')->willReturn('https://example.invalid/w?q={location}');
+ $this->config->method('getUserValue')->willReturn('');
+ $this->cache->method('get')->willReturn(null);
+
+ $client = $this->createMock(originalClassName: IClient::class);
+ $client->method('get')->willThrowException(new RuntimeException('upstream down'));
+ $this->clientService->method('newClient')->willReturn($client);
+
+ $result = $this->service()->resolveForPlacement(placementId: 1, userId: 'alice');
+
+ $this->assertSame(['error' => 'weather_unavailable'], $result);
+ }//end testNoCacheAndUpstreamFailureReturnsErrorShape()
+
+ /**
+ * A missing placement MUST return the error shape, never throw.
+ *
+ * @return void
+ */
+ public function testMissingPlacementReturnsErrorShape(): void {
+ $this->placementMapper->method('find')->willThrowException(new DoesNotExistException('nope'));
+
+ $result = $this->service()->resolveForPlacement(placementId: 404, userId: 'alice');
+
+ $this->assertSame(['error' => 'placement_not_found'], $result);
+ }//end testMissingPlacementReturnsErrorShape()
+
+ /**
+ * The public response MUST NOT leak the provider API key or raw
+ * provider URL, whatever the upstream returned (REQ-WEATHER-001).
+ *
+ * @return void
+ */
+ public function testResponseNeverContainsApiKeyOrProviderUrl(): void {
+ $this->placementMapper->method('find')->willReturn(
+ $this->placementWith(['location' => 'Utrecht'])
+ );
+ $this->appConfig->method('getValueInt')->willReturn(900);
+ $this->appConfig->method('getValueString')->willReturn('');
+ $this->config->method('getUserValue')->willReturn('');
+
+ $this->cache->method('get')->willReturn(
+ json_encode([
+ 'location' => 'Utrecht',
+ 'tempValue' => 12.5,
+ 'units' => 'metric',
+ 'condition' => 'cloudy',
+ 'conditionText' => 'Cloudy',
+ 'language' => 'en',
+ 'fetchedAtTs' => time(),
+ // Deliberately smuggle secrets into the cached payload.
+ 'apiKey' => 'SUPER-SECRET-KEY',
+ 'providerUrl' => 'https://provider.example/api?key=SUPER-SECRET-KEY',
+ ])
+ );
+
+ $result = $this->service()->resolveForPlacement(placementId: 1, userId: 'alice');
+
+ $encoded = json_encode($result);
+ $this->assertStringNotContainsString('SUPER-SECRET-KEY', $encoded);
+ $this->assertStringNotContainsString('provider.example', $encoded);
+ $this->assertArrayNotHasKey('apiKey', $result);
+ $this->assertArrayNotHasKey('providerUrl', $result);
+ // The public contract keys are exactly these.
+ $this->assertSame(
+ ['location', 'tempValue', 'units', 'condition', 'conditionText', 'language', 'fetchedAt', 'stale'],
+ array_keys($result)
+ );
+ }//end testResponseNeverContainsApiKeyOrProviderUrl()
+
+ /**
+ * Units MUST follow the viewer's locale by default (regression guard
+ * against hardcoded imperial/metric) — REQ-WEATHER-003.
+ *
+ * @return void
+ */
+ public function testUnitsFollowViewerLocaleByDefault(): void {
+ $this->placementMapper->method('find')->willReturn(
+ $this->placementWith(['location' => 'Boston'])
+ );
+ $this->appConfig->method('getValueInt')->willReturn(900);
+ $this->appConfig->method('getValueString')->willReturn('');
+
+ // A US locale viewer.
+ $this->config->method('getUserValue')->willReturnCallback(
+ static function (string $uid, string $app, string $key, $default = '') {
+ if ($key === 'locale') {
+ return 'en_US';
+ }
+
+ return $default;
+ }
+ );
+
+ $this->cache->method('get')->willReturn(null);
+ $client = $this->createMock(originalClassName: IClient::class);
+ $client->method('get')->willThrowException(new RuntimeException('no upstream in test'));
+ $this->clientService->method('newClient')->willReturn($client);
+
+ // The cache key is derived from units; assert the units the service
+ // resolved by observing the value it tried to persist/lookup.
+ $observedKeys = [];
+ $this->cache->method('get')->willReturnCallback(
+ static function (string $key) use (&$observedKeys) {
+ $observedKeys[] = $key;
+
+ return null;
+ }
+ );
+
+ $this->service()->resolveForPlacement(placementId: 1, userId: 'usviewer');
+
+ $this->assertNotEmpty($observedKeys, 'service must consult the cache with a units-derived key');
+ }//end testUnitsFollowViewerLocaleByDefault()
+
+ /**
+ * An explicit author units override MUST win over the locale default
+ * (REQ-WEATHER-003).
+ *
+ * @return void
+ */
+ public function testAuthorUnitsOverrideWinsOverLocale(): void {
+ $this->placementMapper->method('find')->willReturn(
+ $this->placementWith(['location' => 'Utrecht', 'unitsOverride' => 'imperial'])
+ );
+ $this->appConfig->method('getValueInt')->willReturn(900);
+ $this->appConfig->method('getValueString')->willReturn('');
+ $this->config->method('getUserValue')->willReturn('nl_NL');
+
+ $this->cache->method('get')->willReturn(
+ json_encode([
+ 'location' => 'Utrecht',
+ 'tempValue' => 54.0,
+ 'units' => 'imperial',
+ 'condition' => 'cloudy',
+ 'conditionText' => 'Cloudy',
+ 'language' => 'nl',
+ 'fetchedAtTs' => time(),
+ ])
+ );
+
+ $result = $this->service()->resolveForPlacement(placementId: 1, userId: 'nlviewer');
+
+ $this->assertSame('imperial', $result['units'], 'author override must beat the nl_NL locale default');
+ }//end testAuthorUnitsOverrideWinsOverLocale()
}//end class
diff --git a/tests/Unit/Service/WidgetPlacementServiceTest.php b/tests/Unit/Service/WidgetPlacementServiceTest.php
index cccca3ca..9d3f9825 100644
--- a/tests/Unit/Service/WidgetPlacementServiceTest.php
+++ b/tests/Unit/Service/WidgetPlacementServiceTest.php
@@ -28,118 +28,108 @@
use OCA\LaunchPad\Service\WidgetPlacementService;
use PHPUnit\Framework\TestCase;
-class WidgetPlacementServiceTest extends TestCase
-{
- /**
- * Build a container `content` blob with `$depth` nested containers.
- *
- * Depth 0 = a label leaf (no `placements[]`).
- * Depth 1 = container { placements: [label] }.
- * Depth 2 = container { placements: [container { placements: [label] }] }.
- *
- * @param int $depth How deep to nest containers.
- *
- * @return array
- */
- private function buildNested(int $depth): array
- {
- if ($depth <= 0) {
- return ['text' => 'leaf'];
- }
+class WidgetPlacementServiceTest extends TestCase {
+ /**
+ * Build a container `content` blob with `$depth` nested containers.
+ *
+ * Depth 0 = a label leaf (no `placements[]`).
+ * Depth 1 = container { placements: [label] }.
+ * Depth 2 = container { placements: [container { placements: [label] }] }.
+ *
+ * @param int $depth How deep to nest containers.
+ *
+ * @return array
+ */
+ private function buildNested(int $depth): array {
+ if ($depth <= 0) {
+ return ['text' => 'leaf'];
+ }
- return [
- 'placements' => [
- [
- 'type' => 'container',
- 'content' => $this->buildNested(($depth - 1)),
- ],
- ],
- ];
- }
+ return [
+ 'placements' => [
+ [
+ 'type' => 'container',
+ 'content' => $this->buildNested(($depth - 1)),
+ ],
+ ],
+ ];
+ }
- public function testValidateContainerDepthAcceptsLeaf(): void
- {
- $service = new WidgetPlacementService();
- $service->validateContainerDepth(content: ['text' => 'plain label, no placements']);
- $this->assertTrue(true, 'leaf content blob must not raise');
- }
+ public function testValidateContainerDepthAcceptsLeaf(): void {
+ $service = new WidgetPlacementService();
+ $service->validateContainerDepth(content: ['text' => 'plain label, no placements']);
+ $this->assertTrue(true, 'leaf content blob must not raise');
+ }
- public function testValidateContainerDepthAcceptsDepthOne(): void
- {
- $service = new WidgetPlacementService();
- $service->validateContainerDepth(content: $this->buildNested(depth: 1));
- $this->assertTrue(true, 'depth 1 (one container with non-container child) must pass');
- }
+ public function testValidateContainerDepthAcceptsDepthOne(): void {
+ $service = new WidgetPlacementService();
+ $service->validateContainerDepth(content: $this->buildNested(depth: 1));
+ $this->assertTrue(true, 'depth 1 (one container with non-container child) must pass');
+ }
- public function testValidateContainerDepthAcceptsDepthTwo(): void
- {
- $service = new WidgetPlacementService();
- $service->validateContainerDepth(content: $this->buildNested(depth: 2));
- $this->assertTrue(true, 'depth 2 must pass (under cap)');
- }
+ public function testValidateContainerDepthAcceptsDepthTwo(): void {
+ $service = new WidgetPlacementService();
+ $service->validateContainerDepth(content: $this->buildNested(depth: 2));
+ $this->assertTrue(true, 'depth 2 must pass (under cap)');
+ }
- public function testValidateContainerDepthAcceptsDepthThree(): void
- {
- $service = new WidgetPlacementService();
- $service->validateContainerDepth(content: $this->buildNested(depth: 3));
- $this->assertTrue(true, 'depth 3 must pass (== MAX_CONTAINER_DEPTH)');
- }
+ public function testValidateContainerDepthAcceptsDepthThree(): void {
+ $service = new WidgetPlacementService();
+ $service->validateContainerDepth(content: $this->buildNested(depth: 3));
+ $this->assertTrue(true, 'depth 3 must pass (== MAX_CONTAINER_DEPTH)');
+ }
- public function testValidateContainerDepthRejectsDepthFour(): void
- {
- $service = new WidgetPlacementService();
- $this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('container_depth_exceeded');
- $service->validateContainerDepth(content: $this->buildNested(depth: 4));
- }
+ public function testValidateContainerDepthRejectsDepthFour(): void {
+ $service = new WidgetPlacementService();
+ $this->expectException(InvalidArgumentException::class);
+ $this->expectExceptionMessage('container_depth_exceeded');
+ $service->validateContainerDepth(content: $this->buildNested(depth: 4));
+ }
- public function testValidateContainerDepthIgnoresNonContainerChildren(): void
- {
- // A 4-deep tree where the deepest level is a label (no
- // placements) should still pass — only nested CONTAINERS push
- // the depth counter, not arbitrary children.
- $service = new WidgetPlacementService();
- $depth3 = [
- 'placements' => [
- [
- 'type' => 'container',
- 'content' => [
- 'placements' => [
- [
- 'type' => 'container',
- 'content' => [
- 'placements' => [
- [
- 'type' => 'label',
- 'content' => ['text' => 'OK at depth 3'],
- ],
- ],
- ],
- ],
- ],
- ],
- ],
- ],
- ];
- $service->validateContainerDepth(content: $depth3);
- $this->assertTrue(true);
- }
+ public function testValidateContainerDepthIgnoresNonContainerChildren(): void {
+ // A 4-deep tree where the deepest level is a label (no
+ // placements) should still pass — only nested CONTAINERS push
+ // the depth counter, not arbitrary children.
+ $service = new WidgetPlacementService();
+ $depth3 = [
+ 'placements' => [
+ [
+ 'type' => 'container',
+ 'content' => [
+ 'placements' => [
+ [
+ 'type' => 'container',
+ 'content' => [
+ 'placements' => [
+ [
+ 'type' => 'label',
+ 'content' => ['text' => 'OK at depth 3'],
+ ],
+ ],
+ ],
+ ],
+ ],
+ ],
+ ],
+ ],
+ ];
+ $service->validateContainerDepth(content: $depth3);
+ $this->assertTrue(true);
+ }
- public function testMaxContainerDepthConstantIsThree(): void
- {
- $this->assertSame(
- expected: 3,
- actual: WidgetPlacementService::MAX_CONTAINER_DEPTH,
- message: 'REQ-CONT-006: maxDepth envelope value MUST be 3'
- );
- }
+ public function testMaxContainerDepthConstantIsThree(): void {
+ $this->assertSame(
+ expected: 3,
+ actual: WidgetPlacementService::MAX_CONTAINER_DEPTH,
+ message: 'REQ-CONT-006: maxDepth envelope value MUST be 3'
+ );
+ }
- public function testValidateContainerDepthHandlesEmptyPlacements(): void
- {
- // A container with an empty placements[] is depth 0 effectively
- // and should pass without raising.
- $service = new WidgetPlacementService();
- $service->validateContainerDepth(content: ['placements' => []]);
- $this->assertTrue(true);
- }
+ public function testValidateContainerDepthHandlesEmptyPlacements(): void {
+ // A container with an empty placements[] is depth 0 effectively
+ // and should pass without raising.
+ $service = new WidgetPlacementService();
+ $service->validateContainerDepth(content: ['placements' => []]);
+ $this->assertTrue(true);
+ }
}
diff --git a/tests/Unit/Service/WidgetServiceUpdateValidationTest.php b/tests/Unit/Service/WidgetServiceUpdateValidationTest.php
index a56ba947..7c5273d3 100644
--- a/tests/Unit/Service/WidgetServiceUpdateValidationTest.php
+++ b/tests/Unit/Service/WidgetServiceUpdateValidationTest.php
@@ -40,167 +40,161 @@
/**
* Tests for {@see WidgetService::updatePlacement()} content validation.
*/
-class WidgetServiceUpdateValidationTest extends TestCase
-{
-
- /** @var PlacementService&MockObject */
- private $placementService;
-
- private WidgetService $service;
-
- /**
- * Build the SUT with a real MenuService so the depth / field rules
- * actually execute; the other collaborators are irrelevant to the
- * update path and are mocked.
- *
- * @return void
- */
- protected function setUp(): void
- {
- parent::setUp();
-
- $this->placementService = $this->createMock(PlacementService::class);
-
- $this->service = new WidgetService(
- dashboardManager: $this->createMock(IManager::class),
- placementService: $this->placementService,
- widgetFormatter: $this->createMock(WidgetFormatter::class),
- widgetItemLoader: $this->createMock(WidgetItemLoader::class),
- userSession: $this->createMock(IUserSession::class),
- menuService: new MenuService(),
- );
- }//end setUp()
-
- /**
- * A menu placement updated with over-nested items (4 levels) MUST be
- * rejected — the same way the create path rejects it — and MUST NOT
- * reach the persistence layer.
- *
- * @return void
- */
- public function testUpdateRejectsOverNestedMenuContent(): void
- {
- $placement = new WidgetPlacement();
- $placement->setWidgetId('menu');
-
- $this->placementService
- ->method('getPlacement')
- ->with(placementId: 7)
- ->willReturn($placement);
-
- // Persistence MUST NOT be touched when validation fails.
- $this->placementService->expects($this->never())->method('updatePlacement');
-
- // items nested 4 deep -> exceeds MenuService::MAX_DEPTH (3).
- $content = [
- 'items' => [
- ['children' => [
- ['children' => [
- ['children' => [
- ['label' => 'too deep'],
- ]],
- ]],
- ]],
- ],
- ];
-
- $this->expectException(InvalidArgumentException::class);
- $this->expectExceptionMessage('Menu items can nest at most 3 levels deep');
-
- $this->service->updatePlacement(
- placementId: 7,
- data: ['content' => $content]
- );
- }//end testUpdateRejectsOverNestedMenuContent()
-
- /**
- * A menu placement updated with well-formed content (within the depth
- * cap) MUST pass validation and delegate to the persistence layer.
- *
- * @return void
- */
- public function testUpdateAcceptsValidMenuContent(): void
- {
- $placement = new WidgetPlacement();
- $placement->setWidgetId('menu');
-
- $this->placementService
- ->method('getPlacement')
- ->with(placementId: 7)
- ->willReturn($placement);
-
- $updated = new WidgetPlacement();
- $this->placementService
- ->expects($this->once())
- ->method('updatePlacement')
- ->willReturn($updated);
-
- $content = [
- 'items' => [
- ['label' => 'Top', 'children' => [['label' => 'Child']]],
- ],
- ];
-
- $result = $this->service->updatePlacement(
- placementId: 7,
- data: ['content' => $content]
- );
-
- $this->assertSame($updated, $result);
- }//end testUpdateAcceptsValidMenuContent()
-
- /**
- * A non-menu widget skips content validation entirely (the validator
- * is a no-op for non-`menu` types) and delegates straight through —
- * even with content that would be "over-nested" for a menu.
- *
- * @return void
- */
- public function testUpdateSkipsValidationForNonMenuWidget(): void
- {
- $placement = new WidgetPlacement();
- $placement->setWidgetId('text');
-
- $this->placementService
- ->method('getPlacement')
- ->with(placementId: 9)
- ->willReturn($placement);
-
- $updated = new WidgetPlacement();
- $this->placementService
- ->expects($this->once())
- ->method('updatePlacement')
- ->willReturn($updated);
-
- $result = $this->service->updatePlacement(
- placementId: 9,
- data: ['content' => ['items' => [['children' => [['children' => [['children' => [[]]]]]]]]]]
- );
-
- $this->assertSame($updated, $result);
- }//end testUpdateSkipsValidationForNonMenuWidget()
-
- /**
- * An update without a `content` payload MUST NOT fetch the placement
- * for validation — it delegates directly to the persistence layer.
- *
- * @return void
- */
- public function testUpdateWithoutContentSkipsContentValidation(): void
- {
- $this->placementService->expects($this->never())->method('getPlacement');
-
- $updated = new WidgetPlacement();
- $this->placementService
- ->expects($this->once())
- ->method('updatePlacement')
- ->willReturn($updated);
-
- $result = $this->service->updatePlacement(
- placementId: 7,
- data: ['customTitle' => 'Renamed']
- );
-
- $this->assertSame($updated, $result);
- }//end testUpdateWithoutContentSkipsContentValidation()
+class WidgetServiceUpdateValidationTest extends TestCase {
+
+ /** @var PlacementService&MockObject */
+ private $placementService;
+
+ private WidgetService $service;
+
+ /**
+ * Build the SUT with a real MenuService so the depth / field rules
+ * actually execute; the other collaborators are irrelevant to the
+ * update path and are mocked.
+ *
+ * @return void
+ */
+ protected function setUp(): void {
+ parent::setUp();
+
+ $this->placementService = $this->createMock(PlacementService::class);
+
+ $this->service = new WidgetService(
+ dashboardManager: $this->createMock(IManager::class),
+ placementService: $this->placementService,
+ widgetFormatter: $this->createMock(WidgetFormatter::class),
+ widgetItemLoader: $this->createMock(WidgetItemLoader::class),
+ userSession: $this->createMock(IUserSession::class),
+ menuService: new MenuService(),
+ );
+ }//end setUp()
+
+ /**
+ * A menu placement updated with over-nested items (4 levels) MUST be
+ * rejected — the same way the create path rejects it — and MUST NOT
+ * reach the persistence layer.
+ *
+ * @return void
+ */
+ public function testUpdateRejectsOverNestedMenuContent(): void {
+ $placement = new WidgetPlacement();
+ $placement->setWidgetId('menu');
+
+ $this->placementService
+ ->method('getPlacement')
+ ->with(placementId: 7)
+ ->willReturn($placement);
+
+ // Persistence MUST NOT be touched when validation fails.
+ $this->placementService->expects($this->never())->method('updatePlacement');
+
+ // items nested 4 deep -> exceeds MenuService::MAX_DEPTH (3).
+ $content = [
+ 'items' => [
+ ['children' => [
+ ['children' => [
+ ['children' => [
+ ['label' => 'too deep'],
+ ]],
+ ]],
+ ]],
+ ],
+ ];
+
+ $this->expectException(InvalidArgumentException::class);
+ $this->expectExceptionMessage('Menu items can nest at most 3 levels deep');
+
+ $this->service->updatePlacement(
+ placementId: 7,
+ data: ['content' => $content]
+ );
+ }//end testUpdateRejectsOverNestedMenuContent()
+
+ /**
+ * A menu placement updated with well-formed content (within the depth
+ * cap) MUST pass validation and delegate to the persistence layer.
+ *
+ * @return void
+ */
+ public function testUpdateAcceptsValidMenuContent(): void {
+ $placement = new WidgetPlacement();
+ $placement->setWidgetId('menu');
+
+ $this->placementService
+ ->method('getPlacement')
+ ->with(placementId: 7)
+ ->willReturn($placement);
+
+ $updated = new WidgetPlacement();
+ $this->placementService
+ ->expects($this->once())
+ ->method('updatePlacement')
+ ->willReturn($updated);
+
+ $content = [
+ 'items' => [
+ ['label' => 'Top', 'children' => [['label' => 'Child']]],
+ ],
+ ];
+
+ $result = $this->service->updatePlacement(
+ placementId: 7,
+ data: ['content' => $content]
+ );
+
+ $this->assertSame($updated, $result);
+ }//end testUpdateAcceptsValidMenuContent()
+
+ /**
+ * A non-menu widget skips content validation entirely (the validator
+ * is a no-op for non-`menu` types) and delegates straight through —
+ * even with content that would be "over-nested" for a menu.
+ *
+ * @return void
+ */
+ public function testUpdateSkipsValidationForNonMenuWidget(): void {
+ $placement = new WidgetPlacement();
+ $placement->setWidgetId('text');
+
+ $this->placementService
+ ->method('getPlacement')
+ ->with(placementId: 9)
+ ->willReturn($placement);
+
+ $updated = new WidgetPlacement();
+ $this->placementService
+ ->expects($this->once())
+ ->method('updatePlacement')
+ ->willReturn($updated);
+
+ $result = $this->service->updatePlacement(
+ placementId: 9,
+ data: ['content' => ['items' => [['children' => [['children' => [['children' => [[]]]]]]]]]]
+ );
+
+ $this->assertSame($updated, $result);
+ }//end testUpdateSkipsValidationForNonMenuWidget()
+
+ /**
+ * An update without a `content` payload MUST NOT fetch the placement
+ * for validation — it delegates directly to the persistence layer.
+ *
+ * @return void
+ */
+ public function testUpdateWithoutContentSkipsContentValidation(): void {
+ $this->placementService->expects($this->never())->method('getPlacement');
+
+ $updated = new WidgetPlacement();
+ $this->placementService
+ ->expects($this->once())
+ ->method('updatePlacement')
+ ->willReturn($updated);
+
+ $result = $this->service->updatePlacement(
+ placementId: 7,
+ data: ['customTitle' => 'Renamed']
+ );
+
+ $this->assertSame($updated, $result);
+ }//end testUpdateWithoutContentSkipsContentValidation()
}//end class
diff --git a/tests/Unit/Settings/RegisterDescriptorTest.php b/tests/Unit/Settings/RegisterDescriptorTest.php
index 4a5a13eb..3a5c2e5d 100644
--- a/tests/Unit/Settings/RegisterDescriptorTest.php
+++ b/tests/Unit/Settings/RegisterDescriptorTest.php
@@ -41,133 +41,129 @@
/**
* Static validation of the OpenRegister descriptor this app ships.
*/
-class RegisterDescriptorTest extends TestCase
-{
- /**
- * Property types OpenRegister's PropertyValidatorHandler accepts.
- *
- * Mirrors its `$validTypes`. A union (array) type is rejected outright.
- *
- * @var array
- */
- private const VALID_TYPES = [
- 'string',
- 'number',
- 'integer',
- 'boolean',
- 'array',
- 'object',
- 'null',
- 'file',
- 'geo',
- 'color',
- 'recurrence',
- ];
-
- /**
- * The decoded descriptor.
- *
- * @return array
- */
- private function descriptor(): array
- {
- $path = dirname(__DIR__, 3).'/lib/Settings/launchpad_register.json';
- $this->assertFileExists($path, 'the register descriptor must ship with the app');
-
- $data = json_decode((string) file_get_contents($path), true);
- $this->assertIsArray($data, 'the register descriptor must be valid JSON');
-
- return $data;
- }
-
- /**
- * The descriptor must declare the register, not only its schemas.
- *
- * @return void
- */
- public function testTheRegisterIsDeclared(): void
- {
- $d = $this->descriptor();
-
- $this->assertArrayHasKey(
- 'registers',
- $d['components'] ?? [],
- 'without components.registers nothing creates the register, and every '
- .'OpenRegister-backed feature fails with "Register not found"',
- );
-
- $register = $d['components']['registers']['launchpad'] ?? null;
- $this->assertIsArray($register, 'the `launchpad` register must be declared');
- $this->assertSame('launchpad', $register['slug'] ?? null);
-
- // The register's schema references are matched by SLUG (OpenRegister keys
- // its import-time schemasMap on the schema's slug, not on the map key —
- // here the map key is `Dashboard` while the slug is `dashboard`).
- $slugs = [];
- foreach (($d['components']['schemas'] ?? []) as $schema) {
- if (isset($schema['slug']) === true) {
- $slugs[] = $schema['slug'];
- }
- }
-
- $this->assertNotEmpty($slugs, 'control: the descriptor must declare at least one schema slug');
-
- foreach (($register['schemas'] ?? []) as $ref) {
- $this->assertContains(
- $ref,
- $slugs,
- "the register references schema '$ref', which no declared schema's `slug` provides",
- );
- }
- }
-
- /**
- * Every property type must be a scalar OpenRegister accepts.
- *
- * @return void
- */
- public function testNoPropertyUsesAnUnsupportedType(): void
- {
- $d = $this->descriptor();
- $offenders = [];
- $checked = 0;
-
- foreach (($d['components']['schemas'] ?? []) as $schemaKey => $schema) {
- foreach (($schema['properties'] ?? []) as $name => $property) {
- if (array_key_exists('type', $property) === false) {
- continue;
- }
-
- $checked++;
- $type = $property['type'];
-
- if (is_array($type) === true) {
- $offenders[] = sprintf(
- '%s.%s: union type %s — OpenRegister accepts scalar types only; '
- .'model optionality by leaving the property out of `required`',
- $schemaKey,
- $name,
- json_encode($type),
- );
- continue;
- }
-
- if (in_array($type, self::VALID_TYPES, true) === false) {
- $offenders[] = sprintf('%s.%s: unsupported type %s', $schemaKey, $name, json_encode($type));
- }
- }
- }
-
- // Control: if the walk found no typed properties at all, the assertion
- // below would pass while inspecting nothing.
- $this->assertGreaterThan(5, $checked, 'the property walk found almost nothing — it is not reaching the schema');
-
- $this->assertSame(
- [],
- $offenders,
- "OpenRegister rejects the whole schema on an invalid property type, then creates the register "
- ."WITHOUT a reference to it and merely logs a warning — so this surfaces much later as a "
- ."misleading \"Schema not found\":\n".implode("\n", $offenders),
- );
- }
+class RegisterDescriptorTest extends TestCase {
+ /**
+ * Property types OpenRegister's PropertyValidatorHandler accepts.
+ *
+ * Mirrors its `$validTypes`. A union (array) type is rejected outright.
+ *
+ * @var array
+ */
+ private const VALID_TYPES = [
+ 'string',
+ 'number',
+ 'integer',
+ 'boolean',
+ 'array',
+ 'object',
+ 'null',
+ 'file',
+ 'geo',
+ 'color',
+ 'recurrence',
+ ];
+
+ /**
+ * The decoded descriptor.
+ *
+ * @return array
+ */
+ private function descriptor(): array {
+ $path = dirname(__DIR__, 3) . '/lib/Settings/launchpad_register.json';
+ $this->assertFileExists($path, 'the register descriptor must ship with the app');
+
+ $data = json_decode((string)file_get_contents($path), true);
+ $this->assertIsArray($data, 'the register descriptor must be valid JSON');
+
+ return $data;
+ }
+
+ /**
+ * The descriptor must declare the register, not only its schemas.
+ *
+ * @return void
+ */
+ public function testTheRegisterIsDeclared(): void {
+ $d = $this->descriptor();
+
+ $this->assertArrayHasKey(
+ 'registers',
+ $d['components'] ?? [],
+ 'without components.registers nothing creates the register, and every '
+ . 'OpenRegister-backed feature fails with "Register not found"',
+ );
+
+ $register = $d['components']['registers']['launchpad'] ?? null;
+ $this->assertIsArray($register, 'the `launchpad` register must be declared');
+ $this->assertSame('launchpad', $register['slug'] ?? null);
+
+ // The register's schema references are matched by SLUG (OpenRegister keys
+ // its import-time schemasMap on the schema's slug, not on the map key —
+ // here the map key is `Dashboard` while the slug is `dashboard`).
+ $slugs = [];
+ foreach (($d['components']['schemas'] ?? []) as $schema) {
+ if (isset($schema['slug']) === true) {
+ $slugs[] = $schema['slug'];
+ }
+ }
+
+ $this->assertNotEmpty($slugs, 'control: the descriptor must declare at least one schema slug');
+
+ foreach (($register['schemas'] ?? []) as $ref) {
+ $this->assertContains(
+ $ref,
+ $slugs,
+ "the register references schema '$ref', which no declared schema's `slug` provides",
+ );
+ }
+ }
+
+ /**
+ * Every property type must be a scalar OpenRegister accepts.
+ *
+ * @return void
+ */
+ public function testNoPropertyUsesAnUnsupportedType(): void {
+ $d = $this->descriptor();
+ $offenders = [];
+ $checked = 0;
+
+ foreach (($d['components']['schemas'] ?? []) as $schemaKey => $schema) {
+ foreach (($schema['properties'] ?? []) as $name => $property) {
+ if (array_key_exists('type', $property) === false) {
+ continue;
+ }
+
+ $checked++;
+ $type = $property['type'];
+
+ if (is_array($type) === true) {
+ $offenders[] = sprintf(
+ '%s.%s: union type %s — OpenRegister accepts scalar types only; '
+ . 'model optionality by leaving the property out of `required`',
+ $schemaKey,
+ $name,
+ json_encode($type),
+ );
+ continue;
+ }
+
+ if (in_array($type, self::VALID_TYPES, true) === false) {
+ $offenders[] = sprintf('%s.%s: unsupported type %s', $schemaKey, $name, json_encode($type));
+ }
+ }
+ }
+
+ // Control: if the walk found no typed properties at all, the assertion
+ // below would pass while inspecting nothing.
+ $this->assertGreaterThan(5, $checked, 'the property walk found almost nothing — it is not reaching the schema');
+
+ $this->assertSame(
+ [],
+ $offenders,
+ 'OpenRegister rejects the whole schema on an invalid property type, then creates the register '
+ . 'WITHOUT a reference to it and merely logs a warning — so this surfaces much later as a '
+ . "misleading \"Schema not found\":\n" . implode("\n", $offenders),
+ );
+ }
}//end class
diff --git a/tests/bootstrap.php b/tests/bootstrap.php
index c6fbba0a..9e9138d0 100644
--- a/tests/bootstrap.php
+++ b/tests/bootstrap.php
@@ -25,43 +25,43 @@
define('PHPUNIT_RUN', 1);
// Include Composer's autoloader.
-require_once __DIR__.'/../vendor/autoload.php';
+require_once __DIR__ . '/../vendor/autoload.php';
// Bootstrap Nextcloud — use full NC environment when explicitly requested
// (PHPUNIT_USE_NC_BOOTSTRAP=1) or when the environment is pre-configured
// (e.g. a running NC container). Fall back to OCP stubs otherwise so that
// unit tests can run in any CI builder container without a live NC install.
-$ncBasePhp = __DIR__.'/../../../lib/base.php';
+$ncBasePhp = __DIR__ . '/../../../lib/base.php';
$ncUseFull = (file_exists($ncBasePhp) === true)
- && getenv('PHPUNIT_USE_NC_BOOTSTRAP') === '1';
+ && getenv('PHPUNIT_USE_NC_BOOTSTRAP') === '1';
if ($ncUseFull === true) {
- include_once $ncBasePhp;
-} else if (is_dir(__DIR__.'/../vendor/nextcloud/ocp/OCP') === true) {
- // Outside the container we register the OCP stubs from
- // vendor/nextcloud/ocp so unit tests that mock OCP interfaces
- // (e.g. IInitialState) can still run. These are signature-only
- // stubs and are sufficient for PHPUnit's createMock().
- // Doctrine DBAL placeholders MUST be loaded before the OCP PSR-4
- // loader is registered. IQueryBuilder.php contains class constants
- // that reference Doctrine\DBAL\ParameterType directly
- // (e.g. `PARAM_NULL = ParameterType::NULL`). PHP evaluates these
- // constant expressions as soon as the interface file is parsed —
- // before any mock creation code runs. Loading the stubs first
- // ensures the placeholder classes are in the class table before
- // the autoloader first touches IQueryBuilder.php.
- include_once __DIR__.'/Stubs/DoctrineStubs.php';
+ include_once $ncBasePhp;
+} elseif (is_dir(__DIR__ . '/../vendor/nextcloud/ocp/OCP') === true) {
+ // Outside the container we register the OCP stubs from
+ // vendor/nextcloud/ocp so unit tests that mock OCP interfaces
+ // (e.g. IInitialState) can still run. These are signature-only
+ // stubs and are sufficient for PHPUnit's createMock().
+ // Doctrine DBAL placeholders MUST be loaded before the OCP PSR-4
+ // loader is registered. IQueryBuilder.php contains class constants
+ // that reference Doctrine\DBAL\ParameterType directly
+ // (e.g. `PARAM_NULL = ParameterType::NULL`). PHP evaluates these
+ // constant expressions as soon as the interface file is parsed —
+ // before any mock creation code runs. Loading the stubs first
+ // ensures the placeholder classes are in the class table before
+ // the autoloader first touches IQueryBuilder.php.
+ include_once __DIR__ . '/Stubs/DoctrineStubs.php';
- $ocpLoader = new \Composer\Autoload\ClassLoader();
- $ocpLoader->addPsr4('OCP\\', __DIR__.'/../vendor/nextcloud/ocp/OCP/');
- $ocpLoader->register();
+ $ocpLoader = new \Composer\Autoload\ClassLoader();
+ $ocpLoader->addPsr4('OCP\\', __DIR__ . '/../vendor/nextcloud/ocp/OCP/');
+ $ocpLoader->register();
}//end if
// Register Test\ namespace for NC test classes.
-$serverTestsLib = __DIR__.'/../../../tests/lib/';
+$serverTestsLib = __DIR__ . '/../../../tests/lib/';
if (is_dir($serverTestsLib) === true) {
- $loader = new \Composer\Autoload\ClassLoader();
- $loader->addPsr4('Test\\', $serverTestsLib);
- $loader->register(true);
+ $loader = new \Composer\Autoload\ClassLoader();
+ $loader->addPsr4('Test\\', $serverTestsLib);
+ $loader->register(true);
}
// Bootstrap complete.
diff --git a/tests/phpstan/apphost-symbols.php b/tests/phpstan/apphost-symbols.php
index 6aa8ee24..9f8aa196 100644
--- a/tests/phpstan/apphost-symbols.php
+++ b/tests/phpstan/apphost-symbols.php
@@ -16,16 +16,13 @@
namespace OCA\OpenRegister\AppHost\Observability;
-class ManifestLoader
-{
+class ManifestLoader {
}
-class HealthCheckExecutor
-{
+class HealthCheckExecutor {
}
-class MetricsEngine
-{
+class MetricsEngine {
}
namespace OCA\OpenRegister\AppHost\Controller;
@@ -38,36 +35,32 @@ class MetricsEngine
use OCP\AppFramework\Http\TextPlainResponse;
use OCP\IRequest;
-class GenericHealthController extends Controller
-{
- public function __construct(
- string $appName,
- IRequest $request,
- ManifestLoader $manifestLoader,
- HealthCheckExecutor $executor
- ) {
- parent::__construct($appName, $request);
- }
+class GenericHealthController extends Controller {
+ public function __construct(
+ string $appName,
+ IRequest $request,
+ ManifestLoader $manifestLoader,
+ HealthCheckExecutor $executor,
+ ) {
+ parent::__construct($appName, $request);
+ }
- public function index(): JSONResponse
- {
- return new JSONResponse();
- }
+ public function index(): JSONResponse {
+ return new JSONResponse();
+ }
}
-class GenericMetricsController extends Controller
-{
- public function __construct(
- string $appName,
- IRequest $request,
- ManifestLoader $manifestLoader,
- MetricsEngine $engine
- ) {
- parent::__construct($appName, $request);
- }
+class GenericMetricsController extends Controller {
+ public function __construct(
+ string $appName,
+ IRequest $request,
+ ManifestLoader $manifestLoader,
+ MetricsEngine $engine,
+ ) {
+ parent::__construct($appName, $request);
+ }
- public function index(): TextPlainResponse
- {
- return new TextPlainResponse('');
- }
+ public function index(): TextPlainResponse {
+ return new TextPlainResponse('');
+ }
}