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