Caution: The documentation you are viewing is
for an older version of Zend Framework.
You can find the documentation of the current version at docs.zendframework.com
Drawing - Zend_Pdf
PDF uses the same geometry as PostScript. It starts from bottom-left corner of page and by default is measured in points (1/72 of an inch).
Page size can be retrieved from a page object:
PDF has a powerful capabilities for colors representation. Zend_Pdf module supports Gray Scale, RGB and CMYK color spaces. Any of them can be used in any place, where Zend_Pdf_Color object is required. Zend_Pdf_Color_GrayScale, Zend_Pdf_Color_Rgb and Zend_Pdf_Color_Cmyk classes provide this functionality:
HTML style colors are also provided with Zend_Pdf_Color_Html class:
All drawing operations can be done in a context of PDF page.
Zend_Pdf_Page class provides a set of drawing primitives:
Text drawing operations also exist in the context of a PDF page. You can draw a single line of text at any position on the page by supplying the x and y coordinates of the baseline. Current font, font size and page fill color are used for text drawing operations (see detailed description below).
Example #1 Draw a string on the page
Example #2 Set font color
By default, text strings are interpreted using the character encoding method of the current locale. if you have a string that uses a different encoding method (such as a UTF-8 string read from a file on disk, or a MacRoman string obtained from a legacy database), you can indicate the character encoding at draw time and Zend_Pdf will handle the conversion for you. You can supply source strings in any encoding method supported by PHP's » iconv() function:
Example #3 Draw a UTF-8-encoded string on the page
Zend_Pdf_Page::drawText() uses the page's current font and font size, which is set with the Zend_Pdf_Page::setFont() method:
PDF documents support PostScript Type 1 and TrueType fonts, as well as two specialized PDF types, Type 3 and composite fonts. There are also 14 standard Type 1 fonts built-in to every PDF viewer: Courier (4 styles), Helvetica (4 styles), Times (4 styles), Symbol, and Zapf Dingbats.
Zend_Pdf currently supports the standard 14 PDF fonts as well as your own custom TrueType fonts. Font objects are obtained via one of two factory methods: Zend_Pdf_Font::fontWithName($fontName) for the standard 14 PDF fonts or Zend_Pdf_Font::fontWithPath($filePath) for custom fonts.
Example #4 Create a standard font
Constants for the standard 14 PDF font names are defined in the Zend_Pdf_Font class:
You can also use any individual TrueType font (which usually has a '.ttf' extension) or an OpenType font ('.otf' extension) if it contains TrueType outlines. Currently unsupported, but planned for a future release are Mac OS X .dfont files and Microsoft TrueType Collection ('.ttc' extension) files.
To use a TrueType font, you must provide the full file path to the font program. If the font cannot be read for some reason, or if it is not a TrueType font, the factory method will throw an exception:
Example #5 Create a TrueType font
By default, custom fonts will be embedded in the resulting PDF document. This allows recipients to view the page as intended, even if they don't have the proper fonts installed on their system. If you are concerned about file size, you can request that the font program not be embedded by passing a 'do not embed' option to the factory method:
Example #6 Create a TrueType font, but do not embed it in the PDF document
If the font program is not embedded but the recipient of the PDF file has the font installed on their system, they will see the document as intended. If they do not have the correct font installed, the PDF viewer application will do its best to synthesize a replacement.
Some fonts have very specific licensing rules which prevent them from being embedded in PDF documents. So you are not caught off-guard by this, if you try to use a font that cannot be embedded, the factory method will throw an exception.
You can still use these fonts, but you must either pass the do not embed flag as described above, or you can simply suppress the exception:
Example #7 Do not throw an exception for fonts that cannot be embedded
This suppression technique is preferred if you allow an end-user to choose their own fonts. Fonts which can be embedded in the PDF document will be; those that cannot, won't.
Font programs can be rather large, some reaching into the tens of megabytes. By default, all embedded fonts are compressed using the Flate compression scheme, resulting in a space savings of 50% on average. If, for some reason, you do not want to compress the font program, you can disable it with an option:
Example #8 Do not compress an embedded font
Finally, when necessary, you can combine the embedding options by using the bitwise OR operator:
Example #9 Combining font embedding options
Standard PDF fonts use several single byte encodings internally (see » PDF Reference, Sixth Edition, version 1.7 Appendix D for details). They are generally equal to Latin1 character set (except Symbol and ZapfDingbats fonts).
Zend_Pdf uses CP1252 (WinLatin1) for drawing text with standard fonts.
Text still can be provided in any other encoding, which must be specified if it differs from a current locale. Only WinLatin1 characters will be actually drawn.
Example #10 Combining font embedding options
Zend_Pdf module provides a possibility to extract fonts from loaded documents.
It may be useful for incremental document updates. Without this functionality you have to attach and possibly embed font into a document each time you want to update it.
Zend_Pdf and Zend_Pdf_Page objects provide special methods to extract all fonts mentioned within a document or a page:
Example #11 Extracting fonts from a loaded document
Example #12 Extracting font from a loaded document by specifying font name
Extracted fonts can be used in the place of any other font with the following limitations:
Extracted font can be used only in the context of the document from which it was extracted.
Possibly embedded font program is actually not extracted. So extracted font can't provide correct font metrics and original font has to be used for text width calculations:
Zend_Pdf_Page class provides drawImage() method to draw image:
Image objects should be created with Zend_Pdf_Image::imageWithPath($filePath) method (JPG, PNG and TIFF images are supported now):
Example #13 Image drawing
Important! JPEG support requires PHP GD extension to be configured.Important! PNG support requires ZLIB extension to be configured to work with Alpha channel images.
Line drawing style is defined by line width, line color and line dashing pattern. All of this parameters can be assigned by Zend_Pdf_Page class methods:
Zend_Pdf_Page::drawRectangle(), Zend_Pdf_Page::drawPolygon(), Zend_Pdf_Page::drawCircle() and Zend_Pdf_Page::drawEllipse() methods take $fillType argument as an optional parameter. It can be:
Zend_Pdf_Page::SHAPE_DRAW_STROKE - stroke shape
Zend_Pdf_Page::SHAPE_DRAW_FILL - only fill shape
Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fill and stroke (default behavior)
Zend_Pdf_Page::drawPolygon() methods also takes an additional parameter $fillMethod:
Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING (default behavior)
PDF reference describes this rule as follows:
The nonzero winding number rule determines whether a given point is inside a path by conceptually drawing a ray from that point to infinity in any direction and then examining the places where a segment of the path crosses the ray. Starting with a count of 0, the rule adds 1 each time a path segment crosses the ray from left to right and subtracts 1 each time a segment crosses from right to left. After counting all the crossings, if the result is 0 then the point is outside the path; otherwise it is inside. Note: The method just described does not specify what to do if a path segment coincides with or is tangent to the chosen ray. Since the direction of the ray is arbitrary, the rule simply chooses a ray that does not encounter such problem intersections. For simple convex paths, the nonzero winding number rule defines the inside and outside as one would intuitively expect. The more interesting cases are those involving complex or self-intersecting paths like the ones shown in Figure 4.10 (in a PDF Reference). For a path consisting of a five-pointed star, drawn with five connected straight line segments intersecting each other, the rule considers the inside to be the entire area enclosed by the star, including the pentagon in the center. For a path composed of two concentric circles, the areas enclosed by both circles are considered to be inside, provided that both are drawn in the same direction. If the circles are drawn in opposite directions, only the "doughnut" shape between them is inside, according to the rule; the "doughnut hole" is outside.
PDF reference describes this rule as follows:
An alternative to the nonzero winding number rule is the even-odd rule. This rule determines the "insideness" of a point by drawing a ray from that point in any direction and simply counting the number of path segments that cross the ray, regardless of direction. If this number is odd, the point is inside; if even, the point is outside. This yields the same results as the nonzero winding number rule for paths with simple shapes, but produces different results for more complex shapes. Figure 4.11 (in a PDF Reference) shows the effects of applying the even-odd rule to complex paths. For the five-pointed star, the rule considers the triangular points to be inside the path, but not the pentagon in the center. For the two concentric circles, only the "doughnut" shape between the two circles is considered inside, regardless of the directions in which the circles are drawn.
PDF page can be rotated before applying any draw operation. It can be done by Zend_Pdf_Page::rotate() method:
Scaling transformation is provided by Zend_Pdf_Page::scale() method:
Coordinate system shifting is performed by Zend_Pdf_Page::translate() method:
Page skewing can be done using Zend_Pdf_Page::skew() method:
At any time page graphics state (current font, font size, line color, fill color, line style, page rotation, clip area) can be saved and then restored. Save operation puts data to a graphics state stack, restore operation retrieves it from there.
There are two methods in Zend_Pdf_Page class for these operations:
PDF and Zend_Pdf module support clipping of draw area. Current clip area limits the regions of the page affected by painting operators. It's a whole page initially.
Zend_Pdf_Page class provides a set of methods for clipping operations.
Zend_Pdf_Style class provides styles functionality.
Styles can be used to store a set of graphic state parameters and apply it to a PDF page by one operation:
Zend_Pdf_Style class provides a set of methods to set or get different graphics state parameters:
Zend_Pdf module supports transparency handling.
Transparency may be set using Zend_Pdf_Page::setAlpha() method: