feat(context): add FormFiles for multi-file form fields

Author: coderianx

context.go

@@ -413,6 +413,24 @@ func (c *Context) FormFile(name string) (*multipart.FileHeader, error) {
 	return fh, nil
 }
 
+// FormFiles returns the multipart form files for the provided name.
+//
+// It is the plural counterpart of FormFile and is meant for form fields that carry more than one file, such as
+// `<input type="file" multiple>` or JavaScript FormData appending several files under the same field name.
+// FormFile only returns the first file for such fields, FormFiles returns all of them in the order they were sent.
+//
+// Returns http.ErrMissingFile when no files exist under the given name, matching FormFile behavior.
+func (c *Context) FormFiles(name string) ([]*multipart.FileHeader, error) {
+	if err := c.request.ParseMultipartForm(c.formParseMaxMemory); err != nil {
+		return nil, err
+	}
+	files := c.request.MultipartForm.File[name]
+	if len(files) == 0 {
+		return nil, http.ErrMissingFile
+	}
+	return files, nil
+}
+
 // MultipartForm returns the multipart form.
 func (c *Context) MultipartForm() (*multipart.Form, error) {
 	err := c.request.ParseMultipartForm(c.formParseMaxMemory)

context_test.go

@@ -1018,6 +1018,90 @@ func TestContextFormFile(t *testing.T) {
 	}
 }
 
+func TestContextFormFiles(t *testing.T) {
+	e := New()
+	buf := new(bytes.Buffer)
+	mw := multipart.NewWriter(buf)
+
+	// a non-file field and multiple files under the same field name, sent in the order they were written to the form
+	if err := mw.WriteField("name", "Jon Snow"); err != nil {
+		t.Fatal(err)
+	}
+	for _, filename := range []string{"a.txt", "b.txt", "c.txt"} {
+		w, err := mw.CreateFormFile("files", filename)
+		if assert.NoError(t, err) {
+			_, _ = w.Write([]byte(filename))
+		}
+	}
+	if err := mw.Close(); err != nil {
+		t.Fatal(err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/", buf)
+	req.Header.Set(HeaderContentType, mw.FormDataContentType())
+	rec := httptest.NewRecorder()
+	c := e.NewContext(req, rec)
+
+	files, err := c.FormFiles("files")
+	if assert.NoError(t, err) && assert.Len(t, files, 3) {
+		assert.Equal(t, "a.txt", files[0].Filename)
+		assert.Equal(t, "b.txt", files[1].Filename)
+		assert.Equal(t, "c.txt", files[2].Filename)
+	}
+}
+
+func TestContextFormFiles_singleFile(t *testing.T) {
+	e := New()
+	buf := new(bytes.Buffer)
+	mw := multipart.NewWriter(buf)
+	w, err := mw.CreateFormFile("files", "a.txt")
+	if assert.NoError(t, err) {
+		_, _ = w.Write([]byte("a"))
+	}
+	if assert.NoError(t, mw.Close()) {
+		req := httptest.NewRequest(http.MethodPost, "/", buf)
+		req.Header.Set(HeaderContentType, mw.FormDataContentType())
+		rec := httptest.NewRecorder()
+		c := e.NewContext(req, rec)
+
+		files, err := c.FormFiles("files")
+		if assert.NoError(t, err) && assert.Len(t, files, 1) {
+			assert.Equal(t, "a.txt", files[0].Filename)
+		}
+	}
+}
+
+func TestContextFormFiles_missing(t *testing.T) {
+	e := New()
+	buf := new(bytes.Buffer)
+	mw := multipart.NewWriter(buf)
+	w, err := mw.CreateFormFile("files", "a.txt")
+	if assert.NoError(t, err) {
+		_, _ = w.Write([]byte("a"))
+	}
+	if assert.NoError(t, mw.Close()) {
+		req := httptest.NewRequest(http.MethodPost, "/", buf)
+		req.Header.Set(HeaderContentType, mw.FormDataContentType())
+		rec := httptest.NewRecorder()
+		c := e.NewContext(req, rec)
+
+		files, err := c.FormFiles("other")
+		assert.Nil(t, files)
+		assert.ErrorIs(t, err, http.ErrMissingFile)
+	}
+}
+
+func TestContextFormFiles_nonMultipart(t *testing.T) {
+	e := New()
+	req := httptest.NewRequest(http.MethodPost, "/", strings.NewReader("name=value"))
+	req.Header.Set(HeaderContentType, MIMEApplicationForm)
+	rec := httptest.NewRecorder()
+	c := e.NewContext(req, rec)
+
+	files, err := c.FormFiles("files")
+	assert.Nil(t, files)
+	assert.ErrorIs(t, err, http.ErrNotMultipart)
+}
+
 func TestContextMultipartForm(t *testing.T) {
 	e := New()
 	buf := new(bytes.Buffer)