PDF は PostScript と同じジオメトリを使用します。ページの左下隅を基準とし、 デフォルトではポイント数 (1 インチの 1/72) で場所を指定します。

ページの大きさはページオブジェクトから取得できます。

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

PDF には、色を表現するためのさまざまな方法があります。Zend_Pdf では、 グレイスケール、RGB および CMYK 色空間をサポートしています。 Zend_Pdf_Color オブジェクトが要求される箇所では、 これらのどれでも使用できます。それぞれの色空間に対応する機能を提供するのが Zend_Pdf_Color_GrayScale、Zend_Pdf_Color_Rgb および Zend_Pdf_Color_Cmyk クラスです。

// $grayLevel (float 型の数値)。0.0 (黒) - 1.0 (白)
$color1 = new Zend_Pdf_Color_GrayScale($grayLevel);

// $r, $g, $b (float 型の数値)。0.0 (最低の強度) - 1.0 (最大の強度)
$color2 = new Zend_Pdf_Color_Rgb($r, $g, $b);

// $c, $m, $y, $k (float 型の数値)。0.0 (最小の強度) - 1.0 (最大の強度)
$color3 = new Zend_Pdf_Color_Cmyk($c, $m, $y, $k);

HTML 形式の色指定も Zend_Pdf_Color_Html クラスで使用できます。

$color1 = new Zend_Pdf_Color_Html('#3366FF');
$color2 = new Zend_Pdf_Color_Html('silver');
$color3 = new Zend_Pdf_Color_Html('forestgreen');

描画操作は、PDF のページに対して行われます。

基本図形のセットが Zend_Pdf_Page クラスで提供されています。

/**
 * x1,y1 から x2,y2 まで直線を描画します。
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @return Zend_Pdf_Page
 */
public function drawLine($x1, $y1, $x2, $y2);

/**
 * 矩形を描画します。
 *
 * 描画方法
 * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - 輪郭を描画して塗りつぶします (デフォルト)
 * Zend_Pdf_Page::SHAPE_DRAW_STROKE          - 輪郭を描画します
 * Zend_Pdf_Page::SHAPE_DRAW_FILL            - 矩形を塗りつぶします
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param integer $fillType
 * @return Zend_Pdf_Page
 */
public function drawRectangle($x1, $y1, $x2, $y2,
                    $fillType = Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE);

/**
 * 丸みをつけた矩形を描きます。
 *
 * 描画方法
 * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - 輪郭を描画して塗りつぶします (デフォルト)
 * Zend_Pdf_Page::SHAPE_DRAW_STROKE      - 輪郭を描画します
 * Zend_Pdf_Page::SHAPE_DRAW_FILL        - 矩形を塗りつぶします
 *
 * radius は、４つの角の半径を表す整数、または角の半径を左上から時計回りで示す４つの整数の配列です。
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param integer|array $radius
 * @param integer $fillType
 * @return Zend_Pdf_Page
 */
public function drawRoundedRectangle($x1, $y1, $x2, $y2, $radius,
                       $fillType = Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE);

/**
 * 多角形を描画します。
 *
 * $fillType が Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE あるいは Zend_Pdf_Page::SHAPE_DRAW_FILL
 * の場合、多角形は自動的に閉じられます。このメソッドについての詳細は、
 * PDF のドキュメント (section 4.4.2 Path painting Operators, Filling)
 * を参照ください。
 *
 * @param array $x  - float の配列 (頂点の X 座標)
 * @param array $y  - float の配列 (頂点の Y 座標)
 * @param integer $fillType
 * @param integer $fillMethod
 * @return Zend_Pdf_Page
 */
public function drawPolygon($x, $y,
                            $fillType =
                                Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE,
                            $fillMethod =
                                Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING);

/**
 * 中心が x, y で半径が radius の円を描画します。
 *
 * 角度はラジアンで指定します。
 *
 * Method signatures:
 * drawCircle($x, $y, $radius);
 * drawCircle($x, $y, $radius, $fillType);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle, $fillType);
 *
 *
 * これは本当の円ではありません。PDF は 3 次ベジエ曲線しかサポートしていないからです。
 * とはいえ、本当の円にかなり近くなります。
 * 本当の円との誤差は、最大でも半径の 0.00026 倍にしかなりません
 * (角度が PI/8, 3*PI/8, 5*PI/8, 7*PI/8, 9*PI/8, 11*PI/8, 13*PI/8 そして 15*PI/8 の場合)。
 * 0, PI/4, PI/2, 3*PI/4, PI, 5*PI/4, 3*PI/2 そして 7*PI/4 の場合は、円の正確な接線となります。
 *
 * @param float $x
 * @param float $y
 * @param float $radius
 * @param mixed $param4
 * @param mixed $param5
 * @param mixed $param6
 * @return Zend_Pdf_Page
 */
