Skip to content

feat: Document uploaded files as multipart request bodies - #401

Open
mateuscmtropical wants to merge 1 commit into
nextcloud:mainfrom
mateuscmtropical:feat/uploaded-files-multipart
Open

mateuscmtropical wants to merge 1 commit into
nextcloud:mainfrom
mateuscmtropical:feat/uploaded-files-multipart

Conversation

@mateuscmtropical

Copy link
Copy Markdown

Fixes #343

Controller methods that call $this->request->getUploadedFile('name') now get a multipart/form-data request body. Each uploaded file is a string property with format: binary. Detection works the same way as for getParam() and getHeader().

  • The multipart schema also contains the method's body parameters and their required list. The existing application/json body stays, so clients that do not upload a file can still send JSON.
  • Uploaded files are never marked as required, because getUploadedFile() returns null when the field is missing.
  • Only POST routes get the multipart body, because PHP only fills $_FILES for POST. Other verbs log a warning.
  • A non-literal argument, such as getUploadedFile($key), logs a warning and is skipped, so existing apps do not start failing.

Known limitations:

  • An upload read inside a helper method, not in the route method itself, is not detected. The same applies to getParam().
  • A multi-file field (files[]) is documented as a single binary, since the code does not show how many files are expected.

Tests: added two fixture endpoints (body parameter plus files, and file only) and regenerated the test specs. I also ran the patched tool on LibreSign. Five upload endpoints got a multipart body (account/pfx, file/validate, file/{uuid}/add-file, admin/signature-background, admin/certificate-policy) and nothing else changed.

Signed-off-by: mateuscmtropical <mateuscmtropical@gmail.com>
@max-nextcloud

Copy link
Copy Markdown

Thanks a lot for looking into this! I hope I'll find some time to try it out in the coming days. Looked good at a first glance.

@lfals

lfals commented Nov 16, 2026

Copy link
Copy Markdown

Thanks for working on #343. Automatically detecting getUploadedFile() calls is a useful improvement, and I think we should preserve it.

Looking at existing applications maintained by the Nextcloud organization, there are cases where automatic detection alone cannot accurately describe the multipart contract:

  1. Collectives: PageController::uploadAttachment() rejects missing files, but the current implementation would document the upload as optional. A nullable return value from getUploadedFile() does not mean the file is optional.
  2. Forms: ApiController::uploadFiles() processes multiple uploaded files. These should be represented as an array of binary values rather than a single binary string. Talk also demonstrates PHP's array-shaped upload representation.
  3. Mail: MessageApiController::handleAttachments() reads uploads inside a private helper method, so inspecting only the route method misses them.

Could we complement automatic detection with optional declarative metadata for cases that cannot be inferred reliably?

Nextcloud already provides a precedent through RequestHeader, which supports indirect: true for headers accessed outside the controller method.

A similar attribute could look like this:

// Illustrative API, not currently part of OCP.
#[RequestFile(
    requestKey: 'files',
    fieldName: 'files[]',
    multiple: true,
    required: true,
    indirect: true,
)]

public function uploadFiles(): DataResponse {
    return $this->handleUpload();
}

This would distinguish the getUploadedFile() key from the actual multipart field name, while describing cardinality, requiredness, and indirect access.

For endpoints supporting both JSON and multipart with different request structures, explicit request-body metadata might also be necessary instead of automatically copying the JSON schema.

I would suggest adding regression tests for required and optional files, multiple uploads, indirect access, and alternative request formats. Both requestBody.required and the schema's required properties should reflect the actual endpoint contract.

I'm not suggesting that a new OCP attribute should block #401. Automatic detection can remain the default, with explicit metadata introduced separately when inference is insufficient.

If this is outside the current PR's scope, could we agree on the declarative approach as a follow-up and ensure unsupported cases do not silently produce misleading schemas?

What do you think?

@mateuscmtropical

Copy link
Copy Markdown
Author

Thanks for checking these apps, that is very useful.

I agree. Automatic detection stays the default, and an attribute like RequestFile can describe what the code does not show: a required file, several files, a field name that differs from the getUploadedFile() key, and an upload read in a helper. indirect: true on RequestHeader is a good model for the last one. Since the attribute has to be added to OCP in nextcloud/server first, I'd do it as a follow-up. I can open an issue for it if you like.

The cases this PR can't infer are listed under "Known limitations" in the description: an upload read in a helper gets no multipart body, a files[] field is documented as one binary, and every file is optional. The attribute would let an app correct each of them.

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.

Add support for file uploads

3 participants