1# GoFPDF document generator 2 3[![No Maintenance 4Intended](http://unmaintained.tech/badge.svg)](http://unmaintained.tech/) 5[![MIT 6licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/jung-kurt/gofpdf/master/LICENSE) 7[![Report](https://goreportcard.com/badge/github.com/jung-kurt/gofpdf)](https://goreportcard.com/report/github.com/jung-kurt/gofpdf) 8[![GoDoc](https://img.shields.io/badge/godoc-GoFPDF-blue.svg)](https://godoc.org/github.com/jung-kurt/gofpdf) 9 10![](https://github.com/jung-kurt/gofpdf/raw/master/image/logo_gofpdf.jpg?raw=true) 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. 283