public function  drawCircle($x,
                            $y,
                            $radius,
                            $param4 = null,
                            $param5 = null,
                            $param6 = null);

/**
 * 指定した矩形に内接する楕円を描画します。
 *
 * 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);
 *
 * 角度はラジアンで指定します。
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param mixed $param5
 * @param mixed $param6
 * @param mixed $param7
 * @return Zend_Pdf_Page
 */
public function drawEllipse($x1,
                            $y1,
                            $x2,
                            $y2,
                            $param5 = null,
                            $param6 = null,
                            $param7 = null);

テキストに対する描画操作も、PDF のページに対して行われます。 ベースラインの x 座標および y 座標を指定することで、 ページ内の任意の場所にテキストを 1 行描画できます。 現在のフォント、フォントサイズおよびページの塗りつぶしの色を使用して、描画操作が行われます (詳細は、以下を参照ください)。

/**
 * 指定した位置にテキストを描画します。
 *
 * @param string $text
 * @param float $x
 * @param float $y
 * @param string $charEncoding (オプション) ソーステキストの文字エンコーディング。
 *   デフォルトは現在のロケールです。
 * @throws Zend_Pdf_Exception
 * @return Zend_Pdf_Page
 */
public function drawText($text, $x, $y, $charEncoding = '');

...
$pdfPage->drawText('Hello world!', 72, 720);
...

...
$pdfPage->setFillColor(Zend_Pdf_Color_Html::color('#990000'))
        ->drawText('Hello world (in red)!', 72, 720);
....

デフォルトでは、現在のロケールのエンコーディングによって テキストの文字列が解釈されます。異なるエンコーディングを使用している場合 (例えば、ディスク上のファイルから UTF-8 の文字列を読み込んだり レガシーなデータベースから MacRoman の文字列を取得したりなど) は、 描画の際に文字エンコーディングを指定できます。 そうすることで、Zend_Pdf が変換処理を行います。PHP の iconv() 関数がサポートしているエンコーディングなら、すべて入力として使用することが可能です。

...
// UTF-8 エンコードされた文字列をディスクから読み込みます
$unicodeString = fread($fp, 1024);

// 文字列をページ上に描画します
$pdfPage->drawText($unicodeString, 72, 720, 'UTF-8');
...

Zend_Pdf_Page::drawText() は、 現在設定されているフォントおよびフォントサイズを使用します。 これは Zend_Pdf_Page::setFont() メソッドで設定できます。

