11.5. Drawing.

11.5.1. Geometry.

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:

$width  = $pdfPage->getWidth();
$height = $pdfPage->getHeight();
            

11.5.2. Colors.

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:

// $grayLevel (float number). 0.0 (black) - 1.0 (white)
$color1 = new Zend_Pdf_Color_GrayScale($grayLevel);

// $r, $g, $b (float numbers). 0.0 (minimum intensity) - 1.0 (maximum intensity)
$color2 = new Zend_Pdf_Color_RGB($r, $g, $b);

// $c, $m, $y, $k (float numbers). 0.0 (minimum intensity) - 1.0 (maximum intensity)
$color3 = new Zend_Pdf_Color_CMYK($c, $m, $y, $k);
            

11.5.3. Shape Drawing.

All drawing operations can be done in a context of PDF page.

Zend_Pdf_Page class provides a set of drawing primitives:

/**
 * Draw a line from x1,y1 to x2,y2.
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 */
public function drawLine($x1, $y1, $x2, $y2);
            

/**
 * Draw a rectangle.
 *
 * Fill types:
 * Zend_Pdf_Const::SHAPEDRAW_FILLNSTROKE - fill rectangle and stroke (default)
 * Zend_Pdf_Const::SHAPEDRAW_STROKE      - stroke rectangle
 * Zend_Pdf_Const::SHAPEDRAW_FILL        - fill rectangle
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param integer $fillType
 */
public function drawRectangle($x1, $y1, $x2, $y2, $fillType = Zend_Pdf_Const::SHAPEDRAW_FILLNSTROKE);
            

/**
 * Draw a polygon.
 *
 * If $fillType is Zend_Pdf_Const::SHAPEDRAW_FILLNSTROKE or Zend_Pdf_Const::SHAPEDRAW_FILL,
 * then polygon is automatically closed.
 * See detailed description of these methods in a PDF documentation
 * (section 4.4.2 Path painting Operators, Filling)
 *
 * @param array $x  - array of float (the X co-ordinates of the vertices)
 * @param array $y  - array of float (the Y co-ordinates of the vertices)
 * @param integer $fillType
 * @param integer $fillMethod
 */
public function drawPolygon($x, $y,
                            $fillType = Zend_Pdf_Const::SHAPEDRAW_FILLNSTROKE,
                            $fillMethod = Zend_Pdf_Const::FILLMETHOD_NONZEROWINDING);
            

/**
 * Draw a circle centered on x, y with a radius of radius.
 *
 * Angles are specified in radians
 *
 * Method signatures:
 * drawCircle($x, $y, $radius);
 * drawCircle($x, $y, $radius, $fillType);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle, $fillType);
 *
 *
 * It's not a really circle, because PDF supports only cubic Bezier curves.
 * But very good approximation.
 * It differs from a real circle on a maximum 0.00026 radiuses
 * (at PI/8, 3*PI/8, 5*PI/8, 7*PI/8, 9*PI/8, 11*PI/8, 13*PI/8 and 15*PI/8 angles).
 * At 0, PI/4, PI/2, 3*PI/4, PI, 5*PI/4, 3*PI/2 and 7*PI/4 it's exactly a tangent to a circle.
 *
 * @param float $x
 * @param float $y
 * @param float $radius
 * @param mixed $param4
 * @param mixed $param5
 * @param mixed $param6
 */
public function  drawCircle($x, $y, $radius, $param4 = null, $param5 = null, $param6 = null);
            

/**
 * Draw an ellipse inside the specified rectangle.
 *
 * Method signatures:
 * drawEllipse($x1, $y1, $x2, $y2);
 * drawEllipse($x1, $y1, $x2, $y2, $fillType);
 * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);
 * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle, $fillType);
 *
 * Angles are specified in radians
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param mixed $param5
 * @param mixed $param6
 * @param mixed $param7
 */
public function drawEllipse($x1, $y1, $x2, $y2, $param5 = null, $param6 = null, $param7 = null);
            

11.5.4. Text Drawing.

Text drawing operations are also exist in a context of PDF page:

/**
 * Draw a line of text at the specified position.
 *
 * @param string $text
 * @param float $x
 * @param float $y
 * @throws Zend_Pdf_Exception
 */
public function drawText($text, $x, $y );
            

Current font and current font size are used for text drawing operations. See detailed description below.

