fix(theming): allow request theme override

[giacomoarru]

Summary

Adds a request-scoped query string override for light/dark theming:

• ?theme=light
• ?theme=dark

The override is not persisted to the user's settings.

Details

• Accepts only light and dark.
• Ignores invalid and non-string values.
• Preserves enabled themes of other types, such as OpenDyslexic.
• Keeps admin-configured enforce_theme behavior unchanged.
• Leaves getThemes() unchanged; the override is applied only in getEnabledThemes().

Testing

• php -l apps/theming/lib/Service/ThemesService.php
• php -l apps/theming/tests/Service/ThemesServiceTest.php
• composer test -- apps/theming/tests/Service/ThemesServiceTest.php

Manual testing

• Opened /login?theme=dark and verified data-theme-dark.
• Opened /login?theme=light and verified data-theme-light.
• Opened /login?theme=sepia and verified no override is applied.

[giacomoarru]

Justification

This pull request introduces a query string override to control the visual theme of embedded Nextcloud Forms.

The main use case is embedding public forms inside external websites via iframe. In this scenario, the surrounding website may have a fixed light design, while the embedded Nextcloud form can automatically switch to dark mode depending on the visitor’s device or browser preference, for example when the user has system-wide dark mode enabled.

This creates an inconsistent user experience: the external page remains white, but the embedded form is rendered with a dark background. In some cases, this also affects readability, branding consistency, and accessibility, especially when the form is intended to visually integrate with a light-themed public website.

A global configuration such as forcing the whole Nextcloud instance to light mode is not a suitable solution, because administrators may still want the rest of Nextcloud to respect user preferences or system theme settings. Similarly, applying custom CSS globally can have unintended side effects on other forms or other parts of the instance.

The proposed query string override solves this in a narrow and explicit way. It allows the embedding page to request a specific theme only for that embedded form view, without changing the global Nextcloud theme behavior and without affecting other users, other forms, or the rest of the instance.

Example use case:

<iframe
  src="https://cloud.example.com/index.php/apps/forms/embed/FORM_ID?theme=light"
  style="width:100%; border:0;">
</iframe>

This makes embedding Nextcloud Forms in external websites more predictable and easier to integrate, while preserving the existing default behavior when no override is provided.

The change is especially useful for organizations that use Nextcloud Forms as part of public-facing websites, intranets, landing pages, or customer portals where the visual appearance of the embedded form needs to match the host page.

[giacomoarru]

Live demo:

https://intranet.cipnes.com/index.php/apps/forms/embed/WBqx8WFSAwMX9Dtgdn7XKd3q?theme=light
https://intranet.cipnes.com/index.php/apps/forms/embed/WBqx8WFSAwMX9Dtgdn7XKd3q?theme=dark

[come-nc]

Won’t that conflict for routes that have a "theme" named parameter?

[giacomoarru]

Won’t that conflict for routes that have a "theme" named parameter?

You are correct - thanks for spotting this.
I will submit a new revision soon.

[giacomoarru]

Add a request-scoped light/dark theme override via the query string

Summary

Adds a request-scoped query string override for light/dark theming:

• ?theme=light
• ?theme=dark

The override is not persisted to the user's settings — it only affects the
themes resolved for the current request.

Why this approach (addressing the review feedback)

A previous iteration read the value with IRequest::getParam('theme'). As pointed
out in review, that is unsafe: getParam() does not read the query string only — it
returns a value from a merged bag built in lib/private/AppFramework/Http/Request.php:

$this->items['parameters'] = array_merge(
    $this->items['get'],       // ?theme=...  (query string)
    $this->items['post'],      // POST body
    $this->items['urlParams'], // route placeholders such as {theme}
    $this->items['params']
);

The documented precedence is 1. URL/route parameters → 2. POST → 3. GET, so a
route placeholder named theme (e.g. a route URL like /foo/{theme}) — or a POST
field named theme — would win over the query string. Because getEnabledThemes()
runs on virtually every rendered page across all apps (not just theming routes), any
such parameter anywhere (including in third-party apps) could hijack the override, or
conversely have its own theme segment reinterpreted as a light/dark request.

To eliminate the conflict, the override now reads exclusively from the URL query
string, by parsing the query part of IRequest::getRequestUri(). Route placeholders
and POST bodies can no longer interfere with — or be hijacked by — this feature.

Details

• Accepts only light and dark.
• Reads the value only from the query string (never route placeholders or POST).
• Ignores invalid values, missing values, array-style values (?theme[]=dark), and
  requests without a query string.
• Preserves enabled themes of other types, such as OpenDyslexic.
• Keeps admin-configured enforce_theme behavior unchanged — the enforced theme always
  takes precedence over this request-scoped override.
• Leaves getThemes() unchanged; the override is applied only in getEnabledThemes().

Testing

Static checks:

php -l apps/theming/lib/Service/ThemesService.php
php -l apps/theming/tests/Service/ThemesServiceTest.php
composer test -- apps/theming/tests/Service/ThemesServiceTest.php

Unit tests added/updated in ThemesServiceTest:

• ?theme=dark applies the dark theme for a guest.
• ?theme=light overrides the user's stored theme while keeping OpenDyslexic.
• ?theme=sepia (invalid) applies no override.
• ?theme[]=dark (non-string) applies no override.
• No query string applies no override.
• A route placeholder named theme (e.g. /apps/example/dark) applies no override
  — this is the regression test for the conflict raised in review.
• enforce_theme still takes precedence and the override is not even consulted.

Manual testing on a live instance:

• Opened /login?theme=dark and verified data-theme-dark.
• Opened /login?theme=light and verified data-theme-light.
• Opened /login?theme=sepia and verified no override is applied.

Notes for reviewers

IRequest intentionally exposes no query-string-only getter (getParam/getParams
both use the merged bag), so the query string is obtained by splitting
getRequestUri() on ? and parsing it with parse_str(). This keeps the change within
the public interface and fully unit-testable.