Class FPDF - Stefanius67/XFPDF GitHub Wiki
Full name: \OPlathey\FPDF\FPDF
Based on version 1.82 of FPDF.php, extended by
- namespace to include through autoloader
- PHP 7.4 typehints
- phpDoc comments
See Also:
Method | Description |
---|---|
__construct | This is the class constructor. |
acceptPageBreak | Whenever a page break condition is met, the method is called, and the break is issued or not depending on the returned value. |
addFont | Imports a TrueType, OpenType or Type1 font and makes it available. |
addLink | Creates a new internal link and returns its identifier. |
addPage | Adds a new page to the document. |
aliasNbPages | Defines an alias for the total number of pages. It will be substituted as the document is closed. |
bookmark | Set bookmark at current position. |
cell | Prints a cell (rectangular area) with optional borders, background color and character string. |
close | Terminates the PDF document. |
error | This method is automatically called in case of a fatal error. |
footer | This method is used to render the page footer. |
getPageBreakTrigger | Get the trigger for autopagebreak |
getPageHeight | Get current page height. |
getPageWidth | Get current page width. |
getStringWidth | Returns the length of a string in user unit for current Font. |
getX | Get current x position. |
getY | Get current Y position. |
header | This method is used to render the page header. |
image | Puts an image. |
line | Draws a line between two points. |
link | Puts a link on a rectangular area of the page. |
ln | Performs a line break. |
multiCell | This method allows printing text with line breaks. |
output | Send the document to a given destination: browser, file or string. |
pageNo | Returns the current page number. |
rect | Outputs a rectangle. |
setAuthor | Defines the author of the document. |
setAutoPageBreak | Enables or disables the automatic page breaking mode. |
setCompression | Activates or deactivates page compression. |
setCreator | Defines the creator of the document. This is typically the name of the application that generates the PDF. |
setDisplayMode | Defines the way the document is to be displayed by the viewer. |
setDrawColor | Defines the color used for all drawing operations (lines, rectangles and cell borders). |
setFillColor | Defines the color used for all filling operations (filled rectangles and cell backgrounds). |
setFont | Sets the font used to print character strings. |
setFontSize | Defines the size of the current font. |
setKeywords | Associates keywords with the document, generally in the form 'keyword1 keyword2 ...'. |
setLeftMargin | Defines the left margin. |
setLineWidth | Defines the line width. |
setLink | Defines the page and position a link points to. |
setMargins | Defines the left, top and right margins. |
setRightMargin | Defines the right margin. |
setSubject | Defines the subject of the document. |
setTextColor | Defines the color used for text. |
setTitle | Defines the title of the document. |
setTopMargin | Defines the top margin. |
setX | Set new X position. |
setXY | Set new X and Y position. |
setY | Set new Y position and optionally moves the current X-position back to the left margin. |
text | Prints a character string. |
write | This method prints text from the current position. |
This is the class constructor.
public FPDF::__construct(string $orientation = 'P', string $unit = 'mm', string|array $size = 'A4')
It allows to set up the page size, the orientation and the unit of measure used in all methods (except for font sizes).
Parameters:
Parameter | Type | Description |
---|---|---|
orientation |
string | Default page orientation. Possible values are (case insensitive):
|
unit |
string | User unit. Possible values are:
This is a very common unit in typography; font sizes are expressed in that unit. Default value is 'mm'. |
size |
string | array | The size used for pages. It can be either one of the following values (case insensitive):
Default value is 'A4'. |
Whenever a page break condition is met, the method is called, and the break is issued or not depending on the returned value.
public FPDF::acceptPageBreak() : bool
The default implementation returns a value according to the mode selected by
SetAutoPageBreak().
This method is called automatically and should not be called directly by the application.
For usage in derived classes see example at http://www.fpdf.org/en/doc/acceptpagebreak.htm.
Return Type: bool
See Also:
Imports a TrueType, OpenType or Type1 font and makes it available.
public FPDF::addFont(string $family, string $style = '', string $file = '') : void
It is necessary to generate a font definition file first with the MakeFont utility. The definition file (and the font file itself when embedding) must be present in the font directory. If it is not found, the error "Could not include font definition file" is raised.
Parameters:
Parameter | Type | Description |
---|---|---|
family |
string | Font family. The name can be chosen arbitrarily. If it is a standard family name, it will override the corresponding font. |
style |
string | Font style. Possible values are (case insensitive):
|
file |
string | The font definition file. By default, the name is built from the family and style, in lower case with no space. |
Creates a new internal link and returns its identifier.
public FPDF::addLink() : int
An internal link is a clickable area which directs to another place within the document. The identifier can then be passed to Cell(), Write(), Image() or Link(). The destination is defined with SetLink().
Return Type: int
Adds a new page to the document.
public FPDF::addPage(string $orientation = '', string|array $size = '', int $rotation) : void
If a page is already present, the Footer() method is called first to output the footer. Then the page is added, the current position set to the top-left corner according to the left and top margins, and Header() is called to display the header. The font which was set before calling is automatically restored. There is no need to call SetFont() again if you want to continue with the same font. The same is true for colors and line width. The origin of the Y-position system is at the top-left corner and increasing Y-positions go downwards.
Parameters:
Parameter | Type | Description |
---|---|---|
orientation |
string | Default page orientation. Possible values are (case insensitive):
|
size |
string | array | The size used for pages. It can be either one of the following values (case insensitive):
Default value is 'A4'. |
rotation |
int | Angle by which to rotate the page. It must be a multiple of 90; positive values mean clockwise rotation. The default value is 0. |
Defines an alias for the total number of pages. It will be substituted as the document is closed.
public FPDF::aliasNbPages(string $alias = '{nb}') : void
Parameters:
Parameter | Type | Description |
---|---|---|
alias |
string | The alias. Default value: {nb}. |
Set bookmark at current position.
public FPDF::bookmark(string $txt, bool $isUTF8 = true, int $level, int $y) : void
from FPDF.org extension to create Bookmarks
Parameters:
Parameter | Type | Description |
---|---|---|
txt |
string | |
isUTF8 |
bool | |
level |
int | |
y |
int |
Prints a cell (rectangular area) with optional borders, background color and character string.
public FPDF::cell(float $w, float $h, string $txt = '', int|string $border, float $ln, string $align = '', bool $fill = false, string|int $link = '') : void
The upper-left corner of the cell corresponds to the current position. The text can be aligned or centered. After the call, the current position moves to the right or to the next line. It is possible to put a link on the text. If automatic page breaking is enabled and the cell goes beyond the limit, a page break is done before outputting.
Parameters:
Parameter | Type | Description |
---|---|---|
w |
float | Cell width. If 0, the cell extends up to the right margin. |
h |
float | Cell height. Default value: 0. |
txt |
string | String to print. Default value: empty string. |
border |
int | string | Indicates if borders must be drawn around the cell. The value can be either a number:
|
ln |
float | Indicates where the current position should go after the call. Possible values are:
Default value: 0. |
align |
string | Allows to center or align the text. Possible values are:
|
fill |
bool | Indicates if the cell background must be painted (true) or transparent (false). If set to true, current FillColor is used for the background. Default value: false. |
link |
string | int | URL or identifier for internal link created by AddLink(). |
Terminates the PDF document.
public FPDF::close() : void
It is not necessary to call this method explicitly because Output() does it automatically. If the document contains no page, AddPage() is called to prevent from getting an invalid document.
This method is automatically called in case of a fatal error.
public FPDF::error(string $msg) : void
It simply throws an exception with the provided message. An inherited class may override it to customize the error handling but the method should never return, otherwise the resulting document would probably be invalid.
Parameters:
Parameter | Type | Description |
---|---|---|
msg |
string | The error message. |
This method is used to render the page footer.
public FPDF::footer() : void
It is automatically called by AddPage() and Close() and should not be called directly by the application. The implementation in FPDF is empty, so you have to subclass it and override the method if you want a specific processing.
Get the trigger for autopagebreak
public FPDF::getPageBreakTrigger() : float
Return Type: float
Get current page height.
public FPDF::getPageHeight() : float
Return Type: float
Get current page width.
public FPDF::getPageWidth() : float
Return Type: float
Returns the length of a string in user unit for current Font.
public FPDF::getStringWidth(string $s) : float
A font must be selected.
Parameters:
Parameter | Type | Description |
---|---|---|
s |
string | The string whose length is to be computed. |
Return Type: float
Get current x position.
public FPDF::getX() : float
Return Type: float
Get current Y position.
public FPDF::getY() : float
Return Type: float
This method is used to render the page header.
public FPDF::header() : void
It is automatically called by AddPage() and should not be called directly by the application. The implementation in FPDF is empty, so you have to subclass it and override the method if you want a specific processing.
Puts an image.
public FPDF::image(string $file, float $x = null, float $y = null, float $w, float $h, string $type = '', string|int $link = '') : void
The size it will take on the page can be specified in different ways:
- explicit width and height (expressed in user unit or dpi)
- one explicit dimension, the other being calculated automatically in order to keep the original proportions
- no explicit dimension, in which case the image is put at 96 dpi
For JPEGs, all flavors are allowed:
- gray scales
- true colors (24 bits)
- CMYK (32 bits)
- gray scales on at most 8 bits (256 levels)
- indexed colors
- true colors (24 bits)
Transparency is supported.
The format can be specified explicitly or inferred from the file extension.
It is possible to put a link on the image.
Remark: if an image is used several times, only one copy is embedded in the file.
Parameters:
Parameter | Type | Description |
---|---|---|
file |
string | Path or URL of the image. |
x |
float | X-position of the upper-left corner. If not specified or equal to null, the current X-position is used. |
y |
float | Y-position of the upper-left corner. If not specified or equal to null, the current Y-position is used; moreover, a page break is triggered first if necessary (in case automatic page breaking is enabled) and, after the call, the current Y-position is moved to the bottom of the image. |
w |
float | Width of the image in the page. There are three cases:
|
h |
float | Height of the image in the page. There are three cases:
|
type |
string | Image format. Possible values are (case insensitive):
|
link |
string | int | URL or identifier for internal link created by AddLink(). |
Draws a line between two points.
public FPDF::line(float $x1, float $y1, float $x2, float $y2) : void
The X/Y-positions refer to the top left corner of the page. Set margins are NOT taken into account.
Parameters:
Parameter | Type | Description |
---|---|---|
x1 |
float | X-position upper left corner |
y1 |
float | Y-position upper left corner |
x2 |
float | X-position lower right corner |
y2 |
float | Y-position lower right corner |
Puts a link on a rectangular area of the page.
public FPDF::link(float $x, float $y, float $w, float $h, string|int $link) : void
Text or image links are generally put via Cell(), Write() or Image(), but this method can be useful for instance to define a clickable area inside an image. Target can be an external URL or an internal link ID created and specified by AddLink()/SetLink()
Parameters:
Parameter | Type | Description |
---|---|---|
x |
float | X-position |
y |
float | Y-position |
w |
float | Width |
h |
float | Height |
link |
string | int | URL or link-ID |
Performs a line break.
public FPDF::ln(float $h = null) : void
The current X-position goes back to the left margin and the Y-position increases by the amount passed in parameter.
Parameters:
Parameter | Type | Description |
---|---|---|
h |
float | The height of the break. By default, the value equals the height of the last printed cell. |
This method allows printing text with line breaks.
public FPDF::multiCell(float $w, float $h, string $txt, int|string $border, string $align = 'J', bool $fill = false) : void
They can be automatic (as soon as the text reaches the right border of the cell) or explicit (via the \n character). As many cells as necessary are output, one below the other. Text can be aligned, centered or justified. The cell block can be framed and the background painted.
Parameters:
Parameter | Type | Description |
---|---|---|
w |
float | Cell width. If 0, the cell extends up to the right margin. |
h |
float | Cell height. Default value: 0. |
txt |
string | String to print. Default value: empty string. |
border |
int | string | Indicates if borders must be drawn around the cell. The value can be either a number:
|
align |
string | Allows to center or align the text. Possible values are:
|
fill |
bool | Indicates if the cell background must be painted (true) or transparent (false). If set to true, current FillColor is used for the background. Default value: false. |
Send the document to a given destination: browser, file or string.
public FPDF::output(string $dest = '', string $name = '', bool $isUTF8 = true) : string
In the case of a browser, the PDF viewer may be used or a download may be forced. The method first calls Close() if necessary to terminate the document.
Parameters:
Parameter | Type | Description |
---|---|---|
dest |
string | Destination where to send the document. It can be one of the following:
|
name |
string | The name of the file. It is ignored in case of destination 'S'. The default value is doc.pdf. |
isUTF8 |
bool | Indicates if name is encoded in ISO-8859-1 (false) or UTF-8 (true). Only used for destinations I and D. The default value is true. |
Return Type: string
Returns the current page number.
public FPDF::pageNo() : int
Return Type: int
Outputs a rectangle.
public FPDF::rect(float $x, float $y, float $w, float $h, string $style = '') : void
It can be drawn (border only), filled (with no border) or both. The X/Y-position refer to the top left corner of the page. Set margins are NOT taken into account.
Parameters:
Parameter | Type | Description |
---|---|---|
x |
float | X-position upper left corner |
y |
float | Y-position upper left corner |
w |
float | Width |
h |
float | Height |
style |
string | Style of rendering. Possible values are:
|
Defines the author of the document.
public FPDF::setAuthor(string $author, bool $isUTF8 = true) : void
Parameters:
Parameter | Type | Description |
---|---|---|
author |
string | |
isUTF8 |
bool | Indicates if the string is encoded in ISO-8859-1 (false) or UTF-8 (true). Default value: true. |
Enables or disables the automatic page breaking mode.
public FPDF::setAutoPageBreak(bool $auto, float $margin) : void
When enabling, the second parameter is the distance from the bottom of the page that defines the triggering limit. By default, the mode is on and the margin is 2 cm.
Parameters:
Parameter | Type | Description |
---|---|---|
auto |
bool | indicating if mode should be on or off. |
margin |
float | Distance from the bottom of the page. |
Activates or deactivates page compression.
public FPDF::setCompression(bool $compress) : void
When activated, the internal representation of each page is compressed, which leads to
a compression ratio of about 2 for the resulting document.
Compression is on by default.
Note: the Zlib extension is required for this feature. If not present, compression will be turned off.
Parameters:
Parameter | Type | Description |
---|---|---|
compress |
bool |
Defines the creator of the document. This is typically the name of the application that generates the PDF.
public FPDF::setCreator(string $creator, bool $isUTF8 = true) : void
Parameters:
Parameter | Type | Description |
---|---|---|
creator |
string | |
isUTF8 |
bool | Indicates if the string is encoded in ISO-8859-1 (false) or UTF-8 (true). Default value: true. |
Defines the way the document is to be displayed by the viewer.
public FPDF::setDisplayMode(string|float $zoom, string $layout = 'default') : void
The zoom level can be set:
pages can be displayed
- entirely on screen
- occupy the full width of the window
- use real size
- be scaled by a specific zooming factor
- or use viewer default (configured in the Preferences menu of Adobe Reader).
- single at once
- continuous display
- two columns
- or viewer default.
Parameters:
Parameter | Type | Description |
---|---|---|
zoom |
string | float | The zoom to use. It can be one of the following string values:
|
layout |
string | The page layout. Possible values are:
|
Defines the color used for all drawing operations (lines, rectangles and cell borders).
public FPDF::setDrawColor(int $r, int $g = null, int $b = null) : void
It can be expressed in RGB components or gray scale. The method can be called before the first page is created and the value is retained from page to page.
Parameters:
Parameter | Type | Description |
---|---|---|
r |
int | If g and b are given, red component; if not, indicates the gray level. Value between 0 and 255. |
g |
int | Green component (between 0 and 255). |
b |
int | Blue component (between 0 and 255). |
Defines the color used for all filling operations (filled rectangles and cell backgrounds).
public FPDF::setFillColor(int $r, int $g = null, int $b = null) : void
It can be expressed in RGB components or gray scale. The method can be called before the first page is created and the value is retained from page to page.
Parameters:
Parameter | Type | Description |
---|---|---|
r |
int | If g and b are given, red component; if not, indicates the gray level. Value between 0 and 255. |
g |
int | Green component (between 0 and 255). |
b |
int | Blue component (between 0 and 255). |
Sets the font used to print character strings.
public FPDF::setFont(string $family, string $style = '', float $size) : void
It is mandatory to call this method at least once before printing text or the
resulting document would not be valid.
The font can be either a standard one or a font added via the AddFont() method.
Standard fonts use the Windows encoding cp1252 (Western Europe).
The method can be called before the first page is created and the font is kept from page to page.
If you just wish to change the current font size, it is simpler to call SetFontSize().
Note:
the font definition files must be accessible.
They are searched successively in:
- The directory defined by the FPDF_FONTPATH constant (if this constant is defined)
- The 'font' directory located in the same directory as fpdf.php (if it exists)
- The directories accessible through include()
Parameters:
Parameter | Type | Description |
---|---|---|
family |
string | Family font. It can be either a name defined by AddFont() or one of the standard families (case insensitive):
|
style |
string | Font style. ossible values are (case insensitive):
|
size |
float | Font size in points. The default value is the current size. If no size has been specified since the beginning of the document, the value taken is 12. |
Defines the size of the current font.
public FPDF::setFontSize(float $size) : void
Parameters:
Parameter | Type | Description |
---|---|---|
size |
float | The size (in points). |
Associates keywords with the document, generally in the form 'keyword1 keyword2 ...'.
public FPDF::setKeywords(string $keywords, bool $isUTF8 = true) : void
Parameters:
Parameter | Type | Description |
---|---|---|
keywords |
string | |
isUTF8 |
bool | Indicates if the string is encoded in ISO-8859-1 (false) or UTF-8 (true). Default value: true. |
Defines the left margin.
public FPDF::setLeftMargin(float $margin) : void
The method can be called before creating the first page. If the current X-position gets out of page, it is brought back to the margin.
Parameters:
Parameter | Type | Description |
---|---|---|
margin |
float | Left margin. |
Defines the line width.
public FPDF::setLineWidth(float $width) : void
By default, the value equals 0.2 mm. The method can be called before the first page is created and the value is retained from page to page.
Parameters:
Parameter | Type | Description |
---|---|---|
width |
float |
Defines the page and position a link points to.
public FPDF::setLink(int $link, float $y, int $page = -1) : void
Parameters:
Parameter | Type | Description |
---|---|---|
link |
int | The link identifier created by AddLink(). |
y |
float | Y-position of target position; -1 indicates the current position. The default value is 0 (top of page). |
page |
int | Number of target page; -1 indicates the current page. This is the default value. |
Defines the left, top and right margins.
public FPDF::setMargins(float $left, float $top, float $right = null) : void
By default, they equal 1 cm. Call this method to change them.
Parameters:
Parameter | Type | Description |
---|---|---|
left |
float | Left margin. |
top |
float | Top margin. |
right |
float | Right margin. Default value is the left one. |
Defines the right margin.
public FPDF::setRightMargin(float $margin) : void
The method can be called before creating the first page.
Parameters:
Parameter | Type | Description |
---|---|---|
margin |
float |
Defines the subject of the document.
public FPDF::setSubject(string $subject, bool $isUTF8 = true) : void
Parameters:
Parameter | Type | Description |
---|---|---|
subject |
string | |
isUTF8 |
bool | Indicates if the string is encoded in ISO-8859-1 (false) or UTF-8 (true). Default value: true. |
Defines the color used for text.
public FPDF::setTextColor(int $r, int $g = null, int $b = null) : void
It can be expressed in RGB components or gray scale. The method can be called before the first page is created and the value is retained from page to page.
Parameters:
Parameter | Type | Description |
---|---|---|
r |
int | If g and b are given, red component; if not, indicates the gray level. Value between 0 and 255. |
g |
int | Green component (between 0 and 255). |
b |
int | Blue component (between 0 and 255). |
Defines the title of the document.
public FPDF::setTitle(string $title, bool $isUTF8 = true) : void
Parameters:
Parameter | Type | Description |
---|---|---|
title |
string | The title. |
isUTF8 |
bool | Indicates if the string is encoded in ISO-8859-1 (false) or UTF-8 (true). Default value: true. |
Defines the top margin.
public FPDF::setTopMargin(float $margin) : void
The method can be called before creating the first page.
Parameters:
Parameter | Type | Description |
---|---|---|
margin |
float |
Set new X position.
public FPDF::setX(float $x) : void
If the passed value is negative, it is relative to the right of the page.
Parameters:
Parameter | Type | Description |
---|---|---|
x |
float |
Set new X and Y position.
public FPDF::setXY(float $x, float $y) : void
If the passed values are negative, they are relative respectively to the right and bottom of the page.
Parameters:
Parameter | Type | Description |
---|---|---|
x |
float | |
y |
float |
Set new Y position and optionally moves the current X-position back to the left margin.
public FPDF::setY(float $y, bool $resetX = true) : void
If the passed value is negative, it is relative to the bottom of the page.
Parameters:
Parameter | Type | Description |
---|---|---|
y |
float | |
resetX |
bool |
Prints a character string.
public FPDF::text(float $x, float $y, string $txt) : void
The origin is on the left of the first character, on the baseline. This method allows to place a string precisely on the page, but it is usually easier to use Cell(), MultiCell() or Write() which are the standard methods to print text.
Parameters:
Parameter | Type | Description |
---|---|---|
x |
float | X-position |
y |
float | Y-position |
txt |
string | String to print. |
This method prints text from the current position.
public FPDF::write(float $h, string $txt, string|int $link = '') : void
When the right margin is reached (or the \n character is met) a line break occurs and text continues from the left margin. Upon method exit, the current position is left just at the end of the text. It is possible to put a link on the text.
Parameters:
Parameter | Type | Description |
---|---|---|
h |
float | Line height. |
txt |
string | String to print. |
link |
string | int | URL or identifier for internal link created by AddLink(). |