11.5.5. Using fonts.

Zend_Pdf_Page::drawText() method uses current font, which can be assigned by Zend_Pdf_Page::setFont() method:

/**
 * Set current font.
 *
 * @param Zend_Pdf_Font $font
 * @param float $fontSize
 */
public function setFont(Zend_Pdf_Font $font, $fontSize);
            

PDF supports Type1, TrueType, Type3 and composite fonts. There are also 14 standard Type1 fonts provided by PDF. Zend_Pdf module provides only these standard fonts now. They can be obtained by using Zend_Pdf_Font_Standard class. Concrete font is specified as a constructor argument:

Exemplo 11.5. Create standard font.

<?php
...
// Create new font
$font = new Zend_Pdf_Font_Standard(Zend_Pdf_Const::FONT_HELVETICA);

// Apply font
$pdfPage->setFont($font, 36);
...
?>
            

Font constants for 14 standard fonts are defined within Zend_Pdf_Const class:

  • Zend_Pdf_Const::FONT_TIMES_ROMAN

  • Zend_Pdf_Const::FONT_TIMES_BOLD

  • Zend_Pdf_Const::FONT_TIMES_ITALIC

  • Zend_Pdf_Const::FONT_TIMES_BOLDITALIC

  • Zend_Pdf_Const::FONT_HELVETICA

  • Zend_Pdf_Const::FONT_HELVETICA_BOLD

  • Zend_Pdf_Const::FONT_HELVETICA_ITALIC

  • Zend_Pdf_Const::FONT_HELVETICA_BOLDITALIC

  • Zend_Pdf_Const::FONT_COURIER

  • Zend_Pdf_Const::FONT_COURIER_BOLD

  • Zend_Pdf_Const::FONT_COURIER_ITALIC

  • Zend_Pdf_Const::FONT_COURIER_BOLDITALIC

  • Zend_Pdf_Const::FONT_SYMBOL

  • Zend_Pdf_Const::FONT_ZAPFDINGBATS

11.5.6. Image Drawing.

Zend_Pdf_Page class provides drawImage() method to draw image:

/**
 * Draw an image at the specified position on the page.
 *
 * @param Zend_Pdf_Image $image
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 */
public function drawImage(Zend_Pdf_Image $image, $x1, $y1, $x2, $y2);
            

Image objects are represented by descendants of Zend_Pdf_Image class.

JPG, PNG and TIFF images are supported now:

Exemplo 11.6. Image drawing.

<?php
...
//Create image object directly (choose one)
$image = new Zend_Pdf_Image_JPEG('my_image.jpg');
$image = new Zend_Pdf_Image_TIFF('my_image.tiff');
$image = new Zend_Pdf_Image_PNG('my_image.png');

//or use the Zend_Pdf_ImageFactory to load the appropriate type
$image = Zend_Pdf_ImageFactory::factory('my_image.jpg');

$pdfPage->drawImage($image, 100, 100, 400, 300);
...
?>
            

Important! Zend_Pdf_Image_JPEG class requires PHP GD extension to be configured. Important! Zend_Pdf_Image_PNG class requires ZLIB extension to be configured to work with Alpha channel images.

