Skip to content

feat: Describe uploaded files with the RequestFile attribute - #405

Draft
lfals wants to merge 3 commits into
nextcloud:mainfrom
lfals:feat/request-file-attribute
Draft

lfals wants to merge 3 commits into
nextcloud:mainfrom
lfals:feat/request-file-attribute

Conversation

@lfals

@lfals lfals commented Nov 18, 2026 •

Copy link
Copy Markdown

Closes #404

Builds on #401, so this branch contains its commit until that is merged.

Problem

Automatic detection of getUploadedFile() can not describe every upload endpoint:

  • A missing file returns null, so a required file is documented as optional.
  • Several files (files[]) are documented as a single files part, which Talk and Forms reject.
  • The multipart field (files[]) can differ from the getUploadedFile() key (files).
  • A read in a helper method is not seen at all.

Change

Optional #[RequestFile(requestKey, fieldName, multiple, required, indirect)] attribute, read by name like RequestHeader. Detection stays the default; the attribute overrides a detected file with the same key.

  • required: true adds the field to the multipart required list and makes the request body required. application/json is then not offered, because a JSON body can not carry the file.
  • multiple: true documents an array of binary strings, with minItems: 1 when required. fieldName defaults to requestKey[].
  • indirect: true marks a file read outside the controller method. Without it, an attribute that matches no getUploadedFile() call is an error, as with RequestHeader.
  • A route can take file references as JSON and the files themselves as multipart under the same names (array $files = [] and getUploadedFile('files')). An optional body parameter named like an uploaded file field, ignoring a trailing [], is only documented in the JSON body. A required one stays in both bodies, and an exact name clash on it is an error, because a file part can not fill it.
  • Duplicate field names and non-literal arguments are reported.

Not covered, and listed in the README: requiring "at least one of several files", fields that only exist in the multipart body, and both file and file[] for the same request key. The attribute does not exist in OCP yet, so only the extractor side is added here.

How to verify

composer test:unit regenerates the specs in tests/; the new fixtures are uploadedFileRequired, uploadedFilesMultiple, uploadedFileIndirect and uploadedFilesOrReferences in SettingsController. composer lint and composer cs:check pass. Also tested against a Nextcloud 35.0.3 instance in Docker, with a small app that has a required file, files[] read in PHP's array form (as Forms and Talk do) and a file read in a private helper (as Mail does):

The JSON-only parameter rule was tested the same way, with a route taking array $file = [] and array $files = [] as JSON and file / files[] as multipart:

  • JSON with file (object) or files (list of objects) is accepted, as in the JSON schema.
  • Multipart with files[] (two files) or a single file is accepted, and the $file and $files arguments stay empty, as in the multipart schema, which has only the binary fields.
  • A request with neither is rejected with 400.

Not tested against the real Talk, Forms and Mail apps.

🤖 AI (if applicable)

  • The content of this PR was partly or fully generated using AI (N/A)

Signed-off-by: mateuscmtropical <mateuscmtropical@gmail.com>
@lfals lfals changed the title Feat/request file attribute feat: Add RequestFile attribute to describe uploaded files Nov 18, 2026
@lfals lfals changed the title feat: Add RequestFile attribute to describe uploaded files feat: Describe uploaded files with the RequestFile attribute Nov 18, 2026
Detection of getUploadedFile() calls can not describe required files,
several files (files[]), a field name that differs from the request key
or files that are read outside of the controller method.

The optional RequestFile attribute (requestKey, fieldName, multiple,
required, indirect) covers these cases. It is read by name like
RequestHeader and overrides the detected file with the same key.

- Required files are added to the multipart required list and make the
  request body required. application/json is not offered then, as it can
  not carry a file.
- Multiple files are documented as an array of binary strings, with
  minItems 1 when required.
- Conflicting field names and invalid attribute arguments are reported.

Closes nextcloud#404

Signed-off-by: Luis Amorim <principal@felps.zip>
…a file

A route can take file references as JSON and the files themselves as
multipart, with the same names (e.g. `array $files = []` and
getUploadedFile('files')). The multipart body copied the JSON schema,
so the object list was documented next to the binary file, or was
replaced by it for an exact name match, which failed the generation.

An optional body parameter named like an uploaded file field, ignoring
a trailing `[]`, is now only part of the JSON body. A required
parameter keeps its place in both bodies, and an exact name clash on
it is still an error, because a file part can not fill it.

Document the limits in the README: no "at least one file" constraint,
no multipart-only fields and one form per request key.

Signed-off-by: Luis Amorim <principal@felps.zip>
@lfals
lfals force-pushed the feat/request-file-attribute branch from 00d451e to e6b8628 Compare November 19, 2026 12:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Describe uploaded files that can not be detected from the code

2 participants