Add Attachments Feature (#3781)

# Description of Changes Added a new feature to add attachments to a PDF document. ### Added: - `AttachmentController`: Endpoint for adding attachments at `/add-attachments` with parameters `fileInput` for the PDF and `attachments` as a list of files to attach - `AttachmentServiceInterface` - `AttachmentService`: Handles the logic of adding attachments to the PDF - `AttachmentUtils`: to handle setting the catalog viewer preferences in the viewer - Add Attachments page - Tests for new feature ### Changes: - `EmlToPdf`: Moved setting of viewer preferences to `AttachmentUtils` - `EndpointConfiguration: Included '/add-attachments' - Updated language files with attachments copy - General clean up Closes #1259 --- ## Checklist ### General - [x] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [x] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable) - [x] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md) (if applicable) - [x] I have performed a self-review of my own code - [x] My changes generate no new warnings ### Documentation - [x] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [x] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### UI Changes (if applicable) ![348abcd235de976c347b8cd2c7979318](https://github.com/user-attachments/assets/56c3c992-7ab2-4723-8ddb-57038b557287) ![Screenshot 2025-06-20 at 13 52 53](https://github.com/user-attachments/assets/dc7a69c3-a85d-41c4-bac6-6a5d901459b9) ![Screenshot 2025-06-20 at 13 57 55](https://github.com/user-attachments/assets/8025a659-db7e-4441-946c-ce10414974ce) ![Screenshot 2025-06-20 at 13 58 20](https://github.com/user-attachments/assets/ae8d464e-1c95-4db1-92e6-1cf894fa4e83) - [x] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [x] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#6-testing) for more details.
2026-04-22 23:08:53 +02:00 · 2025-06-24 23:52:17 +01:00
parent 8e8f0492c4
commit 32aa568196
28 changed files with 624 additions and 76 deletions
--- a/stirling-pdf/src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java
@@ -10,6 +10,7 @@ import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.stereotype.Service;

 import lombok.extern.slf4j.Slf4j;
+
 import stirling.software.common.model.ApplicationProperties;

@Service
@@ -173,6 +174,7 @@ public class EndpointConfiguration {
        addEndpointToGroup("Other", "get-info-on-pdf");
        addEndpointToGroup("Other", "show-javascript");
        addEndpointToGroup("Other", "remove-image-pdf");
+        addEndpointToGroup("Other", "add-attachments");

        // CLI
        addEndpointToGroup("CLI", "compress-pdf");
@@ -251,6 +253,7 @@ public class EndpointConfiguration {
        addEndpointToGroup("Java", "pdf-to-text");
        addEndpointToGroup("Java", "remove-image-pdf");
        addEndpointToGroup("Java", "pdf-to-markdown");
+        addEndpointToGroup("Java", "add-attachments");

        // Javascript
        addEndpointToGroup("Javascript", "pdf-organizer");
--- a/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/MergeController.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/MergeController.java
@@ -225,7 +225,7 @@ public class MergeController {
            String mergedFileName =
                    files[0].getOriginalFilename().replaceFirst("[.][^.]+$", "")
                            + "_merged_unsigned.pdf";
-            return WebResponseUtils.boasToWebResponse(
+            return WebResponseUtils.baosToWebResponse(
                    baos, mergedFileName); // Return the modified PDF

        } catch (Exception ex) {
--- a/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/misc/AttachmentController.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/misc/AttachmentController.java
@@ -0,0 +1,57 @@
+package stirling.software.SPDF.controller.api.misc;
+
+import java.io.IOException;
+import java.util.List;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ModelAttribute;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.multipart.MultipartFile;
+
+import io.github.pixee.security.Filenames;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.SPDF.model.api.misc.AddAttachmentRequest;
+import stirling.software.SPDF.service.AttachmentServiceInterface;
+import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.util.WebResponseUtils;
+
+@Slf4j
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/v1/misc")
+@Tag(name = "Misc", description = "Miscellaneous APIs")
+public class AttachmentController {
+
+    private final CustomPDFDocumentFactory pdfDocumentFactory;
+
+    private final AttachmentServiceInterface pdfAttachmentService;
+
+    @PostMapping(consumes = "multipart/form-data", value = "/add-attachments")
+    @Operation(
+            summary = "Add attachments to PDF",
+            description =
+                    "This endpoint adds attachments to a PDF. Input:PDF, Output:PDF Type:MISO")
+    public ResponseEntity<byte[]> addAttachments(@ModelAttribute AddAttachmentRequest request)
+            throws IOException {
+        MultipartFile fileInput = request.getFileInput();
+        List<MultipartFile> attachments = request.getAttachments();
+
+        PDDocument document =
+                pdfAttachmentService.addAttachment(
+                        pdfDocumentFactory.load(fileInput, false), attachments);
+
+        return WebResponseUtils.pdfDocToWebResponse(
+                document,
+                Filenames.toSimpleFileName(fileInput.getOriginalFilename())
+                                .replaceFirst("[.][^.]+$", "")
+                        + "_with_attachments.pdf");
+    }
+}
--- a/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/misc/BlankPageController.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/misc/BlankPageController.java
@@ -144,7 +144,7 @@ public class BlankPageController {
            zos.close();

            log.info("Returning ZIP file: {}", filename + "_processed.zip");
-            return WebResponseUtils.boasToWebResponse(
+            return WebResponseUtils.baosToWebResponse(
                    baos, filename + "_processed.zip", MediaType.APPLICATION_OCTET_STREAM);

        } catch (IOException e) {
--- a/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/misc/ExtractImagesController.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/misc/ExtractImagesController.java
@@ -148,7 +148,7 @@ public class ExtractImagesController {
        // Create ByteArrayResource from byte array
        byte[] zipContents = baos.toByteArray();

-        return WebResponseUtils.boasToWebResponse(
+        return WebResponseUtils.baosToWebResponse(
                baos, filename + "_extracted-images.zip", MediaType.APPLICATION_OCTET_STREAM);
    }

--- a/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java
@@ -118,7 +118,7 @@ public class PipelineController {
            }
            zipOut.close();
            log.info("Returning zipped file response...");
-            return WebResponseUtils.boasToWebResponse(
+            return WebResponseUtils.baosToWebResponse(
                    baos, "output.zip", MediaType.APPLICATION_OCTET_STREAM);
        } catch (Exception e) {
            log.error("Error handling data: ", e);
--- a/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/security/CertSignController.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/controller/api/security/CertSignController.java
@@ -205,7 +205,7 @@ public class CertSignController {
                location,
                reason,
                showLogo);
-        return WebResponseUtils.boasToWebResponse(
+        return WebResponseUtils.baosToWebResponse(
                baos,
                Filenames.toSimpleFileName(pdf.getOriginalFilename()).replaceFirst("[.][^.]+$", "")
                        + "_signed.pdf");
--- a/stirling-pdf/src/main/java/stirling/software/SPDF/controller/web/OtherWebController.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/controller/web/OtherWebController.java
@@ -191,4 +191,11 @@ public class OtherWebController {
        model.addAttribute("currentPage", "auto-rename");
        return "misc/auto-rename";
    }
+
+    @GetMapping("/add-attachments")
+    @Hidden
+    public String attachmentsForm(Model model) {
+        model.addAttribute("currentPage", "add-attachments");
+        return "misc/add-attachments";
+    }
 }
--- a/stirling-pdf/src/main/java/stirling/software/SPDF/model/api/misc/AddAttachmentRequest.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/model/api/misc/AddAttachmentRequest.java
@@ -0,0 +1,23 @@
+package stirling.software.SPDF.model.api.misc;
+
+import java.util.List;
+
+import org.springframework.web.multipart.MultipartFile;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+import stirling.software.common.model.api.PDFFile;
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class AddAttachmentRequest extends PDFFile {
+
+    @Schema(
+            description = "The image file to be overlaid onto the PDF.",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            format = "binary")
+    private List<MultipartFile> attachments;
+}
--- a/stirling-pdf/src/main/java/stirling/software/SPDF/service/AttachmentService.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/service/AttachmentService.java
@@ -0,0 +1,105 @@
+package stirling.software.SPDF.service;
+
+import static stirling.software.common.util.AttachmentUtils.setCatalogViewerPreferences;
+
+import java.io.IOException;
+import java.util.GregorianCalendar;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDDocumentCatalog;
+import org.apache.pdfbox.pdmodel.PDDocumentNameDictionary;
+import org.apache.pdfbox.pdmodel.PDEmbeddedFilesNameTreeNode;
+import org.apache.pdfbox.pdmodel.PageMode;
+import org.apache.pdfbox.pdmodel.common.filespecification.PDComplexFileSpecification;
+import org.apache.pdfbox.pdmodel.common.filespecification.PDEmbeddedFile;
+import org.springframework.stereotype.Service;
+import org.springframework.web.multipart.MultipartFile;
+
+import lombok.extern.slf4j.Slf4j;
+
+@Slf4j
+@Service
+public class AttachmentService implements AttachmentServiceInterface {
+
+    @Override
+    public PDDocument addAttachment(PDDocument document, List<MultipartFile> attachments)
+            throws IOException {
+        PDEmbeddedFilesNameTreeNode embeddedFilesTree = getEmbeddedFilesTree(document);
+        Map<String, PDComplexFileSpecification> existingNames;
+
+        try {
+            Map<String, PDComplexFileSpecification> names = embeddedFilesTree.getNames();
+
+            if (names == null) {
+                log.debug("No existing embedded files found, creating new names map.");
+                existingNames = new HashMap<>();
+            } else {
+                existingNames = new HashMap<>(names);
+                log.debug("Embedded files: {}", existingNames.keySet());
+            }
+        } catch (IOException e) {
+            log.error("Could not retrieve existing embedded files", e);
+            throw e;
+        }
+
+        attachments.forEach(
+                attachment -> {
+                    String filename = attachment.getOriginalFilename();
+
+                    try {
+                        PDEmbeddedFile embeddedFile =
+                                new PDEmbeddedFile(document, attachment.getInputStream());
+                        embeddedFile.setSize((int) attachment.getSize());
+                        embeddedFile.setCreationDate(new GregorianCalendar());
+                        embeddedFile.setModDate(new GregorianCalendar());
+                        String contentType = attachment.getContentType();
+                        if (StringUtils.isNotBlank(contentType)) {
+                            embeddedFile.setSubtype(contentType);
+                        }
+
+                        // Create attachments specification and associate embedded attachment with
+                        // file
+                        PDComplexFileSpecification fileSpecification =
+                                new PDComplexFileSpecification();
+                        fileSpecification.setFile(filename);
+                        fileSpecification.setFileUnicode(filename);
+                        fileSpecification.setFileDescription("Embedded attachment: " + filename);
+                        fileSpecification.setEmbeddedFile(embeddedFile);
+                        fileSpecification.setEmbeddedFileUnicode(embeddedFile);
+
+                        existingNames.put(filename, fileSpecification);
+
+                        log.info("Added attachment: {} ({} bytes)", filename, attachment.getSize());
+                    } catch (IOException e) {
+                        log.warn("Failed to create embedded file for attachment: {}", filename, e);
+                    }
+                });
+
+        embeddedFilesTree.setNames(existingNames);
+        setCatalogViewerPreferences(document, PageMode.USE_ATTACHMENTS);
+
+        return document;
+    }
+
+    private PDEmbeddedFilesNameTreeNode getEmbeddedFilesTree(PDDocument document) {
+        PDDocumentCatalog catalog = document.getDocumentCatalog();
+        PDDocumentNameDictionary documentNames = catalog.getNames();
+
+        if (documentNames == null) {
+            documentNames = new PDDocumentNameDictionary(catalog);
+        }
+
+        catalog.setNames(documentNames);
+        PDEmbeddedFilesNameTreeNode embeddedFilesTree = documentNames.getEmbeddedFiles();
+
+        if (embeddedFilesTree == null) {
+            embeddedFilesTree = new PDEmbeddedFilesNameTreeNode();
+            documentNames.setEmbeddedFiles(embeddedFilesTree);
+        }
+        return embeddedFilesTree;
+    }
+}
--- a/stirling-pdf/src/main/java/stirling/software/SPDF/service/AttachmentServiceInterface.java
+++ b/stirling-pdf/src/main/java/stirling/software/SPDF/service/AttachmentServiceInterface.java
@@ -0,0 +1,13 @@
+package stirling.software.SPDF.service;
+
+import java.io.IOException;
+import java.util.List;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.springframework.web.multipart.MultipartFile;
+
+public interface AttachmentServiceInterface {
+
+    PDDocument addAttachment(PDDocument document, List<MultipartFile> attachments)
+            throws IOException;
+}