codeberg.org/go-pdf/fpdf@v0.11.1/README.md (about) 1 # GoFPDF document generator 2 3 [](https://codeberg.org/go-pdf/fpdf/releases) 4 [](https://codeberg.org/go-pdf/fpdf/actions) 5 [](https://raw.githubusercontent.com/go-pdf/fpdf/master/LICENSE) 6 [](https://goreportcard.com/report/codeberg.org/go-pdf/fpdf) 7 [](https://godoc.org/codeberg.org/go-pdf/fpdf) 8 9  10 11 Package `go-pdf/fpdf` implements a PDF document generator with high level 12 support for text, drawing and images. 13 14 ## Features 15 16 - UTF-8 support 17 - Choice of measurement unit, page format and margins 18 - Page header and footer management 19 - Automatic page breaks, line breaks, and text justification 20 - Inclusion of JPEG, PNG, GIF, TIFF and basic path-only SVG images 21 - Colors, gradients and alpha channel transparency 22 - Outline bookmarks 23 - Internal and external links 24 - TrueType, Type1 and encoding support 25 - Page compression 26 - Lines, Bézier curves, arcs, and ellipses 27 - Rotation, scaling, skewing, translation, and mirroring 28 - Clipping 29 - Document protection 30 - Layers 31 - Templates 32 - Barcodes 33 - Charting facility 34 - Import PDFs as templates 35 36 gofpdf has no dependencies other than the Go standard library. All tests 37 pass on Linux, Mac and Windows platforms. 38 39 gofpdf supports UTF-8 TrueType fonts and “right-to-left” languages. Note 40 that Chinese, Japanese, and Korean characters may not be included in 41 many general purpose fonts. For these languages, a specialized font (for 42 example, 43 [NotoSansSC](https://github.com/jsntn/webfonts/blob/master/NotoSansSC-Regular.ttf) 44 for simplified Chinese) can be used. 45 46 Also, support is provided to automatically translate UTF-8 runes to code 47 page encodings for languages that have fewer than 256 glyphs. 48 49 ## Installation 50 51 To install the package on your system, run 52 53 ``` shell 54 go get codeberg.org/go-pdf/fpdf 55 ``` 56 57 Later, to receive updates, run 58 59 ``` shell 60 go get -u -v codeberg.org/go-pdf/fpdf/... 61 ``` 62 63 ## Quick Start 64 65 The following Go code generates a simple PDF file. 66 67 ``` go 68 pdf := fpdf.New("P", "mm", "A4", "") 69 pdf.AddPage() 70 pdf.SetFont("Arial", "B", 16) 71 pdf.Cell(40, 10, "Hello, world") 72 err := pdf.OutputFileAndClose("hello.pdf") 73 ``` 74 75 See the functions in the 76 [fpdf\_test.go](https://codeberg.org/go-pdf/fpdf/blob/master/fpdf_test.go) 77 file (shown as examples in this documentation) for more advanced PDF 78 examples. 79 80 ## Errors 81 82 If an error occurs in an Fpdf method, an internal error field is set. 83 After this occurs, Fpdf method calls typically return without performing 84 any operations and the error state is retained. This error management 85 scheme facilitates PDF generation since individual method calls do not 86 need to be examined for failure; it is generally sufficient to wait 87 until after `Output()` is called. For the same reason, if an error 88 occurs in the calling application during PDF generation, it may be 89 desirable for the application to transfer the error to the Fpdf instance 90 by calling the `SetError()` method or the `SetErrorf()` method. At any 91 time during the life cycle of the Fpdf instance, the error state can be 92 determined with a call to `Ok()` or `Err()`. The error itself can be 93 retrieved with a call to `Error()`. 94 95 ## Conversion Notes 96 97 This package is a relatively straightforward translation from the 98 original [FPDF](http://www.fpdf.org/) library written in PHP (despite 99 the caveat in the introduction to [Effective 100 Go](https://golang.org/doc/effective_go.html)). The API names have been 101 retained even though the Go idiom would suggest otherwise (for example, 102 `pdf.GetX()` is used rather than simply `pdf.X()`). The similarity of 103 the two libraries makes the original FPDF website a good source of 104 information. It includes a forum and FAQ. 105 106 However, some internal changes have been made. Page content is built up 107 using buffers (of type bytes.Buffer) rather than repeated string 108 concatenation. Errors are handled as explained above rather than 109 panicking. Output is generated through an interface of type io.Writer or 110 io.WriteCloser. A number of the original PHP methods behave differently 111 based on the type of the arguments that are passed to them; in these 112 cases additional methods have been exported to provide similar 113 functionality. Font definition files are produced in JSON rather than 114 PHP. 115 116 ## Example PDFs 117 118 A side effect of running `go test ./...` is the production of a number 119 of example PDFs. These can be found in the gofpdf/pdf directory after 120 the tests complete. 121 122 Please note that these examples run in the context of a test. In order 123 run an example as a standalone application, you’ll need to examine 124 [fpdf\_test.go](https://codeberg.org/go-pdf/fpdf/blob/master/fpdf_test.go) 125 for some helper routines, for example `exampleFilename()` and 126 `summary()`. 127 128 Example PDFs can be compared with reference copies in order to verify 129 that they have been generated as expected. This comparison will be 130 performed if a PDF with the same name as the example PDF is placed in 131 the fpdf/pdf/reference directory and if the third argument to 132 `ComparePDFFiles()` in internal/example/example.go is true. (By default 133 it is false.) The routine that summarizes an example will look for this 134 file and, if found, will call `ComparePDFFiles()` to check the example 135 PDF for equality with its reference PDF. If differences exist between 136 the two files they will be printed to standard output and the test will 137 fail. If the reference file is missing, the comparison is considered to 138 succeed. In order to successfully compare two PDFs, the placement of 139 internal resources must be consistent and the internal creation 140 timestamps must be the same. To do this, the methods `SetCatalogSort()` 141 and `SetCreationDate()` need to be called for both files. This is done 142 automatically for all examples. 143 144 ## Nonstandard Fonts 145 146 Nothing special is required to use the standard PDF fonts (courier, 147 helvetica, times, zapfdingbats) in your documents other than calling 148 `SetFont()`. 149 150 You should use `AddUTF8Font()` or `AddUTF8FontFromBytes()` to add a 151 TrueType UTF-8 encoded font. Use `RTL()` and `LTR()` methods switch 152 between “right-to-left” and “left-to-right” mode. 153 154 In order to use a different non-UTF-8 TrueType or Type1 font, you will 155 need to generate a font definition file and, if the font will be 156 embedded into PDFs, a compressed version of the font file. This is done 157 by calling the MakeFont function or using the included makefont command 158 line utility. To create the utility, cd into the makefont subdirectory 159 and run “go build”. This will produce a standalone executable named 160 makefont. Select the appropriate encoding file from the font 161 subdirectory and run the command as in the following example. 162 163 ``` shell 164 ./makefont --embed --enc=../font/cp1252.map --dst=../font ../font/calligra.ttf 165 ``` 166 167 In your PDF generation code, call `AddFont()` to load the font and, as 168 with the standard fonts, SetFont() to begin using it. Most examples, 169 including the package example, demonstrate this method. Good sources of 170 free, open-source fonts include [Google 171 Fonts](https://fonts.google.com/) and [DejaVu 172 Fonts](http://dejavu-fonts.org/). 173 174 ## Related Packages 175 176 The [draw2d](https://github.com/llgcode/draw2d) package is a two 177 dimensional vector graphics library that can generate output in 178 different forms. It uses `go-pdf/fpdf` for its document production mode. 179 180 ## Contributing Changes 181 182 `go-pdf/fpdf` is a global community effort and you are invited to make it even 183 better. If you have implemented a new feature or corrected a problem, 184 please consider contributing your change to the project. A contribution 185 that does not directly pertain to the core functionality of `go-pdf/fpdf` 186 should be placed in its own directory directly beneath the `contrib` 187 directory. 188 189 Here are guidelines for making submissions. Your change should 190 191 - be compatible with the MIT License 192 - be properly documented 193 - be formatted with `go fmt` 194 - include an example in 195 [fpdf\_test.go](https://codeberg.org/go-pdf/fpdf/blob/master/fpdf_test.go) 196 if appropriate 197 - conform to the standards of [golint](https://github.com/golang/lint) 198 and [go vet](https://golang.org/cmd/vet/), that is, `golint .` and 199 `go vet .` should not generate any warnings 200 - not diminish [test coverage](https://blog.golang.org/cover) 201 202 [Pull requests](https://help.github.com/articles/using-pull-requests/) 203 are the preferred means of accepting your changes. 204 205 ## License 206 207 `go-pdf/fpdf` is released under the MIT License. It is copyrighted by Kurt Jung and the contributors acknowledged below. 208 209 ## Acknowledgments 210 211 Thank you to Kurt Jung who originally wrote [gofpdf](https://github.com/jung-kurt/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.