Common Use Cases for Aspose.PDF FOSS for Go

Aspose.PDF FOSS for Go is a pure-Go module for PDF document management. This article covers the most frequently needed operations using the Document, Form, EncryptionOptions, Table, and OutlineItemCollection types. Install with go get github.com/aspose-pdf-foss/aspose-pdf-foss-for-go.

Step-by-Step Guide

Step 1: Install the Package

Add the Go module dependency:

go get github.com/aspose-pdf-foss/aspose-pdf-foss-for-go

Step 2: Import the Package

Use an alias to keep import references concise:

import (
    "fmt"
    pdf "github.com/aspose-pdf-foss/aspose-pdf-foss-for-go"
)

Step 3: Split a PDF into Per-Page Files

Document.Split divides a multi-page document into one *Document per page.

doc, err := pdf.Open("report.pdf")
if err != nil {
    panic(err)
}
pages, _ := doc.Split()
for i, p := range pages {
    p.Save(fmt.Sprintf("report_page_%03d.pdf", i+1))
}
fmt.Printf("Split %d pages\n", len(pages))

Step 4: Merge Multiple PDFs into One

Document.Append merges pages from a second document in-place before saving.

base, _ := pdf.Open("intro.pdf")
chapter1, _ := pdf.Open("chapter1.pdf")
chapter2, _ := pdf.Open("chapter2.pdf")
appendix, _ := pdf.Open("appendix.pdf")

base.Append(chapter1)
base.Append(chapter2)
base.Append(appendix)
base.Save("full_document.pdf")

Step 5: Apply Password Encryption

EncryptionOptions configures user password, owner password, algorithm, and per-operation Permissions in a single call:

doc, _ := pdf.Open("contract.pdf")
doc.SetEncryption(pdf.EncryptionOptions{
    UserPassword:  "clientpass",
    OwnerPassword: "adminpass",
    Permissions:   &pdf.Permissions{AllowPrint: true, AllowCopy: false},
})
doc.Save("contract_protected.pdf")

To produce a plaintext copy from an encrypted file:

doc, _ := pdf.OpenWithPassword("contract_protected.pdf", "clientpass")
doc.RemoveEncryption()
doc.Save("contract_decrypted.pdf")

Step 6: Fill an AcroForm

Iterate or target fields by name. Assert the concrete type (TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField).

doc, _ := pdf.Open("application_form.pdf")

name := doc.Form().Field("applicant_name").(*pdf.TextBoxField)
name.SetValue("Jane Doe")

agree := doc.Form().Field("terms_accepted").(*pdf.CheckboxField)
agree.SetChecked(true)

country := doc.Form().Field("country").(*pdf.ComboBoxField)
country.SetSelected(0)

doc.Save("application_filled.pdf")

Step 7: Build a Table Layout

Add a Table with Row and Cell entries to a page for invoice or report generation:

doc, _ := pdf.Open("invoice_template.pdf")
page, _ := doc.Page(1)

tbl := pdf.NewTable()
tbl.ColumnWidths = []float64{200, 80, 100}

header := tbl.AddRow()
header.AddCell().SetText("Description")
header.AddCell().SetText("Qty")
header.AddCell().SetText("Amount")

row := tbl.AddRow()
row.AddCell().SetText("PDF Processing Service")
row.AddCell().SetText("1")
row.AddCell().SetText("$500.00")

page.AddTable(tbl)
doc.Save("invoice.pdf")

Step 8: Add a Bookmark Tree

OutlineItemCollection creates bookmarks with chapter/section nesting and DestinationXYZ page targets:

doc, _ := pdf.Open("manual.pdf")
page1, _ := doc.Page(1)
page2, _ := doc.Page(2)

ch1 := pdf.NewOutlineItemCollection(doc)
ch1.SetTitle("Introduction")
ch1.SetBold(true)
ch1.SetDestination(pdf.NewDestinationXYZ(page1, 0, 792, 1.0))
doc.Outlines().Add(ch1)

ch2 := pdf.NewOutlineItemCollection(doc)
ch2.SetTitle("Configuration")
ch2.SetDestination(pdf.NewDestinationFit(page2))
doc.Outlines().Add(ch2)

doc.Save("manual_bookmarked.pdf")

Common Issues and Fixes

pdf.Open returns an error for valid PDF files Check that the file path is correct and that the file is not open in another process. On Windows, file locking can prevent reads.

Type assertion panic when accessing form fields Use pdf.FieldType(f) or a type switch to inspect the field type before asserting. A *pdf.TextBoxField assertion on a CheckboxField will panic.

go get fails with “module not found” Ensure GOPROXY is set to a reachable proxy (e.g. GOPROXY=direct) and that your network can reach github.com. In air-gapped environments, use GONOSUMCHECK or a local module mirror.

SaveTo fails after OpenWithPassword If you call Save after OpenWithPassword without calling RemoveEncryption, the output is re-encrypted with the original password. This is the expected behaviour — call RemoveEncryption explicitly to produce a plaintext copy.

Merged document page count is wrong Append mutates the receiver in-place. Ensure you are not calling Append on a document that has already been saved; re-open the base document if you need to build multiple merged outputs.

Frequently Asked Questions

Can I process PDFs without writing to disk?

Document.WriteTo accepts an io.Writer, so you can write to a buffer, network stream, or response writer without creating a temporary file.

Is it safe to use Aspose.PDF FOSS for Go concurrently?

Each *Document instance is not goroutine-safe. Use one Document per goroutine, or protect shared instances with a mutex.

How do I read back field values from a filled form?

Use Field.Value() on any field or type-assert to access type-specific accessors such as CheckboxField.Checked() or ComboBoxField.SelectedIndex().

Can I create a PDF from scratch without an existing template?

Yes. pdf.NewDocument() creates an empty document. Call AddBlankPageFromFormat(pdf.PageFormatA4) to append a blank page, then add content (tables, annotations, etc.) before saving.

What is the difference between `Document.Save` and `Document.WriteTo`?

Save(path string) writes to a file path. WriteTo(w io.Writer) writes to any io.Writer — useful for HTTP responses, buffers, or stream pipelines.