/**
 * 現在のフォントを設定します。
 *
 * @param Zend_Pdf_Resource_Font $font
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFont(Zend_Pdf_Resource_Font $font, $fontSize);

PDF ドキュメントは、PostScript Type 1 フォントおよび TrueType フォントだけでなく、 PDF 用の特別な形式である Type 3 フォントや複合フォントもサポートしています。 すべての PDF ビューアには、以下の 14 種類の標準 Type 1 フォントが組み込まれています。 その内容は Courier (4 種類)、Helvetica (4 種類)、Times (4 種類)、Symbol そして Zapf Dingbats です。

現在 Zend_Pdf は、標準の 14 種類の PDF フォントだけでなく 独自の TrueType フォントもサポートしています。フォントオブジェクトを取得するには、 2 種類のファクトリーメソッドのいずれかを使用します。使用するメソッドは、 標準の 14 種類の PDF フォントの場合は Zend_Pdf_Font::fontWithName($fontName)、 独自のフォントの場合は Zend_Pdf_Font::fontWithPath($filePath) です。

...
// 新しいフォントを作成します。
$font = Zend_Pdf_Font::fontWithName(Zend_Pdf_Font::FONT_HELVETICA);

// フォントを適用します。
$pdfPage->setFont($font, 36);
...

14 種類の標準フォント名を表す定数は、Zend_Pdf_Font クラスで定義されています。

任意の TrueType フォント (通常は '.ttf' という拡張子です) も使用できますし、 TrueType アウトラインを含む OpenType フォント (拡張子は '.otf') を使用することも可能です。現在はまだサポートしていませんが、将来は Mac OS X の .dfont ファイルや Microsoft TrueType Collection (拡張子 '.ttc') ファイルもサポートする予定です。

TrueType フォントを使用するには、フォントへのフルパスを指定しなければなりません。 何らかの理由でフォントが読み込めなかった場合、あるいはそれが TrueType フォントでなかった場合は、ファクトリーメソッドが例外をスローします。

...
// 新しいフォントを作成します
$goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/path/to/GOODDC__.TTF');

// フォントを適用します
$pdfPage->setFont($goodDogCoolFont, 36);
...

デフォルトでは、独自のフォントは PDF ドキュメントに埋め込まれます。 そのため、閲覧者のシステムにそのフォントがインストールされていなくても、 ページをきちんと閲覧できるようになります。ファイルの大きさが気になる場合は、 ファクトリーメソッドのオプションで「フォントを埋め込まない」ことを指定できます。

...
// 新しいフォントを作成します
$goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/path/to/GOODDC__.TTF',
                                               Zend_Pdf_Font::EMBED_DONT_EMBED);

// フォントを適用します
$pdfPage->setFont($goodDogCoolFont, 36);
...

PDF ファイルにフォントが埋め込まれていないけれども 閲覧者のシステムにはそのフォントがインストールされている場合は、ドキュメントは通常通りに閲覧できます。 もし適切なフォントがインストールされていないは、PDF 閲覧アプリケーションが適切な代替フォントを選択します。

中には、PDF ドキュメントへの埋め込みを禁止するようなライセンスを使用しているフォントもあります。 これをあなどってはいけません。もし埋め込めないフォントを利用しようとすると、 ファクトリーメソッドは例外をスローします。

このようなフォントを使用することも可能ですが、そのためには、 上で説明した「埋め込まない」フラグを使用するか、あるいは例外を抑制しなければなりません。

...
$font = Zend_Pdf_Font::fontWithPath(
           '/path/to/unEmbeddableFont.ttf',
           Zend_Pdf_Font::EMBED_SUPPRESS_EMBED_EXCEPTION
        );
...

利用者にフォントを選択させる場合などは、この抑制方法を使用することをお勧めします。 PDF ドキュメントに埋め込めるフォントなら埋め込むでしょうし、 埋め込めないフォントは埋め込まないでしょう。

フォントのサイズは比較的大きく、中には 10 メガバイトに達するものもあります。 デフォルトでは埋め込みフォントは Flate 圧縮され、平均して 50% ほどサイズを節約できます。 何らかの理由でフォントを圧縮したくない場合は、以下のオプションで圧縮を無効にできます。

...
$font = Zend_Pdf_Font::fontWithPath('/path/to/someReallyBigFont.ttf',
                                    Zend_Pdf_Font::EMBED_DONT_COMPRESS);
...

最後に、必要に応じていくつかの埋め込みオプションをビット OR 演算子で連結することもできます。

...
$font = Zend_Pdf_Font::fontWithPath(
            $someUserSelectedFontPath,
            (Zend_Pdf_Font::EMBED_SUPPRESS_EMBED_EXCEPTION |
            Zend_Pdf_Font::EMBED_DONT_COMPRESS));
...

標準 PDF フォントは、いくつかのシングルバイトエンコーディング (詳細は PDF Reference, Sixth Edition, version 1.7 の Appendix D を参照ください) を内部的に使用しています。 これらは、ほぼ Latin1 文字セットと同じものです (Symbol フォントと ZapfDingbats フォントは例外です)。

Zend_Pdf は、標準フォントでのテキストの描画時に CP1252 (WinLatin1) を使用します。

他のエンコーディングでもテキストは描画できますが、 現在のロケールと異なる場合はそれを指定する必要があります。 実際に描画されるのは WinLatin1 の文字のみです。

...
$font = Zend_Pdf_Font::fontWithName(Zend_Pdf_Font::FONT_COURIER);
$pdfPage->setFont($font, 36)
        ->drawText('Euro sign - €', 72, 720, 'UTF-8')
        ->drawText('Text with umlauts - à è ì', 72, 650, 'UTF-8');
...

Zend_Pdf モジュールを使用すると、読み込んだドキュメントからフォントを抽出できるようになります。

これは、ドキュメントをインクリメンタルに更新する際に便利です。 この機能がなければ、ドキュメントを更新するたびにフォントをアタッチしたり ドキュメントに埋め込んだりしなければならなくなります。

Zend_Pdf オブジェクトおよび Zend_Pdf_Page オブジェクトには、 ドキュメントやページ内のすべてのフォントを抽出するためのメソッドが用意されています。

...
$pdf = Zend_Pdf::load($documentPath);
...
// ドキュメントのすべてのフォントを取得します
$fontList = $pdf->extractFonts();
$pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));
$yPosition = 700;
foreach ($fontList as $font) {
    $page->setFont($font, 15);
    $fontName = $font->getFontName(Zend_Pdf_Font::NAME_POSTSCRIPT,
                                   'en',
                                   'UTF-8');
    $page->drawText($fontName . ': The quick brown fox jumps over the lazy dog',
                    100,
                    $yPosition,
                    'UTF-8');
    $yPosition -= 30;
}
...
// ドキュメントの最初のページで用いられているフォントを取得します
$firstPage = reset($pdf->pages);
$firstPageFonts = $firstPage->extractFonts();
...

...
$pdf = new Zend_Pdf();
...
$pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));

$font = Zend_Pdf_Font::fontWithPath($fontPath);
$page->setFont($font, $fontSize);
$page->drawText($text, $x, $y);
...
// フォント名をどこかに保存しておきます...
$fontName = $font->getFontName(Zend_Pdf_Font::NAME_POSTSCRIPT,
                               'en',
                               'UTF-8');
...
$pdf->save($docPath);
...

...
$pdf = Zend_Pdf::load($docPath);
...
$pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));

/* $srcPage->extractFont($fontName) としてもかまいません */
$font = $pdf->extractFont($fontName);