Refer to the PHP documentation for detailed information (http://www.php.net/manual/en/ref.image.php). (http://www.php.net/manual/en/ref.zlib.php).

11.5.7. Line drawing style.

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:

/** Set line color. */
public function setLineColor(Zend_Pdf_Color $color);

/** Set line width. */
public function setLineWidth(float $width);

/**
 * Set line dashing pattern.
 *
 * Pattern is an array of floats: array(on_length, off_length, on_length, off_length, ...)
 * Phase is shift from the beginning of line.
 *
 * @param array $pattern
 * @param array $phase
 */
public function setLineDashingPattern($pattern, $phase = 0);
            

11.5.8. Fill style.

Zend_Pdf_Page::drawRectangle(), Zend_Pdf_Page::drawPoligon(), Zend_Pdf_Page::drawCircle() and Zend_Pdf_Page::drawEllipse() methods take $fillType argument as an optional parameter. It can be:

  • Zend_Pdf_Const::SHAPEDRAW_STROKE - stroke shape

  • Zend_Pdf_Const::SHAPEDRAW_FILL - only fill shape

  • Zend_Pdf_Const::SHAPEDRAW_FILLNSTROKE - fill and stroke (default behavior)

Zend_Pdf_Page::drawPoligon() methods also takes an additional parameter $fillMethod:

  • Zend_Pdf_Const::FILLMETHOD_NONZEROWINDING (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.

  • Zend_Pdf_Const::FILLMETHOD_EVENODD

    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.

11.5.9. Rotations.

PDF page can be rotated before applying any draw operation. It can be done by Zend_Pdf_Page::rotate() method:

/**
 * Rotate the page around ($x, $y) point by specified angle (in radians).
 *
 * @param float $angle
 */
public function rotate($x, $y, $angle);
            

11.5.10. Save/restore graphics state.

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 to methods in Zend_Pdf_Page class for these operations:

/**
 * Save the graphics state of this page.
 * This takes a snapshot of the currently applied style, position, clipping area and
 * any rotation/translation/scaling that has been applied.
 */
public function saveGS();

/**
 * Restore the graphics state that was saved with the last call to saveGS().
 */
public function restoreGS();
            

11.5.11. Clipping draw area.

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.

/**
 * Intersect current clipping area with a rectangle.
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 */
public function clipRectangle($x1, $y1, $x2, $y2);
            

/**
 * Intersect current clipping area with a polygon.
 *
 * @param array $x  - array of float (the X co-ordinates of the vertices)
 * @param array $y  - array of float (the Y co-ordinates of the vertices)
 * @param integer $fillMethod
 */
public function clipPolygon($x, $y, $fillMethod = Zend_Pdf_Const::FILLMETHOD_NONZEROWINDING);
            

/**
 * Intersect current clipping area with a circle.
 *
 * @param float $x
 * @param float $y
 * @param float $radius
 * @param float $startAngle
 * @param float $endAngle
 */
public function clipCircle($x, $y, $radius, $startAngle = null, $endAngle = null);
            

/**
 * Intersect current clipping area with an ellipse.
 *
 * Method signatures:
 * drawEllipse($x1, $y1, $x2, $y2);
 * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);
 *
 * @todo process special cases with $x2-$x1 == 0 or $y2-$y1 == 0
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param float $startAngle
 * @param float $endAngle
 */
public function clipEllipse($x1, $y1, $x2, $y2, $startAngle = null, $endAngle = null);
            

11.5.12. Styles.

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:

/**
 * Set the style to use for future drawing operations on this page
 *
 * @param Zend_Pdf_Style $style
 */
public function setStyle(Zend_Pdf_Style $style);

/**
 * Return the style, applied to the page.
 *
 * @return Zend_Pdf_Style|null
 */
public function getStyle();
            

Zend_Pdf_Style class provides a set of methods to set or get different graphics state parameters:

/**
 * Set line color.
 *
 * @param Zend_Pdf_Color $color
 */
public function setLineColor(Zend_Pdf_Color $color);
            

/**
 * Get line color.
 *
 * @return Zend_Pdf_Color|null
 */
public function getLineColor();
            

/**
 * Set line width.
 *
 * @param float $width
 */
public function setLineWidth($width);
            

/**
 * Get line width.
 *
 * @return float
 */
public function getLineWidth();
            

/**
 * Set line dashing pattern
 *
 * @param array $pattern
 * @param float $phase
 */
public function setLineDashingPattern($pattern, $phase = 0);
            

/**
 * Get line dashing pattern
 *
 * @return array
 */
public function getLineDashingPattern();
            

/**
 * Get line dashing phase
 *
 * @return float
 */
public function getLineDashingPhase();
            

/**
 * Set fill color.
 *
 * @param Zend_Pdf_Color $color
 */
public function setFillColor(Zend_Pdf_Color $color);
            

/**
 * Get fill color.
 *
 * @return Zend_Pdf_Color|null
 */
public function getFillColor();
            

/**
 * Set current font.
 *
 * @param Zend_Pdf_Font $font
 * @param float $fontSize
 */
public function setFont(Zend_Pdf_Font $font, $fontSize);
            

/**
 * Modify current font size
 *
 * @param float $fontSize
 */
public function setFontSize($fontSize);
            

/**
 * Get current font.
 *
 * @return Zend_Pdf_Font $font
 */
public function getFont();
            

/**
 * Get current font size
 *
 * @return float $fontSize
 */
public function getFontSize();