1# GoFPDF document generator
2
3[](http://unmaintained.tech/)
5[](https://raw.githubusercontent.com/jung-kurt/gofpdf/master/LICENSE)
7[](https://goreportcard.com/report/github.com/jung-kurt/gofpdf)
8[](https://godoc.org/github.com/jung-kurt/gofpdf)
9
10
11
12Package gofpdf implements a PDF document generator with high level
13support for text, drawing and images.
14
15## Features
16
17 - UTF-8 support
18 - Choice of measurement unit, page format and margins
19 - Page header and footer management
20 - Automatic page breaks, line breaks, and text justification
21 - Inclusion of JPEG, PNG, GIF, TIFF and basic path-only SVG images
22 - Colors, gradients and alpha channel transparency
23 - Outline bookmarks
24 - Internal and external links
25 - TrueType, Type1 and encoding support
26 - Page compression
27 - Lines, Bézier curves, arcs, and ellipses
28 - Rotation, scaling, skewing, translation, and mirroring
29 - Clipping
30 - Document protection
31 - Layers
32 - Templates
33 - Barcodes
34 - Charting facility
35 - Import PDFs as templates
36
37gofpdf has no dependencies other than the Go standard library. All tests
38pass on Linux, Mac and Windows platforms.
39
40gofpdf supports UTF-8 TrueType fonts and “right-to-left” languages. Note
41that Chinese, Japanese, and Korean characters may not be included in
42many general purpose fonts. For these languages, a specialized font (for
43example,
44[NotoSansSC](https://github.com/jsntn/webfonts/blob/master/NotoSansSC-Regular.ttf)
45for simplified Chinese) can be used.
46
47Also, support is provided to automatically translate UTF-8 runes to code
48page encodings for languages that have fewer than 256 glyphs.
49
50## We Are Closed
51
52This repository will not be maintained, at least for some unknown
53duration. But it is hoped that gofpdf has a bright future in the open
54source world. Due to Go’s promise of compatibility, gofpdf should
55continue to function without modification for a longer time than would
56be the case with many other languages.
57
58Forks should be based on the [last viable
59commit](https://github.com/jung-kurt/gofpdf/commit/603f56990463f011cb1dbb64ef7f872c1adc009a).
60Tools such as
61[active-forks](https://techgaun.github.io/active-forks/index.html#jung-kurt/gofpdf)
62can be used to select a fork that looks promising for your needs. If a
63particular fork looks like it has taken the lead in attracting
64followers, this README will be updated to point people in that
65direction.
66
67The efforts of all contributors to this project have been deeply
68appreciated. Best wishes to all of you.
69
70## Installation
71
72To install the package on your system, run
73
74``` shell
75go get github.com/jung-kurt/gofpdf
76```
77
78Later, to receive updates, run
79
80``` shell
81go get -u -v github.com/jung-kurt/gofpdf/...
82```
83
84## Quick Start
85
86The following Go code generates a simple PDF file.
87
88``` go
89pdf := gofpdf.New("P", "mm", "A4", "")
90pdf.AddPage()
91pdf.SetFont("Arial", "B", 16)
92pdf.Cell(40, 10, "Hello, world")
93err := pdf.OutputFileAndClose("hello.pdf")
94```
95
96See the functions in the
97[fpdf\_test.go](https://github.com/jung-kurt/gofpdf/blob/master/fpdf_test.go)
98file (shown as examples in this documentation) for more advanced PDF
99examples.
100
101## Errors
102
103If an error occurs in an Fpdf method, an internal error field is set.
104After this occurs, Fpdf method calls typically return without performing
105any operations and the error state is retained. This error management
106scheme facilitates PDF generation since individual method calls do not
107need to be examined for failure; it is generally sufficient to wait
108until after `Output()` is called. For the same reason, if an error
109occurs in the calling application during PDF generation, it may be
110desirable for the application to transfer the error to the Fpdf instance
111by calling the `SetError()` method or the `SetErrorf()` method. At any
112time during the life cycle of the Fpdf instance, the error state can be
113determined with a call to `Ok()` or `Err()`. The error itself can be
114retrieved with a call to `Error()`.
115
116## Conversion Notes
117
118This package is a relatively straightforward translation from the
119original [FPDF](http://www.fpdf.org/) library written in PHP (despite
120the caveat in the introduction to [Effective
121Go](https://golang.org/doc/effective_go.html)). The API names have been
122retained even though the Go idiom would suggest otherwise (for example,
123`pdf.GetX()` is used rather than simply `pdf.X()`). The similarity of
124the two libraries makes the original FPDF website a good source of
125information. It includes a forum and FAQ.
126
127However, some internal changes have been made. Page content is built up
128using buffers (of type bytes.Buffer) rather than repeated string
129concatenation. Errors are handled as explained above rather than
130panicking. Output is generated through an interface of type io.Writer or
131io.WriteCloser. A number of the original PHP methods behave differently
132based on the type of the arguments that are passed to them; in these
133cases additional methods have been exported to provide similar
134functionality. Font definition files are produced in JSON rather than
135PHP.
136
137## Example PDFs
138
139A side effect of running `go test ./...` is the production of a number
140of example PDFs. These can be found in the gofpdf/pdf directory after
141the tests complete.
142
143Please note that these examples run in the context of a test. In order
144run an example as a standalone application, you’ll need to examine
145[fpdf\_test.go](https://github.com/jung-kurt/gofpdf/blob/master/fpdf_test.go)
146for some helper routines, for example `exampleFilename()` and
147`summary()`.
148
149Example PDFs can be compared with reference copies in order to verify
150that they have been generated as expected. This comparison will be
151performed if a PDF with the same name as the example PDF is placed in
152the gofpdf/pdf/reference directory and if the third argument to
153`ComparePDFFiles()` in internal/example/example.go is true. (By default
154it is false.) The routine that summarizes an example will look for this
155file and, if found, will call `ComparePDFFiles()` to check the example
156PDF for equality with its reference PDF. If differences exist between
157the two files they will be printed to standard output and the test will
158fail. If the reference file is missing, the comparison is considered to
159succeed. In order to successfully compare two PDFs, the placement of
160internal resources must be consistent and the internal creation
161timestamps must be the same. To do this, the methods `SetCatalogSort()`
162and `SetCreationDate()` need to be called for both files. This is done
163automatically for all examples.
164
165## Nonstandard Fonts
166
167Nothing special is required to use the standard PDF fonts (courier,
168helvetica, times, zapfdingbats) in your documents other than calling
169`SetFont()`.
170
171You should use `AddUTF8Font()` or `AddUTF8FontFromBytes()` to add a
172TrueType UTF-8 encoded font. Use `RTL()` and `LTR()` methods switch
173between “right-to-left” and “left-to-right” mode.
174
175In order to use a different non-UTF-8 TrueType or Type1 font, you will
176need to generate a font definition file and, if the font will be
177embedded into PDFs, a compressed version of the font file. This is done
178by calling the MakeFont function or using the included makefont command
179line utility. To create the utility, cd into the makefont subdirectory
180and run “go build”. This will produce a standalone executable named
181makefont. Select the appropriate encoding file from the font
182subdirectory and run the command as in the following example.
183
184``` shell
185./makefont --embed --enc=../font/cp1252.map --dst=../font ../font/calligra.ttf
186```
187
188In your PDF generation code, call `AddFont()` to load the font and, as
189with the standard fonts, SetFont() to begin using it. Most examples,
190including the package example, demonstrate this method. Good sources of
191free, open-source fonts include [Google
192Fonts](https://fonts.google.com/) and [DejaVu
193Fonts](http://dejavu-fonts.org/).
194
195## Related Packages
196
197The [draw2d](https://github.com/llgcode/draw2d) package is a two
198dimensional vector graphics library that can generate output in
199different forms. It uses gofpdf for its document production mode.
200
201## Contributing Changes
202
203gofpdf is a global community effort and you are invited to make it even
204better. If you have implemented a new feature or corrected a problem,
205please consider contributing your change to the project. A contribution
206that does not directly pertain to the core functionality of gofpdf
207should be placed in its own directory directly beneath the `contrib`
208directory.
209
210Here are guidelines for making submissions. Your change should
211
212 - be compatible with the MIT License
213 - be properly documented
214 - be formatted with `go fmt`
215 - include an example in
216 [fpdf\_test.go](https://github.com/jung-kurt/gofpdf/blob/master/fpdf_test.go)
217 if appropriate
218 - conform to the standards of [golint](https://github.com/golang/lint)
219 and [go vet](https://golang.org/cmd/vet/), that is, `golint .` and
220 `go vet .` should not generate any warnings
221 - not diminish [test coverage](https://blog.golang.org/cover)
222
223[Pull requests](https://help.github.com/articles/using-pull-requests/)
224are the preferred means of accepting your changes.
225
226## License
227
228gofpdf is released under the MIT License. It is copyrighted by Kurt Jung
229and the contributors acknowledged below.
230
231## Acknowledgments
232
233This package’s code and documentation are closely derived from the
234[FPDF](http://www.fpdf.org/) library created by Olivier Plathey, and a
235number of font and image resources are copied directly from it. Bruno
236Michel has provided valuable assistance with the code. Drawing support
237is adapted from the FPDF geometric figures script by David Hernández
238Sanz. Transparency support is adapted from the FPDF transparency script
239by Martin Hall-May. Support for gradients and clipping is adapted from
240FPDF scripts by Andreas Würmser. Support for outline bookmarks is
241adapted from Olivier Plathey by Manuel Cornes. Layer support is adapted
242from Olivier Plathey. Support for transformations is adapted from the
243FPDF transformation script by Moritz Wagner and Andreas Würmser. PDF
244protection is adapted from the work of Klemen Vodopivec for the FPDF
245product. Lawrence Kesteloot provided code to allow an image’s extent to
246be determined prior to placement. Support for vertical alignment within
247a cell was provided by Stefan Schroeder. Ivan Daniluk generalized the
248font and image loading code to use the Reader interface while
249maintaining backward compatibility. Anthony Starks provided code for the
250Polygon function. Robert Lillack provided the Beziergon function and
251corrected some naming issues with the internal curve function. Claudio
252Felber provided implementations for dashed line drawing and generalized
253font loading. Stani Michiels provided support for multi-segment path
254drawing with smooth line joins, line join styles, enhanced fill modes,
255and has helped greatly with package presentation and tests. Templating
256is adapted by Marcus Downing from the FPDF\_Tpl library created by Jan
257Slabon and Setasign. Jelmer Snoeck contributed packages that generate a
258variety of barcodes and help with registering images on the web. Jelmer
259Snoek and Guillermo Pascual augmented the basic HTML functionality with
260aligned text. Kent Quirk implemented backwards-compatible support for
261reading DPI from images that support it, and for setting DPI manually
262and then having it properly taken into account when calculating image
263size. Paulo Coutinho provided support for static embedded fonts. Dan
264Meyers added support for embedded JavaScript. David Fish added a generic
265alias-replacement function to enable, among other things, table of
266contents functionality. Andy Bakun identified and corrected a problem in
267which the internal catalogs were not sorted stably. Paul Montag added
268encoding and decoding functionality for templates, including images that
269are embedded in templates; this allows templates to be stored
270independently of gofpdf. Paul also added support for page boxes used in
271printing PDF documents. Wojciech Matusiak added supported for word
272spacing. Artem Korotkiy added support of UTF-8 fonts. Dave Barnes added
273support for imported objects and templates. Brigham Thompson added
274support for rounded rectangles. Joe Westcott added underline
275functionality and optimized image storage. Benoit KUGLER contributed
276support for rectangles with corners of unequal radius, modification
277times, and for file attachments and annotations.
278
279## Roadmap
280
281 - Remove all legacy code page font support; use UTF-8 exclusively
282 - Improve test coverage as reported by the coverage tool.
View as plain text