$page->setFont($font, $fontSize);
$page->drawText($text, $x, $y);
...
$pdf->save($docPath, true /* インクリメンタル更新モード */);
...

フォントの抽出はどこででもできますが、次のような制限があります。

Zend_Pdf_Page クラスの drawImage() メソッドで、 画像の描画を行います。

/**
 * ページ内の指定した位置に画像を描画します。
 *
 * @param Zend_Pdf_Resource_Image $image
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @return Zend_Pdf_Page
 */
public function drawImage(Zend_Pdf_Resource_Image $image, $x1, $y1, $x2, $y2);

画像オブジェクトは、Zend_Pdf_Image::imageWithPath($filePath) メソッドで作成しなければなりません (現在は JPG、PNG および TIFF 画像をサポートしています)。

...
// 画像を読み込みます
$image = Zend_Pdf_Image::imageWithPath('my_image.jpg');

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

重要! JPEG のサポートには PHP の GD 拡張モジュールを必要とします。 重要! PNG でアルファチャネルを使用した画像を扱うには、ZLIB 拡張モジュールを必要とします。

詳細な情報は、PHP のドキュメント (http://www.php.net/manual/ja/ref.image.php), (http://www.php.net/manual/ja/ref.zlib.php) を参照ください。

直線の描画スタイルは、線幅と線の色、そして破線のパターンで定義されます。 これらはすべて、Zend_Pdf_Page クラスのメソッドで設定します。

/** 線の色を設定します。*/
public function setLineColor(Zend_Pdf_Color $color);

/** 線の幅を設定します。*/
public function setLineWidth(float $width);

/**
 * 破線のパターンを設定します。
 *
 * pattern は float の配列です:
 *     array(on_length, off_length, on_length, off_length, ...)
 * phase は線の開始位置から移動する距離です。
 *
 * @param array $pattern
 * @param array $phase
 * @return Zend_Pdf_Page
 */
public function setLineDashingPattern($pattern, $phase = 0);

Zend_Pdf_Page::drawRectangle()、Zend_Pdf_Page::drawPolygon()、 Zend_Pdf_Page::drawCircle() および Zend_Pdf_Page::drawEllipse() メソッドは、オプションのパラメータとして $fillType を受け取ります。これは以下のいずれかの値となります。

Zend_Pdf_Page::drawPolygon() メソッドには、さらにパラメータ $fillMethod を指定できます。

好きな時点でのグラフィックの状態 (現在のフォント、フォントサイズ、線の色、塗りつぶしの色、線の形式、 ページの回転、クリップ領域) を保存/復元できます。 保存操作はグラフィックの状態をスタックに保存し、復元の際にはそこから取り出されます。

Zend_Pdf_Page クラスには、これらの操作を行うための 2 つのメソッドがあります。

/**
 * このページのグラフィックの状態を保存します。
 * 現在適用されているスタイル・位置・クリップ領域および
 * 回転/移動/拡大縮小などを情報を保存します。
 *
 * @return Zend_Pdf_Page
 */
public function saveGS();

/**
 * 直近の saveGS() で保存されたグラフィックの状態を復元します。
 *
 * @return Zend_Pdf_Page
 */
public function restoreGS();

PDF および Zend_Pdf モジュールは、描画領域のクリッピングに対応しています。 描画演算子が影響を及ぼす範囲を、このクリップ領域内に制限します。 クリップ領域の初期値は、ページ全体です。

Zend_Pdf_Page クラスでは、 クリッピングに関連するいくつかのメソッドを提供しています。

/**
 * 矩形のクリップ領域を設定します。
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @return Zend_Pdf_Page
 */
public function clipRectangle($x1, $y1, $x2, $y2);

/**
 * 多角形のクリップ領域を設定します。
 *
 * @param array $x  - float の配列 (頂点の X 座標)
 * @param array $y  - float の配列 (頂点の Y 座標)
 * @param integer $fillMethod
 * @return Zend_Pdf_Page
 */
public function clipPolygon($x,
                            $y,
                            $fillMethod =
                                Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING);

/**
 * 円形のクリップ領域を設定します。
 *
 * @param float $x
 * @param float $y
 * @param float $radius
 * @param float $startAngle
 * @param float $endAngle
 * @return Zend_Pdf_Page
 */
public function clipCircle($x,
                           $y,
                           $radius,
                           $startAngle = null,
                           $endAngle = null);

/**
 * 楕円のクリップ領域を設定します。
 *
 * メソッドの書式
 * drawEllipse($x1, $y1, $x2, $y2);
 * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);
 *
 * @todo $x2-$x1 == 0 や $y2-$y1 == 0 のような特別な場合への対応
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param float $startAngle
 * @param float $endAngle
 * @return Zend_Pdf_Page
 */
public function clipEllipse($x1,
                            $y1,
                            $x2,
                            $y2,
                            $startAngle = null,
                            $endAngle = null);

Zend_Pdf_Style クラスがスタイルに関する機能を提供します。

スタイルは、グラフィックの状態に関する複数の設定を保存し、 PDF のページに 1 回の操作でそれを適用するために使用されます。

/**
 * このページの描画操作で使用する予定のスタイルを設定します。
 *
 * @param Zend_Pdf_Style $style
 * @return Zend_Pdf_Page
 */
public function setStyle(Zend_Pdf_Style $style);

/**
 * スタイルを返し、それをページに適用します。
 *
 * @return Zend_Pdf_Style|null
 */
public function getStyle();

Zend_Pdf_Style クラスでは、 さまざまなグラフィックの状態を設定あるいは取得するためのメソッドが提供されています。

/**
 * 線の色を設定します。
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setLineColor(Zend_Pdf_Color $color);

/**
 * 線の色を取得します。
 *
 * @return Zend_Pdf_Color|null
 */
public function getLineColor();

/**
 * 線の幅を設定します。
 *
 * @param float $width
 * @return Zend_Pdf_Page
 */
public function setLineWidth($width);

/**
 * 線の幅を取得します。
 *
 * @return float
 */
public function getLineWidth();

/**
 * 破線のパターンを設定します。
 *
 * @param array $pattern
 * @param float $phase
 * @return Zend_Pdf_Page
 */
public function setLineDashingPattern($pattern, $phase = 0);

/**
 * 破線のパターンを取得します。
 *
 * @return array
 */
public function getLineDashingPattern();

/**
 * 破線の位相を取得します。
 *
 * @return float
 */
public function getLineDashingPhase();

/**
 * 塗りつぶし色を設定します。
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setFillColor(Zend_Pdf_Color $color);

/**
 * 塗りつぶし色を取得します。
 *
 * @return Zend_Pdf_Color|null
 */
public function getFillColor();

/**
 * 現在のフォントを設定します。
 *
 * @param Zend_Pdf_Resource_Font $font
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFont(Zend_Pdf_Resource_Font $font, $fontSize);

/**
 * 現在のフォントサイズを変更します。
 *
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFontSize($fontSize);

/**
 * 現在のフォントを取得します。
 *
 * @return Zend_Pdf_Resource_Font $font
 */
public function getFont();

/**
 * 現在のフォントサイズを取得します。
 *
 * @return float $fontSize
 */
public function getFontSize();

Zend_Pdf モジュールは、透明度の処理に対応しています。

透明度を設定するには Zend_Pdf_Page::setAlpha() メソッドを使用します。

/**
 * 透明度を設定します
 *
 * $alpha == 0  - 透明
 * $alpha == 1  - 不透明
 *
 * PDF でサポートするモードは次のとおりです
 * Normal (デフォルト), Multiply, Screen, Overlay, Darken, Lighten,
 * ColorDodge, ColorBurn, HardLight, SoftLight, Difference, Exclusion
 *
 * @param float $alpha
 * @param string $mode
 * @throws Zend_Pdf_Exception
 * @return Zend_Pdf_Page
 */
public function setAlpha($alpha, $mode = 'Normal');