Repository navigation
Conversation
Signed-off-by: mateuscmtropical <mateuscmtropical@gmail.com>
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
force-pushed
the
feat/request-file-attribute
branch
from
November 19, 2026 12:36
00d451e to
e6b8628
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:null, so a required file is documented as optional.files[]) are documented as a singlefilespart, which Talk and Forms reject.files[]) can differ from thegetUploadedFile()key (files).Change
Optional
#[RequestFile(requestKey, fieldName, multiple, required, indirect)]attribute, read by name likeRequestHeader. Detection stays the default; the attribute overrides a detected file with the same key.required: trueadds the field to the multipartrequiredlist and makes the request body required.application/jsonis then not offered, because a JSON body can not carry the file.multiple: truedocuments an array of binary strings, withminItems: 1when required.fieldNamedefaults torequestKey[].indirect: truemarks a file read outside the controller method. Without it, an attribute that matches nogetUploadedFile()call is an error, as withRequestHeader.array $files = []andgetUploadedFile('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.Not covered, and listed in the README: requiring "at least one of several files", fields that only exist in the multipart body, and both
fileandfile[]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:unitregenerates the specs intests/; the new fixtures areuploadedFileRequired,uploadedFilesMultiple,uploadedFileIndirectanduploadedFilesOrReferencesinSettingsController.composer lintandcomposer cs:checkpass. 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):files[]field returns 400.filespart, as described by the spec from feat: Document uploaded files as multipart request bodies #401, is rejected with 400 on thefiles[]endpoint.files[]as onefilespart and had no request body for the helper case.The JSON-only parameter rule was tested the same way, with a route taking
array $file = []andarray $files = []as JSON andfile/files[]as multipart:file(object) orfiles(list of objects) is accepted, as in the JSON schema.files[](two files) or a singlefileis accepted, and the$fileand$filesarguments stay empty, as in the multipart schema, which has only the binary fields.Not tested against the real Talk, Forms and Mail apps.
🤖 AI (if applicable)