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