[vitormattos]

Problem

FileController::save() currently gives implicit precedence to the multipart files key over file, and to multipart uploads over JSON file references. The JSON files array similarly overrides file. If clients inadvertently provide multiple nonempty input representations, the API may return success while silently ignoring some supplied documents.

The endpoint's source documentation also omits the canonical single-file multipart field file used by the LibreSign frontend.

Changes

• Preserve the direct IRequest::getUploadedFile('file') and getUploadedFile('files') calls inside save(); this retains compatibility with the proposed detection in feat: Document uploaded files as multipart request bodies nextcloud/openapi-extractor#401.
• Reject ambiguous combinations of JSON file / files references and multipart file / files[] fields with the existing 422 response before persisting any file. A single selected input form is unchanged, including legacy file[] arrays.
• Clarify supported JSON and multipart input field names in the endpoint's PHP source documentation.
• Add focused PHPUnit regression cases for five valid input forms, four conflicting combinations, and an API controller call verifying 422/no persistence.

Non-goals / coordination

• No extractor changes, Composer patches, custom OpenAPI tags, hand-edited generated schemas or SDK generator work. Four generated description artifacts were synchronized directly from the composer openapi CI output. This protects current backend behavior but cannot generate missing multipart OpenAPI requestBody schemas; Document multipart uploads in the OpenAPI contract #9435 remains open.
• Does not overlap fix(signing): preserve nullable code request contracts #9454's signing-code defaults or fix(policies): allow mixed properties in policy value contracts #9453's policy/nullable type work. No change to EffectivePolicyValue solely to accommodate unsupported anyOf in typescript-axios.
• Requests using two file representations previously relied on undocumented precedence. They now fail explicitly; integrations that send both must choose one.

Validation

• 4 incremental commits signed and DCO-verified by Git Signing MCP.
• Static code review against main at 9a387bdbb844721d3607f6fa2b26522b6571785f.
• GitHub Actions confirmed OpenAPI regeneration, Psalm/static analysis, PHP-CS-Fixer, TypeScript checks and the Node/build jobs on the prior commit. The regenerated OpenAPI job passed after syncing the four generated descriptions.
• PHPUnit initially found two failures in positive control fixtures only: PHP associative upload metadata key order was being compared as meaningful. The focused test was corrected to sort each upload metadata map before strict comparison, without ignoring document order. The revised PHPUnit step passed in the PostgreSQL/PHP 8.5 workflow at 1e037b729c847ce4c20402a1951e21ffda4e6459.
• Remaining: full final-head CI matrix and real multipart HTTP transport against a running Nextcloud instance. Do not mark ready to merge on the basis of one green unit job.

Required CI / acceptance

• composer test:unit -- --filter FileControllerInputSourceTest
• composer openapi and the OpenAPI PHPUnit suite to ensure regenerated contracts match the new PHPDoc.
• Psalm, PHP lint / code style, and full PR checks.
• A live multipart request with both file and files[] must return 422 without creating files; each accepted form must retain the existing response.

Refs: #9435, #9437, nextcloud/openapi-extractor#401.

Do not auto-close #9435; upstream schema generation remains unresolved.

[github-actions]

Code Metrics Report

Note: Metrics describe the revision analyzed by the successful PHPUnit run. Newer commits with pending, canceled or failed checks may not yet be represented in this report.

	main (9a387bd)	#9490 (e1477fc)	+/-
Coverage	76.4%	76.6%	+0.1%
Test Execution Time	2m58s	3m42s	+44s

Details

  |                     | main (9a387bd) | #9490 (e1477fc) |  +/-  |
  |---------------------|----------------|-----------------|-------|
+ | Coverage            |          76.4% |           76.6% | +0.1% |
  |   Files             |            512 |             512 |     0 |
  |   Lines             |          28856 |           28862 |    +6 |
+ |   Covered           |          22072 |           22115 |   +43 |
- | Test Execution Time |          2m58s |           3m42s |  +44s |

Code coverage of files in pull request scope (26.9% → 38.9%, patch 100.0%)

Files	Coverage	+/-	Patch Coverage	Status
lib/Controller/FileController.php	38.9%	+12.0%	100.0%	modified

---

Reported by octocov

[vitormattos]

/backport to stable35

[vitormattos]

/backport to stable34

[vitormattos]

/backport to stable33